Send queries to your custom Text Analytics for health model

After the deployment is added successfully, you can query the deployment to extract entities from your text based on the model you assigned to the deployment. You can query the deployment programmatically using the Prediction API.

Test deployed model

You can use Language Studio to submit the custom Text Analytics for health task and visualize the results.

To test your deployed models from within the Language Studio:

1. Select Testing deployments from the left side menu.

2. Select the deployment you want to test. You can only test models that are assigned to deployments.

3. For multilingual projects, from the language dropdown, select the language of the text you are testing.

4. Select the deployment you want to query/test from the dropdown.

5. You can enter the text you want to submit to the request or upload a .txt file to use.

6. Select Run the test from the top menu.

7. In the Result tab, you can see the extracted entities from your text and their types. You can also view the JSON response under the JSON tab.

Send a custom text analytics for health request to your model

Language Studio

1. After the deployment job is completed successfully, select the deployment you want to use and from the top menu select Get prediction URL.

   

2. In the window that appears, under the Submit pivot, copy the sample request URL and body. Replace the placeholder values such as YOUR_DOCUMENT_HERE and YOUR_DOCUMENT_LANGUAGE_HERE with the actual text and language you want to process.

3. Submit the POST cURL request in your terminal or command prompt. You'll receive a 202 response with the API results if the request was successful.

4. In the response header you receive extract {JOB-ID} from operation-location, which has the format: {ENDPOINT}/language/analyze-text/jobs/<JOB-ID}>

5. Back to Language Studio; select Retrieve pivot from the same window you got the example request you got earlier and copy the sample request into a text editor.

6. Add your job ID after /jobs/ to the URL, using the ID you extracted from the previous step.

7. Submit the GET cURL request in your terminal or command prompt.

REST API

First you will need to get your resource key and endpoint:

1. Go to your resource overview page in the Azure portal

2. From the menu on the left side, select Keys and Endpoint. You'll use the endpoint and key for the API requests

   

Submit a custom Text Analytics for health task

Use this POST request to start a Custom Text Analytics for health extraction task.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}

Placeholder	Value	Example
{ENDPOINT}	The endpoint for authenticating your API request.	https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION}	The version of the API you are calling. The value referenced here is for the latest version released. See Model lifecycle to learn more about other available API versions.	2022-05-01

Headers

Key	Value
Ocp-Apim-Subscription-Key	Your key that provides access to this API.

Body

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomHealthcare",
      "taskName": "Custom TextAnalytics for Health Test",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Key	Placeholder	Value	Example
displayName	{JOB-NAME}	Your job name.	MyJobName
documents	[{},{}]	List of documents to run tasks on.	[{},{}]
id	{DOC-ID}	Document name or ID.	doc1
language	{LANGUAGE-CODE}	A string specifying the language code for the document. If this key isn't specified, the service will assume the default language of the project that was selected during project creation. See language support for a list of supported language codes.	en-us
text	{DOC-TEXT}	Document task to run the tasks on.	Lorem ipsum dolor sit amet
tasks		List of tasks we want to perform.	[]
taskName	Custom Text Analytics for Health Test	The task name	Custom Text Analytics for Health Test
kind	CustomHealthcare	The project or task kind we are trying to perform	CustomHealthcare
parameters		List of parameters to pass to the task.
project-name	{PROJECT-NAME}	The name for your project. This value is case-sensitive.	myProject
deployment-name	{DEPLOYMENT-NAME}	The name of your deployment. This value is case-sensitive.	prod

Response

You will receive a 202 response indicating that your task has been submitted successfully. In the response headers, extract operation-location. operation-location is formatted like this:

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

You can use this URL to query the task completion status and get the results when task is completed.

Get task results

Use the following GET request to query the status/results of the custom entity recognition task.

{ENDPOINT}/language/analyze-text/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
{API-VERSION}	The version of the API you're calling. The value referenced here is for the latest version released. See Model lifecycle to learn more about other available API versions.	2022-05-01

Headers

Key	Value
Ocp-Apim-Subscription-Key	Your key that provides access to this API.

Response Body

The response is a JSON document with the following parameters

{
	"createdDateTime": "2021-05-19T14:32:25.578Z",
	"displayName": "MyJobName",
	"expirationDateTime": "2021-05-19T14:32:25.578Z",
	"jobId": "xxxx-xxxx-xxxxx-xxxxx",
	"lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
	"status": "succeeded",
	"tasks": {
		"completed": 1,
		"failed": 0,
		"inProgress": 0,
		"total": 1,
		"items": [
			{
				"kind": "CustomHealthcareLROResults",
				"taskName": "Custom Text Analytics for Health Test",
				"lastUpdateDateTime": "2020-10-01T15:01:03Z",
				"status": "succeeded",
				"results": {
					"documents": [
						{
							"entities": [
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "learnedComponent"
										}
									],
									"offset": 0,
									"length": 11,
									"text": "first entity",
									"category": "Entity1",
									"confidenceScore": 0.98
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "listComponent"
										}
									],
									"offset": 0,
									"length": 11,
									"text": "first entity",
									"category": "Entity1.Dictionary",
									"confidenceScore": 1.0
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "learnedComponent"
										}
									],
									"offset": 16,
									"length": 9,
									"text": "entity two",
									"category": "Entity2",
									"confidenceScore": 1.0
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "prebuiltComponent"
										}
									],
									"offset": 37,
									"length": 9,
									"text": "ibuprofen",
									"category": "MedicationName",
									"confidenceScore": 1,
									"assertion": {
										"certainty": "negative"
									},
									"name": "ibuprofen",
									"links": [
										{
											"dataSource": "UMLS",
											"id": "C0020740"
										},
										{
											"dataSource": "AOD",
											"id": "0000019879"
										},
										{
											"dataSource": "ATC",
											"id": "M01AE01"
										},
										{
											"dataSource": "CCPSS",
											"id": "0046165"
										},
										{
											"dataSource": "CHV",
											"id": "0000006519"
										},
										{
											"dataSource": "CSP",
											"id": "2270-2077"
										},
										{
											"dataSource": "DRUGBANK",
											"id": "DB01050"
										},
										{
											"dataSource": "GS",
											"id": "1611"
										},
										{
											"dataSource": "LCH_NW",
											"id": "sh97005926"
										},
										{
											"dataSource": "LNC",
											"id": "LP16165-0"
										},
										{
											"dataSource": "MEDCIN",
											"id": "40458"
										},
										{
											"dataSource": "MMSL",
											"id": "d00015"
										},
										{
											"dataSource": "MSH",
											"id": "D007052"
										},
										{
											"dataSource": "MTHSPL",
											"id": "WK2XYI10QM"
										},
										{
											"dataSource": "NCI",
											"id": "C561"
										},
										{
											"dataSource": "NCI_CTRP",
											"id": "C561"
										},
										{
											"dataSource": "NCI_DCP",
											"id": "00803"
										},
										{
											"dataSource": "NCI_DTP",
											"id": "NSC0256857"
										},
										{
											"dataSource": "NCI_FDA",
											"id": "WK2XYI10QM"
										},
										{
											"dataSource": "NCI_NCI-GLOSS",
											"id": "CDR0000613511"
										},
										{
											"dataSource": "NDDF",
											"id": "002377"
										},
										{
											"dataSource": "PDQ",
											"id": "CDR0000040475"
										},
										{
											"dataSource": "RCD",
											"id": "x02MO"
										},
										{
											"dataSource": "RXNORM",
											"id": "5640"
										},
										{
											"dataSource": "SNM",
											"id": "E-7772"
										},
										{
											"dataSource": "SNMI",
											"id": "C-603C0"
										},
										{
											"dataSource": "SNOMEDCT_US",
											"id": "387207008"
										},
										{
											"dataSource": "USP",
											"id": "m39860"
										},
										{
											"dataSource": "USPMG",
											"id": "MTHU000060"
										},
										{
											"dataSource": "VANDF",
											"id": "4017840"
										}
									]
								},
								{
									"entityComponentInformation": [
										{
											"entityComponentKind": "prebuiltComponent"
										}
									],
									"offset": 30,
									"length": 6,
									"text": "100 mg",
									"category": "Dosage",
									"confidenceScore": 0.98
								}
							],
							"relations": [
								{
									"confidenceScore": 1,
									"relationType": "DosageOfMedication",
									"entities": [
										{
											"ref": "#/documents/0/entities/1",
											"role": "Dosage"
										},
										{
											"ref": "#/documents/0/entities/0",
											"role": "Medication"
										}
									]
								}
							],
							"id": "1",
							"warnings": []
						}
					],
					"errors": [],
					"modelVersion": "2020-04-01"
				}
			}
		]
	}
}

Key	Sample Value	Description
entities	[]	An array containing all the extracted entities.
entityComponentKind	prebuiltComponent	A variable that indicates which component returned the specific entity. Possible values: prebuiltComponent, learnedComponent, listComponent
offset	0	A number denoting the starting point of the extracted entity by indexing over the characters
length	10	A number denoting the length of the extracted entity in number of characters.
text	first entity	The text that was extracted for a specific entity.
category	MedicationName	The name of the entity type or category corresponding to the extracted text.
confidenceScore	0.9	A number denoting the model's certainty level of the extracted entity ranging from 0 to 1 with higher number denoting higher certainty.
assertion	certainty	Assertions associated with the extracted entity. Assertions are only supported for prebuilt Text Analytics for health entities.
name	Ibuprofen	The normalized name for the entity linking associated with the extracted entity. Entity linking is only supported for prebuilt Text Analytics for health entities.
links	[]	An array containing all the results from the entity linking associated with the extracted entity. Entity linking is only supported for prebuilt Text Analytics for health entities.
dataSource	UMLS	The reference standard resulting from the entity linking associated with the extracted entity. Entity linking is only supported for prebuilt Text Analytics for health entities.
ID	C0020740	The reference code resulting from the entity linking associated with the extracted entity belonging to the extracted data source. Entity linking is only supported for prebuilt Text Analytics for health entities.
relations	[]	Array containing all the extracted relationships. Relationship extraction is only supported for prebuilt Text Analytics for health entities.
relationType	DosageOfMedication	The category of the extracted relationship. Relationship extraction is only supported for prebuilt Text Analytics for health entities.
entities	"Dosage", "Medication"	The entities associated with the extracted relationship. Relationship extraction is only supported for prebuilt Text Analytics for health entities.

Next steps

• Custom text analytics for health