How to update the LUIS model with REST APIs

Reference documentation | Sample

Prerequisites

• .NET Core 3.1
• Visual Studio Code

Example utterances JSON file

The example utterances follow a specific format.

The text field contains the text of the example utterance. The intentName field must correspond to the name of an existing intent in the LUIS app. The entityLabels field is required. If you don't want to label any entities, provide an empty array.

If the entityLabels array is not empty, the startCharIndex and endCharIndex need to mark the entity referred to in the entityName field. The index is zero-based. If you begin or end the label at a space in the text, the API call to add the utterances fails.

[
  {
    "text": "order a pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "order a large pepperoni pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 14,
        "endCharIndex": 28
      },
      {
        "entityName": "Size",
        "startCharIndex": 8,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "I want two large pepperoni pizzas on thin crust",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 17,
        "endCharIndex": 32
      },
      {
        "entityName": "Size",
        "startCharIndex": 11,
        "endCharIndex": 15
      },
      {
        "entityName": "Quantity",
        "startCharIndex": 7,
        "endCharIndex": 9
      },
      {
        "entityName": "Crust",
        "startCharIndex": 37,
        "endCharIndex": 46
      }
    ]
  }
]

Create Pizza app

Create the pizza app.

1. Select pizza-app-for-luis-v6.json to bring up the GitHub page for the pizza-app-for-luis.json file.
2. Right-click or long tap the Raw button and select Save link as to save the pizza-app-for-luis.json to your computer.
3. Sign into the LUIS portal.
4. Select My Apps.
5. On the My Apps page, select + New app for conversation.
6. Select Import as JSON.
7. In the Import new app dialog, select the Choose File button.
8. Select the pizza-app-for-luis.json file you downloaded, then select Open.
9. In the Import new app dialog Name field, enter a name for your Pizza app, then select the Done button.

The app will be imported.

If you see a dialog How to create an effective LUIS app, close the dialog.

Train and publish the Pizza app

You should see the Intents page with a list of the intents in the Pizza app.

1. In the top-right side of the LUIS website, select the Train button.

   

2. Training is complete when the Train button is disabled.

In order to receive a LUIS prediction in a chat bot or other client applications, you need to publish the app to the prediction endpoint.

1. Select Publish in the top-right navigation.

   

2. Select the Production slot, then select Done.

   

3. Select Access your endpoint URLs in the notification to go to the Azure Resources page. You will only be able to see the URLs if you have a prediction resource associated with the app. You can also find the Azure Resources page by clicking Manage.

   

Add an authoring resource to the Pizza app

1. Select MANAGE.
2. Select Azure Resources.
3. Select Authoring Resource.
4. Select Change authoring resource.

If you have an authoring resource, enter the Tenant Name, Subscription Name, and LUIS resource name of your authoring resource.

If you do not have an authoring resource:

1. Select Create new resource.
2. Enter a Tenant Name, Resource Name, Subscription Name, and Azure Resource Group Name.

Your Pizza app is now ready to use.

Record the access values for your Pizza app

To use your new Pizza app, you will need the app ID, authoring key, and authoring endpoint of your Pizza app. To get predictions, you will need your separate prediction endpoint and prediction key.

To find these values:

1. From the Intents page, select MANAGE.
2. From the Application Settings page, record the App ID.
3. Select Azure Resources.
4. Select Authoring Resource.
5. From the Authoring Resource and Prediction Resources tabs, record the Primary Key. This value is your authoring key.
6. Record the Endpoint URL. This value is your authoring endpoint.

Change model programmatically

1. Create a new console application targeting the C# language, with a project and folder name of csharp-model-with-rest.

   dotnet new console -lang C# -n csharp-model-with-rest
   

2. Change to the csharp-model-with-rest directory you created, and install required dependencies with these commands:

   cd csharp-model-with-rest
   dotnet add package System.Net.Http
   dotnet add package JsonFormatterPlus
   

3. Overwrite Program.cs with the following code:

//
// This quickstart shows how to add utterances to a LUIS model using the REST APIs.
//

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using System.Collections.Generic;
using System.Linq;

// 3rd party NuGet packages
using JsonFormatterPlus;

namespace AddUtterances
{
    class Program
    {
        //////////
        // Values to modify.

        // YOUR-APP-ID: The App ID GUID found on the luis.azure.cn Application Settings page.
        static string appID = "PASTE_YOUR_LUIS_APP_ID_HERE";

        // YOUR-AUTHORING-KEY: Your LUIS authoring key, 32 character value.
        static string authoringKey = "PASTE_YOUR_LUIS_AUTHORING_SUBSCRIPTION_KEY_HERE";

        // YOUR-AUTHORING-ENDPOINT: Replace this endpoint with your authoring key endpoint.
        // For example, "https://your-resource-name.cognitiveservices.azure.cn/"
        static string authoringEndpoint = "PASTE_YOUR_LUIS_AUTHORING_ENDPOINT_HERE";

        // NOTE: Replace this your version number.
        static string appVersion = "0.1";
        //////////

        static string host = String.Format("{0}luis/authoring/v3.0-preview/apps/{1}/versions/{2}/", authoringEndpoint, appID, appVersion);

        // GET request with authentication
        async static Task<HttpResponseMessage> SendGet(string uri)
        {
            using (var client = new HttpClient())
            using (var request = new HttpRequestMessage())
            {
                request.Method = HttpMethod.Get;
                request.RequestUri = new Uri(uri);
                request.Headers.Add("Ocp-Apim-Subscription-Key", authoringKey);
                return await client.SendAsync(request);
            }
        }

        // POST request with authentication
        async static Task<HttpResponseMessage> SendPost(string uri, string requestBody)
        {
            using (var client = new HttpClient())
            using (var request = new HttpRequestMessage())
            {
                request.Method = HttpMethod.Post;
                request.RequestUri = new Uri(uri);

                if (!String.IsNullOrEmpty(requestBody))
                {
                    request.Content = new StringContent(requestBody, Encoding.UTF8, "text/json");
                }

                request.Headers.Add("Ocp-Apim-Subscription-Key", authoringKey);
                return await client.SendAsync(request);
            }
        }

        // Add utterances as string with POST request
        async static Task AddUtterances(string utterances)
        {
            string uri = host + "examples";

            var response = await SendPost(uri, utterances);
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Added utterances.");
            Console.WriteLine(JsonFormatter.Format(result));
        }

        // Train app after adding utterances
        async static Task Train()
        {
            string uri = host  + "train";

            var response = await SendPost(uri, null);
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Sent training request.");
            Console.WriteLine(JsonFormatter.Format(result));
        }

        // Check status of training
        async static Task Status()
        {
            var response = await SendGet(host  + "train");
            var result = await response.Content.ReadAsStringAsync();
            Console.WriteLine("Requested training status.");
            Console.WriteLine(JsonFormatter.Format(result));
        }

        // Add utterances, train, check status
        static void Main(string[] args)
        {
            string utterances = @"
            [
                {
                    'text': 'order a pizza',
                    'intentName': 'ModifyOrder',
                    'entityLabels': [
                        {
                            'entityName': 'Order',
                            'startCharIndex': 6,
                            'endCharIndex': 12
                        }
                    ]
                },
                {
                    'text': 'order a large pepperoni pizza',
                    'intentName': 'ModifyOrder',
                    'entityLabels': [
                        {
                            'entityName': 'Order',
                            'startCharIndex': 6,
                            'endCharIndex': 28
                        },
                        {
                            'entityName': 'FullPizzaWithModifiers',
                            'startCharIndex': 6,
                            'endCharIndex': 28
                        },
                        {
                            'entityName': 'PizzaType',
                            'startCharIndex': 14,
                            'endCharIndex': 28
                        },
                        {
                            'entityName': 'Size',
                            'startCharIndex': 8,
                            'endCharIndex': 12
                        }
                    ]
                },
                {
                    'text': 'I want two large pepperoni pizzas on thin crust',
                    'intentName': 'ModifyOrder',
                    'entityLabels': [
                        {
                            'entityName': 'Order',
                            'startCharIndex': 7,
                            'endCharIndex': 46
                        },
                        {
                            'entityName': 'FullPizzaWithModifiers',
                            'startCharIndex': 7,
                            'endCharIndex': 46
                        },
                        {
                            'entityName': 'PizzaType',
                            'startCharIndex': 17,
                            'endCharIndex': 32
                        },
                        {
                            'entityName': 'Size',
                            'startCharIndex': 11,
                            'endCharIndex': 15
                        },
                        {
                            'entityName': 'Quantity',
                            'startCharIndex': 7,
                            'endCharIndex': 9
                        },
                        {
                            'entityName': 'Crust',
                            'startCharIndex': 37,
                            'endCharIndex': 46
                        }
                    ]
                }
            ]
            ";

            AddUtterances(utterances).Wait();
            Train().Wait();
            Status().Wait();
        }
    }
}

1. Replace the values starting with YOUR- with your own values.

   Information	Purpose
   YOUR-APP-ID	Your LUIS app ID.
   YOUR-AUTHORING-KEY	Your 32 character authoring key.
   YOUR-AUTHORING-ENDPOINT	Your authoring URL endpoint. For example, https://replace-with-your-resource-name.api.cognitive.azure.cn/. You set your resource name when you created the resource.

   Assigned keys and resources are visible in the LUIS portal in the Manage section, on the Azure resources page. The app ID is available in the same Manage section, on the Application Settings page.

   Important

   Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.

2. Build the console application.

   dotnet build
   

3. Run the console application.

   dotnet run
   

4. Review the authoring response:

   Added utterances.
   [
       {
           "value": {
               "ExampleId": 1137150691,
               "UtteranceText": "order a pizza"
           },
           "hasError": false
       },
       {
           "value": {
               "ExampleId": 1137150692,
               "UtteranceText": "order a large pepperoni pizza"
           },
           "hasError": false
       },
       {
           "value": {
               "ExampleId": 1137150693,
               "UtteranceText": "i want two large pepperoni pizzas on thin crust"
           },
           "hasError": false
       }
   ]
   Sent training request.
   {
       "statusId": 9,
       "status": "Queued"
   }
   Requested training status.
   [
       {
           "modelId": "edb46abf-0000-41ab-beb2-a41a0fe1630f",
           "details": {
               "statusId": 9,
               "status": "Queued",
               "exampleCount": 0
           }
       },
       {
           "modelId": "a5030be2-616c-4648-bf2f-380fa9417d37",
           "details": {
               "statusId": 9,
               "status": "Queued",
               "exampleCount": 0
           }
       },
       {
           "modelId": "3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9",
           "details": {
               "statusId": 9,
               "status": "Queued",
               "exampleCount": 0
           }
       },
       {
           "modelId": "e4b6704b-1636-474c-9459-fe9ccbeba51c",
           "details": {
               "statusId": 9,
               "status": "Queued",
               "exampleCount": 0
           }
       },
       {
           "modelId": "031d3777-2a00-4a7a-9323-9a3280a30000",
           "details": {
               "statusId": 9,
               "status": "Queued",
               "exampleCount": 0
           }
       },
       {
           "modelId": "9250e7a1-06eb-4413-9432-ae132ed32583",
           "details": {
               "statusId": 9,
               "status": "Queued",
               "exampleCount": 0
           }
       }
   ]
   

Clean up resources

When you are finished with this quickstart, delete the project folder from the file system.

Next steps

Best practices for an app

Reference documentation | Sample

Prerequisites

• JDK SE (Java Development Kit, Standard Edition)
• Visual Studio Code or your favorite IDE

Example utterances JSON file

The example utterances follow a specific format.

The text field contains the text of the example utterance. The intentName field must correspond to the name of an existing intent in the LUIS app. The entityLabels field is required. If you don't want to label any entities, provide an empty array.

If the entityLabels array is not empty, the startCharIndex and endCharIndex need to mark the entity referred to in the entityName field. The index is zero-based. If you begin or end the label at a space in the text, the API call to add the utterances fails.

[
  {
    "text": "order a pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "order a large pepperoni pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 14,
        "endCharIndex": 28
      },
      {
        "entityName": "Size",
        "startCharIndex": 8,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "I want two large pepperoni pizzas on thin crust",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 17,
        "endCharIndex": 32
      },
      {
        "entityName": "Size",
        "startCharIndex": 11,
        "endCharIndex": 15
      },
      {
        "entityName": "Quantity",
        "startCharIndex": 7,
        "endCharIndex": 9
      },
      {
        "entityName": "Crust",
        "startCharIndex": 37,
        "endCharIndex": 46
      }
    ]
  }
]

Change model programmatically

1. Create a new folder to hold your Java project, such as java-model-with-rest.

2. Make a subdirectory named lib and copy in the following Java libs into the lib subdirectory:

   • commons-logging-1.2.jar
   • httpclient-4.5.3.jar
   • httpcore-4.4.6.jar

3. Create a new file named Model.java. Add the following code:

//
// This quickstart shows how to add utterances to a LUIS model using the REST APIs.
//

import java.io.*;
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

// To compile, execute this command at the console:
//      Windows: javac -cp ";lib/*" Model.java
//      macOs: javac -cp ":lib/*" Model.java
//      Linux: javac -cp ":lib/*" Model.java

// To run, execute this command at the console:
//      Windows: java -cp ";lib/*" Model
//      macOs: java -cp ":lib/*" Model
//      Linux: java -cp ":lib/*" Model

public class Model
{
    public static void main(String[] args)
    {
        try
        {
            //////////
            // Values to modify.

            // YOUR-APP-ID: The App ID GUID found on the luis.azure.cn Application Settings page.
            String AppId = "PASTE_YOUR_LUIS_APP_ID_HERE";

            // YOUR-AUTHORING-KEY: Your LUIS authoring key, 32 character value.
            String Key = "PASTE_YOUR_LUIS_AUTHORING_SUBSCRIPTION_KEY_HERE";

            // YOUR-AUTHORING-ENDPOINT: Replace this with your authoring key endpoint.
            // For example, "https://your-resource-name.cognitiveservices.azure.cn/"
            String Endpoint = "PASTE_YOUR_LUIS_AUTHORING_ENDPOINT_HERE";

            // NOTE: Replace this your version number. The Pizza app uses a version number of "0.1".
            String Version = "0.1";
            //////////

            // The list of utterances to add, in JSON format.
            String Utterances = "[{'text': 'order a pizza', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 6, 'endCharIndex': 12}]}, {'text': 'order a large pepperoni pizza', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 6, 'endCharIndex': 28}, {'entityName': 'FullPizzaWithModifiers', 'startCharIndex': 6, 'endCharIndex': 28}, {'entityName': 'PizzaType', 'startCharIndex': 14, 'endCharIndex': 28}, {'entityName': 'Size', 'startCharIndex': 8, 'endCharIndex': 12}]}, {'text': 'I want two large pepperoni pizzas on thin crust', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 7, 'endCharIndex': 46}, {'entityName': 'FullPizzaWithModifiers', 'startCharIndex': 7, 'endCharIndex': 46}, {'entityName': 'PizzaType', 'startCharIndex': 17, 'endCharIndex': 32}, {'entityName': 'Size', 'startCharIndex': 11, 'endCharIndex': 15}, {'entityName': 'Quantity', 'startCharIndex': 7, 'endCharIndex': 9}, {'entityName': 'Crust', 'startCharIndex': 37, 'endCharIndex': 46}]}]";

            // Create the URLs for uploading example utterances and for training.
            URIBuilder addUtteranceURL = new URIBuilder(Endpoint + "luis/authoring/v3.0-preview/apps/" + AppId + "/versions/" + Version + "/examples");
            URIBuilder trainURL = new URIBuilder(Endpoint + "luis/authoring/v3.0-preview/apps/" + AppId + "/versions/" + Version + "/train");
            URI addUtterancesURI = addUtteranceURL.build();
            URI trainURI = trainURL.build();


            // Add the utterances.

            // Create the request.
            HttpClient addUtterancesClient = HttpClients.createDefault();
            HttpPost addUtterancesRequest = new HttpPost(addUtterancesURI);

            // Add the headers.
            addUtterancesRequest.setHeader("Ocp-Apim-Subscription-Key",Key);
            addUtterancesRequest.setHeader("Content-type","application/json");

            // Add the body.
            StringEntity stringEntity = new StringEntity(Utterances);
            addUtterancesRequest.setEntity(stringEntity);

            // Execute the request and obtain the response.
            HttpResponse addUtterancesResponse = addUtterancesClient.execute(addUtterancesRequest);
            HttpEntity addUtterancesEntity = addUtterancesResponse.getEntity();

            // Print the response on the console.
            if (addUtterancesEntity != null)
            {
                System.out.println(EntityUtils.toString(addUtterancesEntity));
            }


            // Train the model.

            // Create the request.
            HttpClient trainClient = HttpClients.createDefault();
            HttpPost trainRequest = new HttpPost(trainURI);

            // Add the headers.
            trainRequest.setHeader("Ocp-Apim-Subscription-Key",Key);
            trainRequest.setHeader("Content-type","application/json");

            // Execute the request and obtain the response.
            HttpResponse trainResponse = trainClient.execute(trainRequest);
            HttpEntity trainEntity = trainResponse.getEntity();

            // Print the response on the console.
            if (trainEntity != null)
            {
                System.out.println(EntityUtils.toString(trainEntity));
            }


            // Get the training status.


            // Create the request.
            HttpClient trainStatusClient = HttpClients.createDefault();
            HttpGet trainStatusRequest = new HttpGet(trainURI);

            // Add the headers.
            trainStatusRequest.setHeader("Ocp-Apim-Subscription-Key",Key);
            trainStatusRequest.setHeader("Content-type","application/json");

            // Execute the request and obtain the response.
            HttpResponse trainStatusResponse = trainStatusClient.execute(trainStatusRequest);
            HttpEntity trainStatusEntity = trainStatusResponse.getEntity();

            // Print the response on the console.
            if (trainStatusEntity != null)
            {
                System.out.println(EntityUtils.toString(trainStatusEntity));
            }
        }

        // Display errors if they occur.
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

1. Replace the values starting with YOUR- with your own values.

   Information	Purpose
   YOUR-APP-ID	Your LUIS app ID.
   YOUR-AUTHORING-KEY	Your 32 character authoring key.
   YOUR-AUTHORING-ENDPOINT	Your authoring URL endpoint. For example, https://replace-with-your-resource-name.api.cognitive.azure.cn/. You set your resource name when you created the resource.

   Assigned keys and resources are visible in the LUIS portal in the Manage section, on the Azure resources page. The app ID is available in the same Manage section, on the Application Settings page.

   Important

   Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.

2. With a command prompt in the same directory as where you created the Model.java file, enter the following command to compile the Java file:

   • If you are using Windows, use this command: javac -cp ";lib/*" Model.java
   • If you are using macOS or Linux, use this command: javac -cp ":lib/*" Model.java

3. Run the Java application from the command line by entering the following text in the command prompt:

   • If you are using Windows, use this command: java -cp ";lib/*" Model
   • If you are using macOS or Linux, use this command: java -cp ":lib/*" Model

4. Review the authoring response:

   [{"value":{"ExampleId":1137150691,"UtteranceText":"order a pizza"},"hasError":false},{"value":{"ExampleId":1137150692,"UtteranceText":"order a large pepperoni pizza"},"hasError":false},{"value":{"ExampleId":1137150693,"UtteranceText":"i want two large pepperoni pizzas on thin crust"},"hasError":false}]
   {"statusId":9,"status":"Queued"}
   [{"modelId":"edb46abf-0000-41ab-beb2-a41a0fe1630f","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"a5030be2-616c-4648-bf2f-380fa9417d37","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"e4b6704b-1636-474c-9459-fe9ccbeba51c","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"031d3777-2a00-4a7a-9323-9a3280a30000","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"9250e7a1-06eb-4413-9432-ae132ed32583","details":{"statusId":3,"status":"InProgress","exampleCount":0,"progressSubstatus":"CollectingData"}}]
   

   Here is the output formatted for readability:

   [
     {
       "value": {
         "ExampleId": 1137150691,
         "UtteranceText": "order a pizza"
       },
       "hasError": false
     },
     {
       "value": {
         "ExampleId": 1137150692,
         "UtteranceText": "order a large pepperoni pizza"
       },
       "hasError": false
     },
     {
       "value": {
         "ExampleId": 1137150693,
         "UtteranceText": "i want two large pepperoni pizzas on thin crust"
       },
       "hasError": false
     }
   ]
   {
     "statusId": 9,
     "status": "Queued"
   }
   [
     {
       "modelId": "edb46abf-0000-41ab-beb2-a41a0fe1630f",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "a5030be2-616c-4648-bf2f-380fa9417d37",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "e4b6704b-1636-474c-9459-fe9ccbeba51c",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "031d3777-2a00-4a7a-9323-9a3280a30000",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "9250e7a1-06eb-4413-9432-ae132ed32583",
       "details": {
         "statusId": 3,
         "status": "InProgress",
         "exampleCount": 0,
         "progressSubstatus": "CollectingData"
       }
     }
   ]
   

Clean up resources

When you are finished with this quickstart, delete the project folder from the file system.

Next steps

Best practices for an app

Reference documentation | Sample

Prerequisites

• Go programming language
• Visual Studio Code

Example utterances JSON file

The example utterances follow a specific format.

The text field contains the text of the example utterance. The intentName field must correspond to the name of an existing intent in the LUIS app. The entityLabels field is required. If you don't want to label any entities, provide an empty array.

If the entityLabels array is not empty, the startCharIndex and endCharIndex need to mark the entity referred to in the entityName field. The index is zero-based. If you begin or end the label at a space in the text, the API call to add the utterances fails.

[
  {
    "text": "order a pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "order a large pepperoni pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 14,
        "endCharIndex": 28
      },
      {
        "entityName": "Size",
        "startCharIndex": 8,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "I want two large pepperoni pizzas on thin crust",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 17,
        "endCharIndex": 32
      },
      {
        "entityName": "Size",
        "startCharIndex": 11,
        "endCharIndex": 15
      },
      {
        "entityName": "Quantity",
        "startCharIndex": 7,
        "endCharIndex": 9
      },
      {
        "entityName": "Crust",
        "startCharIndex": 37,
        "endCharIndex": 46
      }
    ]
  }
]

Create Pizza app

Create the pizza app.

1. Select pizza-app-for-luis-v6.json to bring up the GitHub page for the pizza-app-for-luis.json file.
2. Right-click or long tap the Raw button and select Save link as to save the pizza-app-for-luis.json to your computer.
3. Sign into the LUIS portal.
4. Select My Apps.
5. On the My Apps page, select + New app for conversation.
6. Select Import as JSON.
7. In the Import new app dialog, select the Choose File button.
8. Select the pizza-app-for-luis.json file you downloaded, then select Open.
9. In the Import new app dialog Name field, enter a name for your Pizza app, then select the Done button.

The app will be imported.

If you see a dialog How to create an effective LUIS app, close the dialog.

Train and publish the Pizza app

You should see the Intents page with a list of the intents in the Pizza app.

1. In the top-right side of the LUIS website, select the Train button.

   

2. Training is complete when the Train button is disabled.

In order to receive a LUIS prediction in a chat bot or other client applications, you need to publish the app to the prediction endpoint.

1. Select Publish in the top-right navigation.

   

2. Select the Production slot, then select Done.

   

3. Select Access your endpoint URLs in the notification to go to the Azure Resources page. You will only be able to see the URLs if you have a prediction resource associated with the app. You can also find the Azure Resources page by clicking Manage.

   

Add an authoring resource to the Pizza app

1. Select MANAGE.
2. Select Azure Resources.
3. Select Authoring Resource.
4. Select Change authoring resource.

If you have an authoring resource, enter the Tenant Name, Subscription Name, and LUIS resource name of your authoring resource.

If you do not have an authoring resource:

1. Select Create new resource.
2. Enter a Tenant Name, Resource Name, Subscription Name, and Azure Resource Group Name.

Your Pizza app is now ready to use.

Record the access values for your Pizza app

To use your new Pizza app, you will need the app ID, authoring key, and authoring endpoint of your Pizza app. To get predictions, you will need your separate prediction endpoint and prediction key.

To find these values:

1. From the Intents page, select MANAGE.
2. From the Application Settings page, record the App ID.
3. Select Azure Resources.
4. Select Authoring Resource.
5. From the Authoring Resource and Prediction Resources tabs, record the Primary Key. This value is your authoring key.
6. Record the Endpoint URL. This value is your authoring endpoint.

Change model programmatically

1. Create a new file named predict.go. Add the following code:

//
// This quickstart shows how to add utterances to a LUIS model using the REST APIs.
//

// dependencies
package main
import (
	"fmt"
	"net/http"
	"io/ioutil"
	"log"
	"strings"
)

// main function
func main() {

	//////////
    // Values to modify.

	// YOUR-APP-ID: The App ID GUID found on the luis.azure.cn Application Settings page.
	var appID = "PASTE_YOUR_LUIS_APP_ID_HERE"

	// YOUR-AUTHORING-KEY: Your LUIS authoring key, 32 character value.
	var authoringKey = "PASTE_YOUR_LUIS_AUTHORING_SUBSCRIPTION_KEY_HERE"

	//  YOUR-AUTHORING-ENDPOINT: Replace this with your authoring key endpoint.
    // For example, "https://your-resource-name.cognitiveservices.azure.cn/"
	var endpoint = "PASTE_YOUR_LUIS_AUTHORING_ENDPOINT_HERE"

	// NOTE: Replace this your version number. The Pizza app uses a version number of "0.1".
	var version = "0.1"
	//////////

	var exampleUtterances = "[{'text': 'order a pizza', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 6, 'endCharIndex': 12}]}, {'text': 'order a large pepperoni pizza', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 6, 'endCharIndex': 28}, {'entityName': 'FullPizzaWithModifiers', 'startCharIndex': 6, 'endCharIndex': 28}, {'entityName': 'PizzaType', 'startCharIndex': 14, 'endCharIndex': 28}, {'entityName': 'Size', 'startCharIndex': 8, 'endCharIndex': 12}]}, {'text': 'I want two large pepperoni pizzas on thin crust', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 7, 'endCharIndex': 46}, {'entityName': 'FullPizzaWithModifiers', 'startCharIndex': 7, 'endCharIndex': 46}, {'entityName': 'PizzaType', 'startCharIndex': 17, 'endCharIndex': 32}, {'entityName': 'Size', 'startCharIndex': 11, 'endCharIndex': 15}, {'entityName': 'Quantity', 'startCharIndex': 7, 'endCharIndex': 9}, {'entityName': 'Crust', 'startCharIndex': 37, 'endCharIndex': 46}]}]"

	fmt.Println("add example utterances requested")
	addUtterance(authoringKey, appID, version, exampleUtterances, endpoint)

	fmt.Println("training selected")
	requestTraining(authoringKey, appID, version, endpoint)

	fmt.Println("training status selected")
	getTrainingStatus(authoringKey, appID, version, endpoint)
}

// Send the list of utterances to the model.
func addUtterance(authoringKey string, appID string,  version string, labeledExampleUtterances string, endpoint string){

	var authoringUrl = fmt.Sprintf("%sluis/authoring/v3.0-preview/apps/%s/versions/%s/examples", endpoint, appID, version)

	httpRequest("POST", authoringUrl, authoringKey, labeledExampleUtterances)
}

// Request training.
func requestTraining(authoringKey string, appID string,  version string, endpoint string){

	trainApp("POST", authoringKey, appID, version, endpoint)
}


func trainApp(httpVerb string, authoringKey string, appID string,  version string, endpoint string){

	var authoringUrl = fmt.Sprintf("%sluis/authoring/v3.0-preview/apps/%s/versions/%s/train", endpoint, appID, version)

	httpRequest(httpVerb,authoringUrl, authoringKey, "")
}


func getTrainingStatus(authoringKey string, appID string, version string, endpoint string){

	trainApp("GET", authoringKey, appID, version, endpoint)
}

// generic HTTP request
// includes setting header with authoring key
func httpRequest(httpVerb string, url string, authoringKey string, body string){

	client := &http.Client{}

	request, err := http.NewRequest(httpVerb, url, strings.NewReader(body))
	request.Header.Add("Ocp-Apim-Subscription-Key", authoringKey)

	fmt.Println("body")
	fmt.Println(body)

	response, err := client.Do(request)

	if err != nil {
		log.Fatal(err)
	} else {
		defer response.Body.Close()

		contents, err := ioutil.ReadAll(response.Body)

		if err != nil {
			log.Fatal(err)
		}

		fmt.Println("   ", response.StatusCode)
		fmt.Println(string(contents))
	}
}

1. Replace the values starting with YOUR- with your own values.

   Information	Purpose
   YOUR-APP-ID	Your LUIS app ID.
   YOUR-AUTHORING-KEY	Your 32 character authoring key.
   YOUR-AUTHORING-ENDPOINT	Your authoring URL endpoint. For example, https://replace-with-your-resource-name.api.cognitive.azure.cn/. You set your resource name when you created the resource.

   Assigned keys and resources are visible in the LUIS portal in the Manage section, on the Azure resources page. The app ID is available in the same Manage section, on the Application Settings page.

   Important

   Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.

2. With a command prompt in the same directory as where you created the file, enter the following command to compile the Go file:

   go build model.go
   

3. Run the Go application from the command line by entering the following text in the command prompt:

   go run model.go
   

4. Review the authoring response:

   add example utterances requested
   body
   [{'text': 'order a pizza', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 6, 'endCharIndex': 12}]}, {'text': 'order a large pepperoni pizza', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 6, 'endCharIndex': 28}, {'entityName': 'FullPizzaWithModifiers', 'startCharIndex': 6, 'endCharIndex': 28}, {'entityName': 'PizzaType', 'startCharIndex': 14, 'endCharIndex': 28}, {'entityName': 'Size', 'startCharIndex': 8, 'endCharIndex': 12}]}, {'text': 'I want two large pepperoni pizzas on thin crust', 'intentName': 'ModifyOrder', 'entityLabels': [{'entityName': 'Order', 'startCharIndex': 7, 'endCharIndex': 46}, {'entityName': 'FullPizzaWithModifiers', 'startCharIndex': 7, 'endCharIndex': 46}, {'entityName': 'PizzaType', 'startCharIndex': 17, 'endCharIndex': 32}, {'entityName': 'Size', 'startCharIndex': 11, 'endCharIndex': 15}, {'entityName': 'Quantity', 'startCharIndex': 7, 'endCharIndex': 9}, {'entityName': 'Crust', 'startCharIndex': 37, 'endCharIndex': 46}]}]
       201
   [{"value":{"ExampleId":1137150691,"UtteranceText":"order a pizza"},"hasError":false},{"value":{"ExampleId":1137150692,"UtteranceText":"order a large pepperoni pizza"},"hasError":false},{"value":{"ExampleId":1137150693,"UtteranceText":"i want two large pepperoni pizzas on thin crust"},"hasError":false}]
   training selected
   body
   
       202
   {"statusId":9,"status":"Queued"}
   training status selected
   body
   
       200
   [{"modelId":"edb46abf-0000-41ab-beb2-a41a0fe1630f","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"a5030be2-616c-4648-bf2f-380fa9417d37","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"e4b6704b-1636-474c-9459-fe9ccbeba51c","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"031d3777-2a00-4a7a-9323-9a3280a30000","details":{"statusId":9,"status":"Queued","exampleCount":0}},{"modelId":"9250e7a1-06eb-4413-9432-ae132ed32583","details":{"statusId":9,"status":"Queued","exampleCount":0}}]
   

   Here is the output formatted for readability:

   add example utterances requested
   body
   [
     {
       'text': 'order a pizza',
       'intentName': 'ModifyOrder',
       'entityLabels': [
         {
           'entityName': 'Order',
           'startCharIndex': 6,
           'endCharIndex': 12
         }
       ]
     },
     {
       'text': 'order a large pepperoni pizza',
       'intentName': 'ModifyOrder',
       'entityLabels': [
         {
           'entityName': 'Order',
           'startCharIndex': 6,
           'endCharIndex': 28
         },
         {
           'entityName': 'FullPizzaWithModifiers',
           'startCharIndex': 6,
           'endCharIndex': 28
         },
         {
           'entityName': 'PizzaType',
           'startCharIndex': 14,
           'endCharIndex': 28
         },
         {
           'entityName': 'Size',
           'startCharIndex': 8,
           'endCharIndex': 12
         }
       ]
     },
     {
       'text': 'I want two large pepperoni pizzas on thin crust',
       'intentName': 'ModifyOrder',
       'entityLabels': [
         {
           'entityName': 'Order',
           'startCharIndex': 7,
           'endCharIndex': 46
         },
         {
           'entityName': 'FullPizzaWithModifiers',
           'startCharIndex': 7,
           'endCharIndex': 46
         },
         {
           'entityName': 'PizzaType',
           'startCharIndex': 17,
           'endCharIndex': 32
         },
         {
           'entityName': 'Size',
           'startCharIndex': 11,
           'endCharIndex': 15
         },
         {
           'entityName': 'Quantity',
           'startCharIndex': 7,
           'endCharIndex': 9
         },
         {
           'entityName': 'Crust',
           'startCharIndex': 37,
           'endCharIndex': 46
         }
       ]
     }
   ]
   
       201
   [
     {
       "value": {
         "ExampleId": 1137150691,
         "UtteranceText": "order a pizza"
       },
       "hasError": false
     },
     {
       "value": {
         "ExampleId": 1137150692,
         "UtteranceText": "order a large pepperoni pizza"
       },
       "hasError": false
     },
     {
       "value": {
         "ExampleId": 1137150693,
         "UtteranceText": "i want two large pepperoni pizzas on thin crust"
       },
       "hasError": false
     }
   ]
   training selected
   body
   
       202
   {
     "statusId": 9,
     "status": "Queued"
   }
   training status selected
   body
   
       200
   [
     {
       "modelId": "edb46abf-0000-41ab-beb2-a41a0fe1630f",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "a5030be2-616c-4648-bf2f-380fa9417d37",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "e4b6704b-1636-474c-9459-fe9ccbeba51c",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "031d3777-2a00-4a7a-9323-9a3280a30000",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "9250e7a1-06eb-4413-9432-ae132ed32583",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     }
   ]
   

Clean up resources

When you are finished with this quickstart, delete the file from the file system.

Next steps

Best practices for an app

Reference documentation | Sample

Prerequisites

• Node.js programming language
• Visual Studio Code

Example utterances JSON file

The example utterances follow a specific format.

The text field contains the text of the example utterance. The intentName field must correspond to the name of an existing intent in the LUIS app. The entityLabels field is required. If you don't want to label any entities, provide an empty array.

If the entityLabels array is not empty, the startCharIndex and endCharIndex need to mark the entity referred to in the entityName field. The index is zero-based. If you begin or end the label at a space in the text, the API call to add the utterances fails.

[
  {
    "text": "order a pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "order a large pepperoni pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 14,
        "endCharIndex": 28
      },
      {
        "entityName": "Size",
        "startCharIndex": 8,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "I want two large pepperoni pizzas on thin crust",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 17,
        "endCharIndex": 32
      },
      {
        "entityName": "Size",
        "startCharIndex": 11,
        "endCharIndex": 15
      },
      {
        "entityName": "Quantity",
        "startCharIndex": 7,
        "endCharIndex": 9
      },
      {
        "entityName": "Crust",
        "startCharIndex": 37,
        "endCharIndex": 46
      }
    ]
  }
]

Create the Node.js project

1. Create a new folder to hold your Node.js project, such as node-model-with-rest.

2. Open a new Command Prompt, navigate to the folder you created and execute the following command:

   npm init
   

   Press Enter at each prompt to accept the default settings.

3. Install the request-promise module by entering the following command:

   npm install --save request
   npm install --save request-promise
   npm install --save querystring
   

Change model programmatically

1. Create a new file named model.js. Add the following code:

//
// This quickstart shows how to add utterances to a LUIS model using the REST APIs.
//

var request = require('request-promise');

//////////
// Values to modify.

// YOUR-APP-ID: The App ID GUID found on the luis.azure.cn Application Settings page.
const LUIS_appId = "PASTE_YOUR_LUIS_APP_ID_HERE";

// YOUR-AUTHORING-KEY: Your LUIS authoring key, 32 character value.
const LUIS_authoringKey = "PASTE_YOUR_LUIS_AUTHORING_SUBSCRIPTION_KEY_HERE";

// YOUR-AUTHORING-ENDPOINT: Replace this with your authoring key endpoint.
// For example, "https://your-resource-name.cognitiveservices.azure.cn/"
const LUIS_endpoint = "PASTE_YOUR_LUIS_AUTHORING_ENDPOINT_HERE";

// NOTE: Replace this your version number. The Pizza app uses a version number of "0.1".
const LUIS_versionId = "0.1";
//////////

const addUtterancesURI = `${LUIS_endpoint}luis/authoring/v3.0-preview/apps/${LUIS_appId}/versions/${LUIS_versionId}/examples`;
const addTrainURI = `${LUIS_endpoint}luis/authoring/v3.0-preview/apps/${LUIS_appId}/versions/${LUIS_versionId}/train`;

const utterances = [
    {
        'text': 'order a pizza',
        'intentName': 'ModifyOrder',
        'entityLabels': [
            {
                'entityName': 'Order',
                'startCharIndex': 6,
                'endCharIndex': 12
            }
        ]
    },
    {
        'text': 'order a large pepperoni pizza',
        'intentName': 'ModifyOrder',
        'entityLabels': [
            {
                'entityName': 'Order',
                'startCharIndex': 6,
                'endCharIndex': 28
            },
            {
                'entityName': 'FullPizzaWithModifiers',
                'startCharIndex': 6,
                'endCharIndex': 28
            },
            {
                'entityName': 'PizzaType',
                'startCharIndex': 14,
                'endCharIndex': 28
            },
            {
                'entityName': 'Size',
                'startCharIndex': 8,
                'endCharIndex': 12
            }
        ]
    },
    {
        'text': 'I want two large pepperoni pizzas on thin crust',
        'intentName': 'ModifyOrder',
        'entityLabels': [
            {
                'entityName': 'Order',
                'startCharIndex': 7,
                'endCharIndex': 46
            },
            {
                'entityName': 'FullPizzaWithModifiers',
                'startCharIndex': 7,
                'endCharIndex': 46
            },
            {
                'entityName': 'PizzaType',
                'startCharIndex': 17,
                'endCharIndex': 32
            },
            {
                'entityName': 'Size',
                'startCharIndex': 11,
                'endCharIndex': 15
            },
            {
                'entityName': 'Quantity',
                'startCharIndex': 7,
                'endCharIndex': 9
            },
            {
                'entityName': 'Crust',
                'startCharIndex': 37,
                'endCharIndex': 46
            }
        ]
    }
];

// Main function.
const main = async() =>{

    await addUtterances(utterances);
    await train("POST");
    await train("GET");

}

// Adds the utterances to the model.
const addUtterances = async (utterances) => {

    const options = {
        uri: addUtterancesURI,
        method: 'POST',
        headers: {
            'Ocp-Apim-Subscription-Key': LUIS_authoringKey
        },
        json: true,
        body: utterances
    };

    const response = await request(options)
    console.log("addUtterance:\n" + JSON.stringify(response, null, 2));
}

// With verb === "POST", sends a training request.
// With verb === "GET", obtains the training status.
const train = async (verb) => {

    const options = {
        uri: addTrainURI,
        method: verb,
        headers: {
            'Ocp-Apim-Subscription-Key': LUIS_authoringKey
        },
        json: true,
        body: null // The body can be empty for a training request
    };

    const response = await request(options)
    console.log("train " + verb + ":\n" + JSON.stringify(response, null, 2));
}

// MAIN
main().then(() => console.log("done")).catch((err)=> console.log(err));

1. Replace the values starting with YOUR- with your own values.

   Information	Purpose
   YOUR-APP-ID	Your LUIS app ID.
   YOUR-AUTHORING-KEY	Your 32 character authoring key.
   YOUR-AUTHORING-ENDPOINT	Your authoring URL endpoint. For example, https://replace-with-your-resource-name.api.cognitive.azure.cn/. You set your resource name when you created the resource.

   Assigned keys and resources are visible in the LUIS portal in the Manage section, on the Azure resources page. The app ID is available in the same Manage section, on the Application Settings page.

   Important

   Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.

2. At the command prompt, enter the following command to run the project:

   node model.js
   

3. Review the authoring response:

   addUtterance:
   [
     {
       "value": {
         "ExampleId": 1137150691,
         "UtteranceText": "order a pizza"
       },
       "hasError": false
     },
     {
       "value": {
         "ExampleId": 1137150692,
         "UtteranceText": "order a large pepperoni pizza"
       },
       "hasError": false
     },
     {
       "value": {
         "ExampleId": 1137150693,
         "UtteranceText": "i want two large pepperoni pizzas on thin crust"
       },
       "hasError": false
     }
   ]
   train POST:
   {
     "statusId": 9,
     "status": "Queued"
   }
   train GET:
   [
     {
       "modelId": "edb46abf-0000-41ab-beb2-a41a0fe1630f",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "a5030be2-616c-4648-bf2f-380fa9417d37",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "e4b6704b-1636-474c-9459-fe9ccbeba51c",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "031d3777-2a00-4a7a-9323-9a3280a30000",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     },
     {
       "modelId": "9250e7a1-06eb-4413-9432-ae132ed32583",
       "details": {
         "statusId": 9,
         "status": "Queued",
         "exampleCount": 0
       }
     }
   ]
   done
   

Clean up resources

When you are finished with this quickstart, delete the project folder from the file system.

Next steps

Best practices for an app

Reference documentation | Sample

Prerequisites

• Python 3.6 or later.
• Visual Studio Code

Example utterances JSON file

The example utterances follow a specific format.

The text field contains the text of the example utterance. The intentName field must correspond to the name of an existing intent in the LUIS app. The entityLabels field is required. If you don't want to label any entities, provide an empty array.

If the entityLabels array is not empty, the startCharIndex and endCharIndex need to mark the entity referred to in the entityName field. The index is zero-based. If you begin or end the label at a space in the text, the API call to add the utterances fails.

[
  {
    "text": "order a pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "order a large pepperoni pizza",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 6,
        "endCharIndex": 28
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 14,
        "endCharIndex": 28
      },
      {
        "entityName": "Size",
        "startCharIndex": 8,
        "endCharIndex": 12
      }
    ]
  },
  {
    "text": "I want two large pepperoni pizzas on thin crust",
    "intentName": "ModifyOrder",
    "entityLabels": [
      {
        "entityName": "Order",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "FullPizzaWithModifiers",
        "startCharIndex": 7,
        "endCharIndex": 46
      },
      {
        "entityName": "PizzaType",
        "startCharIndex": 17,
        "endCharIndex": 32
      },
      {
        "entityName": "Size",
        "startCharIndex": 11,
        "endCharIndex": 15
      },
      {
        "entityName": "Quantity",
        "startCharIndex": 7,
        "endCharIndex": 9
      },
      {
        "entityName": "Crust",
        "startCharIndex": 37,
        "endCharIndex": 46
      }
    ]
  }
]

Create Pizza app

Create the pizza app.

1. Select pizza-app-for-luis-v6.json to bring up the GitHub page for the pizza-app-for-luis.json file.
2. Right-click or long tap the Raw button and select Save link as to save the pizza-app-for-luis.json to your computer.
3. Sign into the LUIS portal.
4. Select My Apps.
5. On the My Apps page, select + New app for conversation.
6. Select Import as JSON.
7. In the Import new app dialog, select the Choose File button.
8. Select the pizza-app-for-luis.json file you downloaded, then select Open.
9. In the Import new app dialog Name field, enter a name for your Pizza app, then select the Done button.

The app will be imported.

If you see a dialog How to create an effective LUIS app, close the dialog.

Train and publish the Pizza app

You should see the Intents page with a list of the intents in the Pizza app.

1. In the top-right side of the LUIS website, select the Train button.

   

2. Training is complete when the Train button is disabled.

In order to receive a LUIS prediction in a chat bot or other client applications, you need to publish the app to the prediction endpoint.

1. Select Publish in the top-right navigation.

   

2. Select the Production slot, then select Done.

   

3. Select Access your endpoint URLs in the notification to go to the Azure Resources page. You will only be able to see the URLs if you have a prediction resource associated with the app. You can also find the Azure Resources page by clicking Manage.

   

Add an authoring resource to the Pizza app

1. Select MANAGE.
2. Select Azure Resources.
3. Select Authoring Resource.
4. Select Change authoring resource.

If you have an authoring resource, enter the Tenant Name, Subscription Name, and LUIS resource name of your authoring resource.

If you do not have an authoring resource:

1. Select Create new resource.
2. Enter a Tenant Name, Resource Name, Subscription Name, and Azure Resource Group Name.

Your Pizza app is now ready to use.

Record the access values for your Pizza app

To use your new Pizza app, you will need the app ID, authoring key, and authoring endpoint of your Pizza app. To get predictions, you will need your separate prediction endpoint and prediction key.

To find these values:

1. From the Intents page, select MANAGE.
2. From the Application Settings page, record the App ID.
3. Select Azure Resources.
4. Select Authoring Resource.
5. From the Authoring Resource and Prediction Resources tabs, record the Primary Key. This value is your authoring key.
6. Record the Endpoint URL. This value is your authoring endpoint.

Change model programmatically

1. Create a new file named model.py. Add the following code:

########### Python 3.6 #############

#
# This quickstart shows how to add utterances to a LUIS model using the REST APIs.
#

import requests

try:

    ##########
    # Values to modify.

    # YOUR-APP-ID: The App ID GUID found on the luis.azure.cn Application Settings page.
    appId = "PASTE_YOUR_LUIS_APP_ID_HERE"

    # YOUR-AUTHORING-KEY: Your LUIS authoring key, 32 character value.
    authoring_key = "PASTE_YOUR_LUIS_AUTHORING_SUBSCRIPTION_KEY_HERE"

    # YOUR-AUTHORING-ENDPOINT: Replace this with your authoring key endpoint.
    # For example, "https://your-resource-name.cognitiveservices.azure.cn/"
    authoring_endpoint = "PASTE_YOUR_LUIS_AUTHORING_ENDPOINT_HERE"

    # The version number of your LUIS app
    app_version = "0.1"
    ##########

    # The headers to use in this REST call.
    headers = {'Ocp-Apim-Subscription-Key': authoring_key}

    # The URL parameters to use in this REST call.
    params ={
        #'timezoneOffset': '0',
        #'verbose': 'true',
        #'show-all-intents': 'true',
        #'spellCheck': 'false',
        #'staging': 'false'
    }

    # List of example utterances to send to the LUIS app.
    data = """[
    {
        'text': 'order a pizza',
        'intentName': 'ModifyOrder',
        'entityLabels': [
            {
                'entityName': 'Order',
                'startCharIndex': 6,
                'endCharIndex': 12
            }
        ]
    },
    {
        'text': 'order a large pepperoni pizza',
        'intentName': 'ModifyOrder',
        'entityLabels': [
            {
                'entityName': 'Order',
                'startCharIndex': 6,
                'endCharIndex': 28
            },
            {
                'entityName': 'FullPizzaWithModifiers',
                'startCharIndex': 6,
                'endCharIndex': 28
            },
            {
                'entityName': 'PizzaType',
                'startCharIndex': 14,
                'endCharIndex': 28
            },
            {
                'entityName': 'Size',
                'startCharIndex': 8,
                'endCharIndex': 12
            }
        ]
    },
    {
        'text': 'I want two large pepperoni pizzas on thin crust',
        'intentName': 'ModifyOrder',
        'entityLabels': [
            {
                'entityName': 'Order',
                'startCharIndex': 7,
                'endCharIndex': 46
            },
            {
                'entityName': 'FullPizzaWithModifiers',
                'startCharIndex': 7,
                'endCharIndex': 46
            },
            {
                'entityName': 'PizzaType',
                'startCharIndex': 17,
                'endCharIndex': 32
            },
            {
                'entityName': 'Size',
                'startCharIndex': 11,
                'endCharIndex': 15
            },
            {
                'entityName': 'Quantity',
                'startCharIndex': 7,
                'endCharIndex': 9
            },
            {
                'entityName': 'Crust',
                'startCharIndex': 37,
                'endCharIndex': 46
            }
        ]
    }
]
"""


    # Make the REST call to POST the list of example utterances.
    response = requests.post(f'{authoring_endpoint}luis/authoring/v3.0-preview/apps/{appId}/versions/{app_version}/examples',
        headers=headers, params=params, data=data)

    # Display the results on the console.
    print('Add the list of utterances:')
    print(response.json())


    # Make the REST call to initiate a training session.
    response = requests.post(f'{authoring_endpoint}luis/authoring/v3.0-preview/apps/{appId}/versions/{app_version}/train',
        headers=headers, params=params, data=None)

    # Display the results on the console.
    print('Request training:')
    print(response.json())


    # Make the REST call to request the status of training.
    response = requests.get(f'{authoring_endpoint}luis/authoring/v3.0-preview/apps/{appId}/versions/{app_version}/train',
        headers=headers, params=params, data=None)

    # Display the results on the console.
    print('Request training status:')
    print(response.json())


except Exception as e:
    # Display the error string.
    print(f'{e}')

1. Replace the values starting with YOUR- with your own values.

   Information	Purpose
   YOUR-APP-ID	Your LUIS app ID.
   YOUR-AUTHORING-KEY	Your 32 character authoring key.
   YOUR-AUTHORING-ENDPOINT	Your authoring URL endpoint. For example, https://replace-with-your-resource-name.api.cognitive.azure.cn/. You set your resource name when you created the resource.

   Assigned keys and resources are visible in the LUIS portal in the Manage section, on the Azure resources page. The app ID is available in the same Manage section, on the Application Settings page.

   Important

   Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.

2. With a command prompt in the same directory as where you created the file, enter the following command to run the file:

   python model.py
   

3. Review the authoring response:

   Add the list of utterances:
   [{'value': {'ExampleId': 1137150691, 'UtteranceText': 'order a pizza'}, 'hasError': False}, {'value': {'ExampleId': 1137150692, 'UtteranceText': 'order a large pepperoni pizza'}, 'hasError': False}, {'value': {'ExampleId': 1137150693, 'UtteranceText': 'i want two large pepperoni pizzas on thin crust'}, 'hasError': False}]
   Request training:
   {'statusId': 9, 'status': 'Queued'}
   Request training status:
   [{'modelId': 'edb46abf-0000-41ab-beb2-a41a0fe1630f', 'details': {'statusId': 3, 'status': 'InProgress', 'exampleCount': 0, 'progressSubstatus': 'CollectingData'}}, {'modelId': 'a5030be2-616c-4648-bf2f-380fa9417d37', 'details': {'statusId': 3, 'status': 'InProgress', 'exampleCount': 0, 'progressSubstatus': 'CollectingData'}}, {'modelId': '3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9', 'details': {'statusId': 3, 'status': 'InProgress', 'exampleCount': 0, 'progressSubstatus': 'CollectingData'}}, {'modelId': 'e4b6704b-1636-474c-9459-fe9ccbeba51c', 'details': {'statusId': 3, 'status': 'InProgress', 'exampleCount': 0, 'progressSubstatus': 'CollectingData'}}, {'modelId': '031d3777-2a00-4a7a-9323-9a3280a30000', 'details': {'statusId': 3, 'status': 'InProgress', 'exampleCount': 0, 'progressSubstatus': 'CollectingData'}}, {'modelId': '9250e7a1-06eb-4413-9432-ae132ed32583', 'details': {'statusId': 3, 'status': 'InProgress', 'exampleCount': 0, 'progressSubstatus': 'CollectingData'}}]
   

   Here is the output formatted for readability:

   Add the list of utterances:
   [
     {
       'value': {
         'ExampleId': 1137150691,
         'UtteranceText': 'order a pizza'
       },
       'hasError': False
     },
     {
       'value': {
         'ExampleId': 1137150692,
         'UtteranceText': 'order a large pepperoni pizza'
       },
       'hasError': False
     },
     {
       'value': {
         'ExampleId': 1137150693,
         'UtteranceText': 'i want two large pepperoni pizzas on thin crust'
       },
       'hasError': False
     }
   ]
   
   Request training:
   {
     'statusId': 9,
     'status': 'Queued'
   }
   
   Request training status:
   [
     {
       'modelId': 'edb46abf-0000-41ab-beb2-a41a0fe1630f',
       'details': {
         'statusId': 3,
         'status': 'InProgress',
         'exampleCount': 0,
         'progressSubstatus': 'CollectingData'
       }
     },
     {
       'modelId': 'a5030be2-616c-4648-bf2f-380fa9417d37',
       'details': {
         'statusId': 3,
         'status': 'InProgress',
         'exampleCount': 0,
         'progressSubstatus': 'CollectingData'
       }
     },
     {
       'modelId': '3f2b1f31-a3c3-4fbd-8182-e9d9dbc120b9',
       'details': {
         'statusId': 3,
         'status': 'InProgress',
         'exampleCount': 0,
         'progressSubstatus': 'CollectingData'
       }
     },
     {
       'modelId': 'e4b6704b-1636-474c-9459-fe9ccbeba51c',
       'details': {
         'statusId': 3,
         'status': 'InProgress',
         'exampleCount': 0,
         'progressSubstatus': 'CollectingData'
       }
     },
     {
       'modelId': '031d3777-2a00-4a7a-9323-9a3280a30000',
       'details': {
         'statusId': 3,
         'status': 'InProgress',
         'exampleCount': 0,
         'progressSubstatus': 'CollectingData'
       }
     },
     {
       'modelId': '9250e7a1-06eb-4413-9432-ae132ed32583',
       'details': {
         'statusId': 3,
         'status': 'InProgress',
         'exampleCount': 0,
         'progressSubstatus': 'CollectingData'
       }
     }
   ]
   

Clean up resources

When you are finished with this quickstart, delete the file from the file system.

Next steps

Best practices for an app