Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Once you're satisfied with how your model performs, it's ready to be deployed; and use it to classify text. Deploying a model makes it available for use through the prediction API.
Prerequisites
- A custom text classification project with a configured Azure storage account,
- Text data that is uploaded to your storage account.
- Labeled data and successfully trained model
- Reviewed the model evaluation details to determine how your model is performing.
See the project development lifecycle.
Deploy model (REST API)
After you review your model's performance and decided it can be used in your environment, you need to assign it to a deployment to be able to query it. Assigning the model to a deployment makes it available for use through the prediction API. We recommend that you create a deployment named production to which you assign the best model you built so far and use it in your system. You can create another deployment called staging to which you can assign the model you're currently working on to be able to test it. You can have a maximum on 10 deployments in your project.
Submit deployment job
Submit a PUT request using the following URL, headers, and JSON body to submit a deployment job. Replace the placeholder values with your own values.
{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?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 of your project. This value is case-sensitive. | myProject |
{DEPLOYMENT-NAME} |
The name of your deployment. This value is case-sensitive. | staging |
{API-VERSION} |
The version of the API you're calling. The value referenced is for the latest version released. Learn more about other available API versions | 2022-05-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 JSON in the body of your request. Use the name of the model you to assign to the deployment.
{
"trainedModelLabel": "{MODEL-NAME}"
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
| trainedModelLabel | {MODEL-NAME} |
The model name that is assigned to your deployment. You can only assign successfully trained models. This value is case-sensitive. | myModel |
Once you send your API request, you receive a 202 response indicating that the job was submitted correctly. In the response headers, extract the operation-location value formatted like this:
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
{JOB-ID} is used to identify your request, since this operation is asynchronous. You can use this URL to get the deployment status.
Get deployment job status
Use the following GET request to query the status of the deployment 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-text/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 of your project. This value is case-sensitive. | myProject |
{DEPLOYMENT-NAME} |
The name of your deployment. This value is case-sensitive. | staging |
{JOB-ID} |
The ID for locating your model's training status. It's in the location header value you received in the previous step. |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you're calling. The value referenced is for the latest version released. Learn more about other available API versions | 2022-05-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 get the following response. Keep polling this endpoint until the status parameter changes to "succeeded". You should get a 200 code to indicate the success of the request.
{
"jobId":"{JOB-ID}",
"createdDateTime":"{CREATED-TIME}",
"lastUpdatedDateTime":"{UPDATED-TIME}",
"expirationDateTime":"{EXPIRATION-TIME}",
"status":"running"
}
Swap deployments (REST API)
You can swap deployments after testing a model assigned to one deployment, and want to assign it to another. Swapping deployments involves taking the model assigned to the first deployment, and assigning it to the second deployment. Then taking the model assigned to second deployment and assign it to the first deployment. This step could be used to swap your production and staging deployments when you want to take the model assigned to staging and assign it to production.
Create a POST request using the following URL, headers, and JSON body to start a swap deployments job.
Request URL
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/:swap?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're calling. The value referenced is for the latest model version released. | 2022-05-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
{
"firstDeploymentName": "{FIRST-DEPLOYMENT-NAME}",
"secondDeploymentName": "{SECOND-DEPLOYMENT-NAME}"
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
| firstDeploymentName | {FIRST-DEPLOYMENT-NAME} |
The name for your first deployment. This value is case-sensitive. | production |
| secondDeploymentName | {SECOND-DEPLOYMENT-NAME} |
The name for your second deployment. This value is case-sensitive. | staging |
Once you send your API request, you receive a 202 response indicating success.
Delete deployment (REST API)
Create a DELETE request using the following URL, headers, and JSON body to delete a deployment.
Request URL
{Endpoint}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{deploymentName}?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 name. This value is case-sensitive. | prod |
{API-VERSION} |
The version of the API you're calling. The value referenced is for the latest version released. Learn more about other available API versions | 2022-05-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 receive a 202 response indicating success, which means your deployment is deleted. A successful call results with an Operation-Location header used to check the status of the job.
Assign deployment resources (REST API)
You can deploy your project to multiple regions by assigning different Language resources that exist in different regions.
Assigning deployment resources programmatically requires Microsoft Entra authentication. Microsoft Entra ID is used to confirm you have access to the resources you're interested in assigning to your project for multi-region deployment. To programmatically use Microsoft Entra authentication when making REST API calls, learn more from the Foundry Tools documentation.
Assign resource
Submit a POST request using the following URL, headers, and JSON body to assign deployment resources.
Request URL
Use the following URL when creating your API request. Replace the placeholder values with your own values.
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/:assign?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're calling. | 2022-10-01-preview |
Headers
Use Microsoft Entra authentication to authenticate this API.
Body
Use the following sample JSON as your body.
{
"resourcesMetadata": [
{
"azureResourceId": "{AZURE-RESOURCE-ID}",
"customDomain": "{CUSTOM-DOMAIN}",
"region": "{REGION-CODE}"
}
]
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
azureResourceId |
{AZURE-RESOURCE-ID} |
The full resource ID path you want to assign. Found in the Azure portal under the Properties tab for the resource, in the Resource ID field. | /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource |
customDomain |
{CUSTOM-DOMAIN} |
The custom subdomain of the resource you want to assign. Found in the Azure portal under the Keys and Endpoint tab for the resource, as the Endpoint field in the URL https://<your-custom-subdomain>.cognitiveservices.azure.com/ |
contosoresource |
region |
{REGION-CODE} |
A region code specifying the region of the resource you want to assign. Found in the Azure portal under the Keys and Endpoint tab for the resource, in the Location/Region field. | eastus |
Get assign resource status
Use the following GET request to get the status of your assign deployment resource job. Replace the placeholder values with your own values.
Request URL
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/assign/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 job ID for getting your assign deployment status. It's in the operation-location header value you received from the API in response to your assign deployment resource request. |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you're calling. | 2022-10-01-preview |
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 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"
}
Unassign deployment resources (REST API)
When you unassign or remove a deployment resource from a project, you also delete all the deployments previously deployed to that resource region.
Unassign resource
Submit a POST request using the following URL, headers, and JSON body to unassign or remove deployment resources from 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-text/projects/{PROJECT-NAME}/resources/:unassign?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're calling. | 2022-10-01-preview |
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
Use the following sample JSON as your body.
{
"assignedResourceIds": [
"{AZURE-RESOURCE-ID}"
]
}
| Key | Placeholder | Value | Example |
|---|---|---|---|
assignedResourceIds |
{AZURE-RESOURCE-ID} |
The full resource ID path you want to unassign. Found in the Azure portal under the Properties tab for the resource as the Resource ID field. | /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourceGroups/ContosoResourceGroup/providers/Microsoft.CognitiveServices/accounts/ContosoResource |
Get unassign resource status
Use the following GET request to get the status of your unassign deployment resources job. Replace the placeholder values with your own values.
Request URL
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/resources/unassign/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 job ID for getting your assign deployment status. It's in the operation-location header value you received from the API in response to your unassign deployment resource request. |
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx |
{API-VERSION} |
The version of the API you're calling. | 2022-10-01-preview |
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 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"
}