Skip to content

Commit add5601

Browse files
denreadenrea
authored
Merge pull request #234145 from aahill/ta4h-rest-api
Custom text analytics for health rest api
2 parents 3cb1a00 + bd2fea3 commit add5601

File tree

14 files changed

+1157
-7
lines changed

14 files changed

+1157
-7
lines changed

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/get-keys-endpoint-azure.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
services: cognitive-services
3+
author: aahill
4+
manager: nitinme
5+
ms.service: cognitive-services
6+
ms.subservice: language-service
7+
ms.custom: event-tier1-build-2022
8+
ms.topic: include
9+
ms.date: 05/05/2022
10+
ms.author: aahi
11+
---
12+
13+
1. Go to your resource overview page in the [Azure portal](https://portal.azure.com/#home)
14+
15+
2. From the menu on the left side, select **Keys and Endpoint**. You'll use the endpoint and key for the API requests
16+
17+
:::image type="content" source="../../custom-text-classification/media/get-endpoint-azure.png" alt-text="A screenshot showing the key and endpoint page in the Azure portal" lightbox="../../custom-text-classification/media/get-endpoint-azure.png":::

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/quickstarts/rest-api.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
author: aahill
3+
manager: nitinme
4+
ms.service: cognitive-services
5+
ms.subservice: language-service
6+
ms.custom: event-tier1-build-2022
7+
ms.topic: include
8+
ms.date: 06/07/2022
9+
ms.author: aahi
10+
---
11+
12+
## Prerequisites
13+
14+
* Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
15+
16+
> [!div class="nextstepaction"]
17+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Trigger-import-project-job" target="_target">I ran into an issue</a>
18+
19+
## Create a new Azure Language resource and Azure storage account
20+
21+
Before you can use custom Text Analytics for health, you'll need to create an Azure Language resource, which will give you the credentials that you need to create a project and start training a model. You'll also need an Azure storage account, where you can upload your dataset that will be used in building your model.
22+
23+
> [!IMPORTANT]
24+
> To get started quickly, we recommend creating a new Azure Language resource using the steps provided in this article, which will let you create the Language resource, and create and/or connect a storage account at the same time, which is easier than doing it later.
25+
26+
<!--
27+
> If you have a pre-existing resource that you'd like to use, you will need to connect it to storage account. See [create project](../../how-to/create-project.md#using-a-pre-existing-language-resource) for information.
28+
-->
29+
[!INCLUDE [create a new resource from the Azure portal](../resource-creation-azure-portal.md)]
30+
31+
> [!div class="nextstepaction"]
32+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Create-new-resource" target="_target">I ran into an issue</a>
33+
34+
## Upload sample data to blob container
35+
36+
[!INCLUDE [Uploading sample data for custom Text Analytics for health](blob-storage-upload.md)]
37+
38+
> [!div class="nextstepaction"]
39+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Upload-sample-data-to-blob-container" target="_target">I ran into an issue</a>
40+
41+
### Get your resource keys and endpoint
42+
43+
[!INCLUDE [Get keys and endpoint Azure Portal](../get-keys-endpoint-azure.md)]
44+
45+
> [!div class="nextstepaction"]
46+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Get-resource-keys-and-endpoint" target="_target">I ran into an issue</a>
47+
48+
## Create a custom Text Analytics for health project
49+
50+
Once your resource and storage account are configured, create a new custom Text Analytics for health project. A project is a work area for building your custom ML models based on your data. Your project can only be accessed by you and others who have access to the Language resource being used.
51+
52+
Use the labels file you downloaded from the sample data in the previous step and add it to the body of the following request.
53+
54+
### Trigger import project job
55+
56+
[!INCLUDE [Import a project using the REST API](../rest-api/import-project.md)]
57+
58+
> [!div class="nextstepaction"]
59+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Trigger-import-project-job" target="_target">I ran into an issue</a>
60+
61+
### Get import job status
62+
63+
[!INCLUDE [get import project status](../rest-api/get-import-status.md)]
64+
65+
> [!div class="nextstepaction"]
66+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Get-import-job-status" target="_target">I ran into an issue</a>
67+
68+
## Train your model
69+
70+
Typically after you create a project, you go ahead and start labeling the documents you have in the container connected to your project. For this quickstart, you have imported a sample tagged dataset and initialized your project with the sample JSON tags file.
71+
72+
### Start training job
73+
74+
After your project has been imported, you can start training your model.
75+
76+
[!INCLUDE [train model](../rest-api/train-model.md)]
77+
78+
> [!div class="nextstepaction"]
79+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Start-training-your-job" target="_target">I ran into an issue</a>
80+
81+
### Get training job status
82+
83+
Training could take sometime between 10 and 30 minutes for this sample dataset. You can use the following request to keep polling the status of the training job until it is successfully completed.
84+
85+
[!INCLUDE [get training model status](../rest-api/get-training-status.md)]
86+
87+
> [!div class="nextstepaction"]
88+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Get-training-job-status" target="_target">I ran into an issue</a>
89+
90+
## Deploy your model
91+
92+
Generally after training a model you would review its evaluation details and make improvements if necessary. In this quickstart, you will just deploy your model, and make it available for you to try in Language Studio, or you can call the [prediction API](https://aka.ms/ct-runtime-swagger).
93+
94+
### Start deployment job
95+
96+
[!INCLUDE [deploy model](../rest-api/deploy-model.md)]
97+
98+
> [!div class="nextstepaction"]
99+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Submit-deployment-job" target="_target">I ran into an issue</a>
100+
101+
### Get deployment job status
102+
103+
[!INCLUDE [get deployment status](../rest-api/get-deployment-status.md)]
104+
105+
> [!div class="nextstepaction"]
106+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Get-deployment-job-status" target="_target">I ran into an issue</a>
107+
108+
## Make predictions with your trained model
109+
110+
After your model is deployed, you can start using it to extract entities from your text using the [prediction API](https://aka.ms/ct-runtime-swagger). In the sample dataset you downloaded earlier you can find some test documents that you can use in this step.
111+
112+
### Submit a custom Text Analytics for health task
113+
114+
[!INCLUDE [submit a custom Text Analytics for health task using the REST API](../rest-api/submit-task.md)]
115+
116+
> [!div class="nextstepaction"]
117+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Submit-custom-text-analytics-for-health-task" target="_target">I ran into an issue</a>
118+
119+
### Get task results
120+
121+
[!INCLUDE [get custom Text Analytics for health task results](../rest-api/get-results.md)]
122+
123+
> [!div class="nextstepaction"]
124+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Get-task-results" target="_target">I ran into an issue</a>
125+
126+
## Clean up resources
127+
128+
[!INCLUDE [Delete project using the REST API](../rest-api/delete-project.md)]
129+
130+
> [!div class="nextstepaction"]
131+
> <a href="https://microsoft.qualtrics.com/jfe/form/SV_0Cl5zkG3CnDjq6O?PLanguage=REST API&Pillar=Language&Product=Custom-text-analytics-for-health&Page=quickstart&Section=Clean-up-resources" target="_target">I ran into an issue</a>

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/create-project.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
services: cognitive-services
3+
author: aahill
4+
manager: nitinme
5+
ms.service: cognitive-services
6+
ms.subservice: language-service
7+
ms.topic: include
8+
ms.date: 04/06/2022
9+
ms.author: aahi
10+
---
11+
To start creating a custom Text Analytics for health model, you need to create a project. Creating a project will let you label data, train, evaluate, improve, and deploy your models.
12+
13+
> [!NOTE]
14+
> The project name is case-sensitive for all operations.
15+
16+
Create a **PATCH** request using the following URL, headers, and JSON body to create your project.
17+
18+
### Request URL
19+
20+
Use the following URL to create a project. Replace the placeholder values below with your own values.
21+
22+
```rest
23+
{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
24+
```
25+
26+
|Placeholder |Value | Example |
27+
|---------|---------|---------|
28+
|`{ENDPOINT}` | The endpoint for authenticating your API request. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
29+
|`{PROJECT-NAME}` | The name for your project. This value is case-sensitive. | `myProject` |
30+
|`{API-VERSION}` | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions. | `2022-05-01` |
31+
32+
33+
### Headers
34+
35+
Use the following header to authenticate your request.
36+
37+
|Key|Value|
38+
|--|--|
39+
|`Ocp-Apim-Subscription-Key`| The key to your resource. Used for authenticating your API requests.|
40+
41+
### Body
42+
43+
Use the following JSON in your request. Replace the placeholder values below with your own values.
44+
45+
```json
46+
{
47+
"projectName": "{PROJECT-NAME}",
48+
"language": "{LANGUAGE-CODE}",
49+
"projectKind": "CustomHealthcare",
50+
"description": "Project description",
51+
"multilingual": "True",
52+
"storageInputContainerName": "{CONTAINER-NAME}"
53+
}
54+
55+
```
56+
57+
|Key |Placeholder|Value | Example |
58+
|---------|---------|---------|--|
59+
| projectName | `{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `myProject` |
60+
| language | `{LANGUAGE-CODE}` | A string specifying the language code for the documents used in your project. If your project is a multilingual project, choose the language code of the majority of the documents. See [language support](../../language-support.md) to learn more about supported language codes. |`en-us`|
61+
| projectKind | `CustomHealthcare` | Your project kind. | `CustomHealthcare` |
62+
| multilingual | `true`| A boolean value that enables you to have documents in multiple languages in your dataset and when your model is deployed you can query the model in any supported language (not necessarily included in your training documents. See [language support](../../language-support.md) to learn more about multilingual support. | `true`|
63+
| storageInputContainerName | `{CONTAINER-NAME` | The name of your Azure storage container where you have uploaded your documents. | `myContainer` |
64+
65+
66+
67+
68+
This request will return a 201 response, which means that the project is created.
69+
70+
71+
This request will return an error if:
72+
* The selected resource doesn't have proper permission for the storage account.
73+

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/delete-project.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
author: aahill
3+
manager: nitinme
4+
ms.service: cognitive-services
5+
ms.subservice: language-service
6+
ms.custom: event-tier1-build-2022
7+
ms.topic: include
8+
ms.date: 05/05/2022
9+
ms.author: aahi
10+
---
11+
12+
When you no longer need your project, you can delete it with the following **DELETE** request. Replace the placeholder values with your own values.
13+
14+
```rest
15+
{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}
16+
```
17+
18+
|Placeholder |Value | Example |
19+
|---------|---------|---------|
20+
|`{ENDPOINT}` | The endpoint for authenticating your API request. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
21+
|`{PROJECT-NAME}` | The name for your project. This value is case-sensitive. | `myProject` |
22+
|`{API-VERSION}` | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions. | `2022-05-01` |
23+
24+
### Headers
25+
26+
Use the following header to authenticate your request.
27+
28+
|Key|Value|
29+
|--|--|
30+
|Ocp-Apim-Subscription-Key| The key to your resource. Used for authenticating your API requests.|
31+
32+
33+
Once you send your API request, you will receive a `202` response indicating success, which means your project has been deleted. A successful call results with an Operation-Location header used to check the status of the job.

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/deploy-model.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
services: cognitive-services
3+
author: aahill
4+
manager: nitinme
5+
ms.service: cognitive-services
6+
ms.subservice: language-service
7+
ms.custom: event-tier1-build-2022
8+
ms.topic: include
9+
ms.date: 04/25/2022
10+
ms.author: aahi
11+
---
12+
13+
Submit a **PUT** request using the following URL, headers, and JSON body to submit a deployment job. Replace the placeholder values below with your own values.
14+
15+
```rest
16+
{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}
17+
```
18+
19+
| Placeholder |Value | Example |
20+
|---------|---------|---------|
21+
| `{ENDPOINT}` | The endpoint for authenticating your API request. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
22+
| `{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `myProject` |
23+
| `{DEPLOYMENT-NAME}` | The name of your deployment. This value is case-sensitive. | `staging` |
24+
|`{API-VERSION}` | The version of the API you're calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions. | `2022-05-01` |
25+
26+
#### Headers
27+
28+
Use the following header to authenticate your request.
29+
30+
|Key|Value|
31+
|--|--|
32+
|`Ocp-Apim-Subscription-Key`| The key to your resource. Used for authenticating your API requests.|
33+
34+
#### Request body
35+
36+
Use the following JSON in the body of your request. Use the name of the model you to assign to the deployment.
37+
38+
```json
39+
{
40+
"trainedModelLabel": "{MODEL-NAME}"
41+
}
42+
```
43+
44+
|Key |Placeholder |Value | Example |
45+
|---------|---------|-----|----|
46+
| 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` |
47+
48+
Once you send your API request, you’ll receive a `202` response indicating that the job was submitted correctly. In the response headers, extract the `operation-location` value. It will be formatted like this:
49+
50+
```rest
51+
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
52+
```
53+
54+
`{JOB-ID}` is used to identify your request, since this operation is asynchronous. You can use this URL to get the deployment status.

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/get-deployment-status.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
services: cognitive-services
3+
author: aahill
4+
manager: nitinme
5+
ms.service: cognitive-services
6+
ms.subservice: language-service
7+
ms.custom: event-tier1-build-2022
8+
ms.topic: include
9+
ms.date: 05/05/2022
10+
ms.author: aahi
11+
---
12+
13+
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 below with your own values.
14+
15+
```rest
16+
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
17+
```
18+
19+
| Placeholder |Value | Example |
20+
|---------|---------|---------|
21+
| `{ENDPOINT}` | The endpoint for authenticating your API request. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
22+
| `{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `myProject` |
23+
| `{DEPLOYMENT-NAME}` | The name of your deployment. This value is case-sensitive. | `staging` |
24+
|`{JOB-ID}` | The ID for locating your model's training status. This is in the `location` header value you received in the previous step. | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx` |
25+
|`{API-VERSION}` | The version of the API you're calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions. | `2022-05-01` |
26+
27+
#### Headers
28+
29+
Use the following header to authenticate your request.
30+
31+
|Key|Value|
32+
|--|--|
33+
|`Ocp-Apim-Subscription-Key`| The key to your resource. Used for authenticating your API requests.|
34+
35+
36+
### Response Body
37+
38+
You'll receive the following request when you send the request. Keep polling this endpoint until the **status** parameter changes to "succeeded". You should get a `200` code to indicate the success of the request.
39+
40+
```json
41+
{
42+
"jobId":"{JOB-ID}",
43+
"createdDateTime":"{CREATED-TIME}",
44+
"lastUpdatedDateTime":"{UPDATED-TIME}",
45+
"expirationDateTime":"{EXPIRATION-TIME}",
46+
"status":"running"
47+
}
48+
```
49+

‎articles/cognitive-services/language-service/custom-text-analytics-for-health/includes/rest-api/get-import-status.md

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
author: aahill
3+
manager: nitinme
4+
ms.service: cognitive-services
5+
ms.subservice: language-service
6+
ms.custom: event-tier1-build-2022
7+
ms.topic: include
8+
ms.date: 05/05/2022
9+
ms.author: aahi
10+
---
11+
12+
Use the following **GET** request to get the status of your importing your project. Replace the placeholder values below with your own values.
13+
14+
### Request URL
15+
16+
```rest
17+
{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
18+
```
19+
20+
|Placeholder |Value | Example |
21+
|---------|---------|---------|
22+
|`{ENDPOINT}` | The endpoint for authenticating your API request. | `https://<your-custom-subdomain>.cognitiveservices.azure.com` |
23+
|`{PROJECT-NAME}` | The name of your project. This value is case-sensitive. | `myProject` |
24+
|`{JOB-ID}` | The ID for locating your model's training status. This value is in the `location` header value you received in the previous step. | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx` |
25+
|`{API-VERSION}` | The version of the API you are calling. The value referenced here is for the latest version released. See [Model lifecycle](../../../concepts/model-lifecycle.md#choose-the-model-version-used-on-your-data) to learn more about other available API versions. | `2022-05-01` |
26+
27+
#### Headers
28+
29+
Use the following header to authenticate your request.
30+
31+
|Key|Value|
32+
|--|--|
33+
|`Ocp-Apim-Subscription-Key`| The key to your resource. Used for authenticating your API requests.|
34+

0 commit comments

Comments
 (0)