Skip to content

Get Started

Jump to bottom
André Secco edited this page Jun 30, 2019 · 18 revisions

For all requests, you will need to instantiate the LuisProgClient class, passing your authoring key and their respective Azure region.

Use the namespace: Cognitive.LUIS.Programmatic

Available Regions:

  • WestUS
  • WestEurope
  • AustraliaEast

* This guide is valid for 1.2.0 version

Ex:

var client = new LuisProgClient("Your_Authoring_Key", Regions.WestUS);
...
client.Dispose();

OR

using (var client = new LuisProgClient("Your_Authoring_Key", Regions.WestUS))
{
    ...
}

Where is my Authoring Key? Check this link: Undestand your LUIS keys

Below, you can see some examples:

Apps

Getting apps

1) Get all:

//Returns IReadOnlyCollection<LuisApp>
var apps = await client.Apps.GetAllAsync();

By default, this method returns until 100 results.
Optionally, you can specificate the "skip" and "take" parameters to get more results:

//Returns IReadOnlyCollection<LuisApp>
var apps = await client.Apps.GetAllAsync(skip: 100, take: 500);

skip: The number of entries to skip. Default value is 0.
take: The number of entries to return. Maximum page size is 500. Default is 100.

2) Get by id:

//Returns a LuisApp
var apps = await client.Apps.GetAllAsync("24d2a592-165d-468f-8800-7778900afc11");

3) Get by name

//Returns a LuisApp
var apps = await client.Apps.GetByNameAsync("AppTest");

Create apps

//Returns app id
var appId = await client.Apps.AddAsync(
    name: "AppTest",
    description: "App description",
    culture: "en-us",
    usageScenario: "SDK Test",
    domain: "Testing",
    initialVersionId: "0.1"
);

Rename apps

//Returns a task
await client.Apps.RenameAsync(
    id: "24d2a592-165d-468f-8800-7778900afc11",
    name: "NewNameApp",
    description: "New app description"
);

Delete apps

//Returns a task
await client.Apps.DeleteAsync(id: "24d2a592-165d-468f-8800-7778900afc11");

Intents

Getting app intents

1) Get all:

//Returns IReadOnlyCollection<Intent>
var intents = await client.Intents.GetAllAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

By default, this method returns until 100 results.
Optionally, you can specificate the "skip" and "take" parameters to get more results:

//Returns IReadOnlyCollection<Intent>
var intents = await client.Intents.GetAllAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1",
   skip: 100,
   take: 500
);

skip: The number of entries to skip. Default value is 0.
take: The number of entries to return. Maximum page size is 500. Default is 100.

2) Get by id:

//Returns an intent
var intent = await client.Intents.GetByIdAsync(
    id : "0f1d3aa8-e397-42d1-a1d0-de2529c36c4b",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

3) Get by name

//Returns an intent
var intent = await client.Intents.GetByNameAsync(
    name : "IntentTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Create intents

//Returns intent id
var intentId = await client.Intents.AddAsync(
    name: "IntentTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Rename intents

//Returns a task
await client.Intents.RenameAsync(
    id: "0f1d3aa8-e397-42d1-a1d0-de2529c36c4b",
    name: "NewIntent",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Delete intents

//Returns a task
await client.Intents.DeleteAsync(
    id: "0f1d3aa8-e397-42d1-a1d0-de2529c36c4b",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1",
    deleteUtterances: true
);

deleteUtterances is an optional parameter (default is false): true means delete utterances from app, false means move utterances to None intent.

Entities

Getting app entities

1) Get all:

//Simple entities
//Returns IReadOnlyCollection<Entity>
var entities = await client.Entities.GetAllSimpleEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

//Composite entities
//Returns IReadOnlyCollection<CompositeEntity>
var entities = await client.Entities.GetAllCompositeEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

//ClosedList entities
//Returns IReadOnlyCollection<ClosedListEntity>
var entities = await client.Entities.GetAllClosedListEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

//Regex entities
//Returns IReadOnlyCollection<RegexEntity>
var entities = await client.Entities.GetAllRegexEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

//PatternAny entities
//Returns IReadOnlyCollection<PatternAnyEntity>
var entities = await client.Entities.GetAllPatternAnyEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

By default, this method returns until 100 results.
Optionally, you can specificate the "skip" and "take" parameters to get more results:

//Simple entities
//Returns IReadOnlyCollection<Entity>
var entities = await client.Entities.GetAllSimpleEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
   skip: 100,
   take: 500
);

//Composite entities
//Returns IReadOnlyCollection<CompositeEntity>
var entities = await client.Entities.GetAllCompositeEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
   skip: 100,
   take: 500
);

//ClosedList entities
//Returns IReadOnlyCollection<ClosedListEntity>
var entities = await client.Entities.GetAllClosedListEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
   skip: 100,
   take: 500
);

//Regex entities
//Returns IReadOnlyCollection<RegexEntity>
var entities = await client.Entities.GetAllRegexEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
   skip: 100,
   take: 500
);

//PatternAny entities
//Returns IReadOnlyCollection<PatternAnyEntity>
var entities = await client.Entities.GetAllPatternAnyEntitiesAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
   skip: 100,
   take: 500
);

skip: The number of entries to skip. Default value is 0.
take: The number of entries to return. Maximum page size is 500. Default is 100.

2) Get by id:

//Returns an simple entity
var entity = await client.Entities.GetSimpleEntityByIdAsync(
    id : "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an composite entity
var entity = await client.Entities.GetCompositeEntityByIdAsync(
    id : "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an closed list entity
var entity = await client.Entities.GetClosedListEntityByIdAsync(
    id : "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an regex entity
var entity = await client.Entities.GetRegexEntityByIdAsync(
    id : "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an pattern any entity
var entity = await client.Entities.GetPatternAnyEntityByIdAsync(
    id : "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

3) Get by name

//Returns an simple entity
var entity = await client.Entities.GetSimpleEntityByNameAsync(
    name : "EntityTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an composite entity
var entity = await client.Entities.GetCompositeEntityByNameAsync(
    name : "EntityTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an closed list entity
var entity = await client.Entities.GetClosedListEntityByNameAsync(
    name : "EntityTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an regex entity
var entity = await client.Entities.GetRegexEntityByNameAsync(
    name : "EntityTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Returns an pattern any entity
var entity = await client.Entities.GetPatternAnyEntityByNameAsync(
    name : "EntityTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Create entities

//Simple entity
//Returns entity id
var entityId = await client.Entities.AddSimpleEntityAsync(
    name: "EntityTest",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Composite entity
//Returns entity id
var entityId = await client.Entities.AddCompositeEntityAsync(
    name: "EntityTest",
    children: new[] { "OtherExistingEntityName1", "OtherExistingEntityName2" },
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//ClosedList entity
//Returns entity id
var entityId = await client.Entities.AddClosedListEntityAsync(
    name: "StatesEntityTest",
    subLists: new ClosedListItem[] 
    {
        new ClosedListItem() { CanonicalForm = "New York", List = new[] { "NY", "New York" } }
    },
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Regex entity
//Returns entity id
var entityId = await client.Entities.AddRegexEntityAsync(
    name: "EntityTest",
    regexPattern: "[0-9]-[0-9]",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//PatternAny entity
//Returns entity id
var entityId = await client.Entities.AddPatternAnyEntityAsync(
    name: "EntityTest",
    explicitList: new[] { "item1", "item2" },
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Rename entities

//Returns a task
await client.Entities.RenameAsync(
    id: "6a90c45a-6eae-49ba-9744-34187296d586",
    name: "NewEntity",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);
  • This method works for any type of entity.

Delete entities

//Simple entity
//Returns a task
await client.Entities.DeleteSimpleEntityAsync(
    id: "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Composite entity
//Returns a task
await client.Entities.DeleteCompositeEntityAsync(
    id: "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Closed list entity
//Returns a task
await client.Entities.DeleteClosedListEntityAsync(
    id: "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Regex entity
//Returns a task
await client.Entities.DeleteRegexEntityAsync(
    id: "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

//Pattern any entity
//Returns a task
await client.Entities.DeletePatternAnyEntityAsync(
    id: "6a90c45a-6eae-49ba-9744-34187296d586",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Utterances

Add labeled example to the app

var utterance = await client.Examples.AddAsync(
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1",
    new Example
    {
        Text = "Hello World!",
        IntentName = "IntentTest", //intent name (previous created)
        EntityLabels = new List<EntityLabel>
        {
            new EntityLabel
            {
                EntityName = "Greeting", //entity name (previous created)
                StartCharIndex = 0,
                EndCharIndex = 4
            }
        }
    }
);

Add a batch of labeled examples to the app

var examples = new List<Example>();
examples.Add(new Example
{
    Text = "Hello World!",
    IntentName = IntentName
});

examples.Add(new Example
{
    Text = "This is a test Utterance",
    IntentName = IntentName
});

//Returns BatchExample[]
var utterances = await client.Examples.AddBatchAsync(
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1",
    models: examples.ToArray()
);

* The maximum batch size is 100 items.

Getting/Review labeled examples

//Returns IReadOnlyCollection<ReviewExample>
var examples = await client.Examples.GetAllAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
);

By default, this method returns until 100 results.
Optionally, you can specificate the "skip" and "take" parameters to get more results:

//Returns IReadOnlyCollection<ReviewExample>
var examples = await client.Examples.GetAllAsync(
   appId: "24d2a592-165d-468f-8800-7778900afc11",
   appVersionId: "0.1"
   skip: 100,
   take: 500
);

skip: The number of entries to skip. Default value is 0.
take: The number of entries to return. Maximum page size is 500. Default is 100.

Delete example labels

//Returns a task
await client.Examples.DeleteAsync(
    id: "9b723179-8c47-4dc9-898f-3d04c7c4d6b1",
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Train

Sends a training request

//Returns the training details
var details = await client.Training.TrainAsync(
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Gets the training status of all models (intents and entities)

//Returns the training list
var trainingList = await client.Training.GetStatusListAsync(
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1"
);

Sends a training request and get final status

//Returns the training details
var trainingDetails = await client.Training.TrainAndGetFinalStatusAsync(
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1",
    timeout: 120 //Maximum wait time to return the final status (in seconds). Default is 60 seconds
);

Publish

//Returns the publish details
var publishDetails = await client.Publishing.PublishAsync(
    appId: "24d2a592-165d-468f-8800-7778900afc11",
    appVersionId: "0.1",
    isStaging: false,
    directVersionPublish: false
);

isStaging: This flag should be set to true in case you want to publish to the STAGING slot, otherwise the application version will be published to the PRODUCTION slot.
directVersionPublish: In case you do not want to publish to either the PRODUCTION or STAGING slots, you can set the flag "directVersionPublish" to true and query the endpoint [directly using the versionId] (https://westus.dev.cognitive.microsoft.com/docs/services/luis-endpoint-api-v3-0-preview/operations/5cb0a9459a1fe8fa44c28dd8).

Clone this wiki locally