Back up and recover your conversational language understanding models
When you create a Language resource in the Azure portal, you specify a region for it to be created in. From then on, your resource and all of the operations related to it take place in the specified Azure server region. It's rare, but not impossible, to encounter a network issue that hits an entire region. If your solution needs to always be available, then you should design it to either fail-over into another region. This requires two Azure AI Language resources in different regions and the ability to sync your CLU models across regions.
If your app or business depends on the use of a CLU model, we recommend that you create a replica of your project into another supported region. So that if a regional outage occurs, you can then access your model in the other fail-over region where you replicated your project.
Replicating a project means that you export your project metadata and assets and import them into a new project. This only makes a copy of your project settings, intents, entities and utterances. You still need to train and deploy the models to be available for use with runtime APIs.
In this article, you will learn to how to use the export and import APIs to replicate your project from one resource to another existing in different supported geographical regions, guidance on keeping your projects in sync and changes needed to your runtime consumption.
Prerequisites
- Two Azure AI Language resources in different Azure regions, each of them in a different region.
Get your resource keys endpoint
Use the following steps to get the keys and endpoint of your primary and secondary resources. These will be used in the following steps.
Go to your resource overview page in the Azure portal. From the menu on the left side, select Keys and Endpoint. You will use the endpoint and key for the API requests
Tip
Keep a note of keys and endpoints for both primary and secondary resources. Use these values to replace the following placeholders:
{PRIMARY-ENDPOINT}, {PRIMARY-RESOURCE-KEY}, {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY}.
Also take note of your project name, your model name and your deployment name. Use these values to replace the following placeholders: {PROJECT-NAME}, {MODEL-NAME} and {DEPLOYMENT-NAME}.
Export your primary project assets
Start by exporting the project assets from the project in your primary resource.
Submit export job
Replace the placeholders in the following request with your {PRIMARY-ENDPOINT} and {PRIMARY-RESOURCE-KEY} that you obtained in the first step.
Create a POST request using the following URL, headers, and JSON body to export your project.
Request URL
Use the following URL when creating your API request. Replace the placeholder values below with your own values.
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | EmailApp |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Value |
|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. |
Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
JOB-ID is used to identify your request, since this operation is asynchronous. Use this URL to get the exported project JSON, using the same authentication method.
Get export job status
Replace the placeholders in the following request with your {PRIMARY-ENDPOINT} and {PRIMARY-RESOURCE-KEY} that you obtained in the first step.
Use the following GET request to query the status of your export job. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/{JOB-ID}?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | myProject |
{JOB-ID} |
The ID for locating your export job status. This is in the location header value you received in the previous step. |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Description | Value |
|---|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. | {YOUR-PRIMARY-RESOURCE-KEY} |
Response body
{
"resultUrl": "{Endpoint}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/xxxxxx-xxxxx-xxxxx-xx/result?api-version={API-VERSION}",
"jobId": "xxxx-xxxxx-xxxxx-xxx",
"createdDateTime": "2022-04-18T15:23:07Z",
"lastUpdatedDateTime": "2022-04-18T15:23:08Z",
"expirationDateTime": "2022-04-25T15:23:07Z",
"status": "succeeded"
}
Use the url from the resultUrl key in the body to view the exported assets from this job.
Get export results
Submit a GET request using the {RESULT-URL} you received from the previous step to view the results of the export job.
Headers
Use the following header to authenticate your request.
| Key | Description | Value |
|---|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. | {PRIMARY-RESOURCE-KEY} |
Copy the response body as you will use it as the body for the next import job.
Import to a new project
Now go ahead and import the exported project assets in your new project in the secondary region so you can replicate it.
Submit import job
Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.
Submit a POST request using the following URL, headers, and JSON body to import your project.
Request URL
Use the following URL when creating your API request. Replace the placeholder values with your own values.
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive, and must match the project name in the JSON file you're importing. | EmailAppDemo |
{API-VERSION} |
The version of the API you're calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Value |
|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. |
Body
The JSON body you send is similar to the following example. See the reference documentation for more details about the JSON object.
{
"projectFileVersion": "{API-VERSION}",
"stringIndexType": "Utf16CodeUnit",
"metadata": {
"projectKind": "Conversation",
"settings": {
"confidenceThreshold": 0.7
},
"projectName": "{PROJECT-NAME}",
"multilingual": true,
"description": "Trying out CLU",
"language": "{LANGUAGE-CODE}"
},
"assets": {
"projectKind": "Conversation",
"intents": [
{
"category": "intent1"
},
{
"category": "intent2"
}
],
"entities": [
{
"category": "entity1"
}
],
"utterances": [
{
"text": "text1",
"dataset": "{DATASET}",
"intent": "intent1",
"entities": [
{
"category": "entity1",
"offset": 5,
"length": 5
}
]
},
{
"text": "text2",
"language": "{LANGUAGE-CODE}",
"dataset": "{DATASET}",
"intent": "intent2",
"entities": []
}
]
}
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
{API-VERSION} |
The version of the API you're calling. | 2023-04-01 |
|
projectName |
{PROJECT-NAME} |
The name of your project. This value is case-sensitive. | EmailAppDemo |
language |
{LANGUAGE-CODE} |
A string specifying the language code for the utterances used in your project. If your project is a multilingual project, choose the language code of the majority of the utterances. | en-us |
multilingual |
true |
A boolean value that enables you to have documents in multiple languages in your dataset. When your model is deployed, you can query the model in any supported language including languages that aren't included in your training documents. | true |
dataset |
{DATASET} |
See how to train a model for information on splitting your data between a testing and training set. Possible values for this field are Train and Test. |
Train |
Upon a successful request, the API response will contain an operation-location header with a URL you can use to check the status of the import job. It is formatted like this:
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
Get import job status
Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.
When you send a successful project import request, the full request URL for checking the import job's status (including your endpoint, project name, and job ID) is contained in the response's operation-location header.
Use the following GET request to query the status of your import job. You can use the URL you received from the previous step, or replace the placeholder values with your own values.
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | myProject |
{JOB-ID} |
The ID for locating your import job status. | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Description | Value |
|---|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. | {YOUR-PRIMARY-RESOURCE-KEY} |
Response body
Once you send the request, you'll get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".
{
"jobId": "xxxxx-xxxxx-xxxx-xxxxx",
"createdDateTime": "2022-04-18T15:17:20Z",
"lastUpdatedDateTime": "2022-04-18T15:17:22Z",
"expirationDateTime": "2022-04-25T15:17:20Z",
"status": "succeeded"
}
Train your model
After importing your project, you only have copied the project's assets and metadata and assets. You still need to train your model, which will incur usage on your account.
Submit training job
Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.
Create a POST request using the following URL, headers, and JSON body to submit a training job.
Request URL
Use the following URL when creating your API request. Replace the placeholder values with your own values.
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | EmailApp |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Value |
|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. |
Request body
Use the following object in your request. The model will be named after the value you use for the modelLabel parameter once training is complete.
{
"modelLabel": "{MODEL-NAME}",
"trainingMode": "{TRAINING-MODE}",
"trainingConfigVersion": "{CONFIG-VERSION}",
"evaluationOptions": {
"kind": "percentage",
"testingSplitPercentage": 20,
"trainingSplitPercentage": 80
}
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
modelLabel |
{MODEL-NAME} |
Your Model name. | Model1 |
trainingConfigVersion |
{CONFIG-VERSION} |
The training configuration model version. By default, the latest model version is used. | 2022-05-01 |
trainingMode |
{TRAINING-MODE} |
The training mode to be used for training. Supported modes are Standard training, faster training, but only available for English and Advanced training supported for other languages and multilingual projects, but involves longer training times. Learn more about training modes. | standard |
kind |
percentage |
Split methods. Possible Values are percentage or manual. See how to train a model for more information. |
percentage |
trainingSplitPercentage |
80 |
Percentage of your tagged data to be included in the training set. Recommended value is 80. |
80 |
testingSplitPercentage |
20 |
Percentage of your tagged data to be included in the testing set. Recommended value is 20. |
20 |
Note
The trainingSplitPercentage and testingSplitPercentage are only required if Kind is set to percentage and the sum of both percentages should be equal to 100.
Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
You can use this URL to get the training job status.
Get Training Status
Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.
When you send a successful training request, the full request URL for checking the job's status (including your endpoint, project name, and job ID) is contained in the response's operation-location header.
Use the following GET request to get the status of your model's training progress. Replace the placeholder values below with your own values.
Request URL
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{YOUR-ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | EmailApp |
{JOB-ID} |
The ID for locating your model's training status. | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Value |
|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. |
Response Body
Once you send the request, you will get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".
{
"result": {
"modelLabel": "{MODEL-LABEL}",
"trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
"trainingMode": "{TRAINING-MODE}",
"estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
"trainingStatus": {
"percentComplete": 3,
"startDateTime": "2022-04-18T15:45:06.8190649Z",
"status": "running"
},
"evaluationStatus": {
"percentComplete": 0,
"status": "notStarted"
}
},
"jobId": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
"createdDateTime": "2022-04-18T15:44:44Z",
"lastUpdatedDateTime": "2022-04-18T15:45:48Z",
"expirationDateTime": "2022-04-25T15:44:44Z",
"status": "running"
}
| Key | Value | Example |
|---|---|---|
modelLabel |
The model name | Model1 |
trainingConfigVersion |
The training configuration version. By default, the latest version is used. | 2022-05-01 |
trainingMode |
Your selected training mode. | standard |
startDateTime |
The time training started | 2022-04-14T10:23:04.2598544Z |
status |
The status of the training job | running |
estimatedEndDateTime |
Estimated time for the training job to finish | 2022-04-14T10:29:38.2598544Z |
jobId |
Your training job ID | xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx |
createdDateTime |
Training job creation date and time | 2022-04-14T10:22:42Z |
lastUpdatedDateTime |
Training job last updated date and time | 2022-04-14T10:23:45Z |
expirationDateTime |
Training job expiration date and time | 2022-04-14T10:22:42Z |
Deploy your model
This is the step where you make your trained model available form consumption via the runtime prediction API.
Tip
Use the same deployment name as your primary project for easier maintenance and minimal changes to your system to handle redirecting your traffic.
Submit deployment job
Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.
Create a PUT request using the following URL, headers, and JSON body to start deploying a conversational language understanding model.
Request URL
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | myProject |
{DEPLOYMENT-NAME} |
The name for your deployment. This value is case-sensitive. | staging |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Value |
|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. |
Request Body
{
"trainedModelLabel": "{MODEL-NAME}",
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
| trainedModelLabel | {MODEL-NAME} |
The model name that will be assigned to your deployment. You can only assign successfully trained models. This value is case-sensitive. | myModel |
Once you send your API request, you will receive a 202 response indicating success. In the response headers, extract the operation-location value. It will be formatted like this:
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
You can use this URL to get the deployment job status.
Get the deployment status
Replace the placeholders in the following request with your {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY} that you obtained in the first step.
When you send a successful deployment request, the full request URL for checking the job's status (including your endpoint, project name, and job ID) is contained in the response's operation-location header.
Use the following GET request to get the status of your deployment job. Replace the placeholder values with your own values.
Request URL
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | myProject |
{DEPLOYMENT-NAME} |
The name for your deployment. This value is case-sensitive. | staging |
{JOB-ID} |
The ID for locating your model's training status. | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Value |
|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. |
Response Body
Once you send the request, you'll get the following response. Keep polling this endpoint until the status parameter changes to "succeeded".
{
"jobId":"{JOB-ID}",
"createdDateTime":"{CREATED-TIME}",
"lastUpdatedDateTime":"{UPDATED-TIME}",
"expirationDateTime":"{EXPIRATION-TIME}",
"status":"running"
}
Changes in calling the runtime
Within your system, at the step where you call runtime API check for the response code returned from the submit task API. If you observe a consistent failure in submitting the request, this could indicate an outage in your primary region. Failure once doesn't mean an outage, it may be transient issue. Retry submitting the job through the secondary resource you have created. For the second request use your {YOUR-SECONDARY-ENDPOINT} and secondary key, if you have followed the steps above, {PROJECT-NAME} and {DEPLOYMENT-NAME} would be the same so no changes are required to the request body.
In case you revert to using your secondary resource you will observe slight increase in latency because of the difference in regions where your model is deployed.
Check if your projects are out of sync
Maintaining the freshness of both projects is an important part of process. You need to frequently check if any updates were made to your primary project so that you move them over to your secondary project. This way if your primary region fail and you move into the secondary region you should expect similar model performance since it already contains the latest updates. Setting the frequency of checking if your projects are in sync is an important choice, we recommend that you do this check daily in order to guarantee the freshness of data in your secondary model.
Get project details
Use the following url to get your project details, one of the keys returned in the body indicates the last modified date of the project. Repeat the following step twice, one for your primary project and another for your secondary project and compare the timestamp returned for both of them to check if they are out of sync.
Use the following GET request to get your project details. You can use the URL you received from the previous step, or replace the placeholder values below with your own values.
{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}
| Placeholder | Value | Example |
|---|---|---|
{ENDPOINT} |
The endpoint for authenticating your API request. | https://<your-custom-subdomain>.cognitiveservices.azure.com |
{PROJECT-NAME} |
The name for your project. This value is case-sensitive. | myProject |
{API-VERSION} |
The version of the API you are calling. | 2023-04-01 |
Headers
Use the following header to authenticate your request.
| Key | Description | Value |
|---|---|---|
Ocp-Apim-Subscription-Key |
The key to your resource. Used for authenticating your API requests. | {YOUR-PRIMARY-RESOURCE-KEY} |
Response body
{
"createdDateTime": "2022-04-18T13:53:03Z",
"lastModifiedDateTime": "2022-04-18T13:53:03Z",
"lastTrainedDateTime": "2022-04-18T14:14:28Z",
"lastDeployedDateTime": "2022-04-18T14:49:01Z",
"projectKind": "Conversation",
"projectName": "{PROJECT-NAME}",
"multilingual": true,
"description": "This is a sample conversation project.",
"language": "{LANGUAGE-CODE}"
}
Repeat the same steps for your replicated project using {SECONDARY-ENDPOINT} and {SECONDARY-RESOURCE-KEY}. Compare the returned lastModifiedDateTime from both projects. If your primary project was modified sooner than your secondary one, you need to repeat the steps of exporting, importing, training and deploying your model.
Next steps
In this article, you have learned how to use the export and import APIs to replicate your project to a secondary Language resource in other region. Next, explore the API reference docs to see what else you can do with authoring APIs.