Skip to content

Commit b5d7781

Browse files
abhahnAbigail HartmankayousefAbby Hartman
authored
Language API for TA (2022-02-01-preview) (#16921)
* WIP for language api spec for TA * Updated preview version number; finished up async definitions * Finished first draft of full spec * Finished first draft of full spec, minus FHIR structuring in HC output * Removed features not included in 2021-11-01 preview * Update custom text tasks TODOs * Moved common definitions to TA-specific definitions * Added custom text tasks to JobManifest * Addressing feedback from PR comments and internal review * Addressed some PR comments * Updated some remaining references to documents * PR comments * Updated a previous change * Reverted references to 'records' back to 'documents' * A few small updates to examples; removed base Task type to simplify structure * PR comments * Addressed TODO items; removed LD-related objects (will be added in another preview) * Fixed anonymous types * Removed required field for body in POST request * Fix prettier check * Added a few more details; experimental change for documents property * Ran prettier * Correction to AnalysisInput object * Merged changes from 2021-11-01-preview and moved new changes to 2022-02-01 * PR comments * Updates to the design for tasks * Added custom entities task to examples * Updates * Finished implementation of discriminator pattern and added some exmaples * Updates * Prettier * Fixed semantic validation errors * Fixed model validation * Another model validation fix * Debugging model validation errors * Using a different discriminator enum for output schemas * Fixed some missing discriminator updates * More semantic validation fixes * Fixed model validation errors; updated sample names * Fixed linting errors and addressed some warnings in the linter output * Ran prettier on examples * PR comments and some minor restructuring * Ran prettier * Removed a duplicate schema from CustomEntitiesTaskParameters * PR comments * PR comments * PR comments * Added missing job task status 'partiallySucceeded' * PR comments * Fix typo causing spell check error * Using common skip and top parameters * Using common StringIndexType definition * Reverted changes to taskName * Updated example * Description update * Description update * PR comments * Updated examples * Fixed issues in examples Co-authored-by: Abigail Hartman <Abigail.Hartman@microsoft.com> Co-authored-by: Kareem Yousef <kayousef@microsoft.com> Co-authored-by: Abby Hartman <abhahn@microsoft.com>
1 parent 5582a35 commit b5d7781

11 files changed

+3888
-1
lines changed

‎specification/cognitiveservices/data-plane/Language/preview/2022-02-01-preview/common.json‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"title": "Microsoft Cognitive Language Service",
5+
"description": "The language service API is a suite of natural language processing (NLP) skills built with best-in-class Microsoft machine learning algorithms. The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language detection and question answering. Further documentation can be found in <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview\">https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview</a>.",
6+
"version": "2022-02-01-preview"
7+
},
8+
"paths": {},
9+
"definitions": {
10+
"ErrorResponse": {
11+
"type": "object",
12+
"description": "Error response.",
13+
"additionalProperties": false,
14+
"properties": {
15+
"error": {
16+
"description": "The error object.",
17+
"$ref": "#/definitions/Error"
18+
}
19+
}
20+
},
21+
"Error": {
22+
"type": "object",
23+
"description": "The error object.",
24+
"additionalProperties": false,
25+
"required": [
26+
"code",
27+
"message"
28+
],
29+
"properties": {
30+
"code": {
31+
"description": "One of a server-defined set of error codes.",
32+
"$ref": "#/definitions/ErrorCode"
33+
},
34+
"message": {
35+
"type": "string",
36+
"description": "A human-readable representation of the error."
37+
},
38+
"target": {
39+
"type": "string",
40+
"description": "The target of the error."
41+
},
42+
"details": {
43+
"type": "array",
44+
"description": "An array of details about specific errors that led to this reported error.",
45+
"items": {
46+
"$ref": "#/definitions/Error"
47+
}
48+
},
49+
"innererror": {
50+
"description": "An object containing more specific information than the current object about the error.",
51+
"$ref": "#/definitions/InnerErrorModel"
52+
}
53+
}
54+
},
55+
"InnerErrorModel": {
56+
"type": "object",
57+
"description": "An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.",
58+
"additionalProperties": false,
59+
"required": [
60+
"code",
61+
"message"
62+
],
63+
"properties": {
64+
"code": {
65+
"description": "One of a server-defined set of error codes.",
66+
"$ref": "#/definitions/InnerErrorCode"
67+
},
68+
"message": {
69+
"type": "string",
70+
"description": "Error message."
71+
},
72+
"details": {
73+
"type": "object",
74+
"additionalProperties": {
75+
"type": "string"
76+
},
77+
"description": "Error details."
78+
},
79+
"target": {
80+
"type": "string",
81+
"description": "Error target."
82+
},
83+
"innererror": {
84+
"description": "An object containing more specific information than the current object about the error.",
85+
"$ref": "#/definitions/InnerErrorModel"
86+
}
87+
}
88+
},
89+
"ErrorCode": {
90+
"type": "string",
91+
"description": "Human-readable error code.",
92+
"x-ms-enum": {
93+
"name": "ErrorCode",
94+
"modelAsString": true
95+
},
96+
"enum": [
97+
"InvalidRequest",
98+
"InvalidArgument",
99+
"Unauthorized",
100+
"Forbidden",
101+
"NotFound",
102+
"ProjectNotFound",
103+
"OperationNotFound",
104+
"AzureCognitiveSearchNotFound",
105+
"AzureCognitiveSearchIndexNotFound",
106+
"TooManyRequests",
107+
"AzureCognitiveSearchThrottling",
108+
"AzureCognitiveSearchIndexLimitReached",
109+
"InternalServerError",
110+
"ServiceUnavailable"
111+
]
112+
},
113+
"InnerErrorCode": {
114+
"type": "string",
115+
"description": "Human-readable error code.",
116+
"x-ms-enum": {
117+
"name": "InnerErrorCode",
118+
"modelAsString": true
119+
},
120+
"enum": [
121+
"InvalidRequest",
122+
"InvalidParameterValue",
123+
"KnowledgeBaseNotFound",
124+
"AzureCognitiveSearchNotFound",
125+
"AzureCognitiveSearchThrottling",
126+
"ExtractionFailure",
127+
"InvalidRequestBodyFormat",
128+
"EmptyRequest",
129+
"MissingInputDocuments",
130+
"InvalidDocument",
131+
"ModelVersionIncorrect",
132+
"InvalidDocumentBatch",
133+
"UnsupportedLanguageCode",
134+
"InvalidCountryHint"
135+
]
136+
},
137+
"Language": {
138+
"type": "string",
139+
"description": "Language of the text records. This is BCP-47 representation of a language. For example, use \"en\" for English; \"es\" for Spanish etc. If not set, use \"en\" for English as default."
140+
},
141+
"StringIndexType": {
142+
"type": "string",
143+
"description": "Specifies the method used to interpret string offsets. Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets.",
144+
"default": "TextElements_v8",
145+
"enum": [
146+
"TextElements_v8",
147+
"UnicodeCodePoint",
148+
"Utf16CodeUnit"
149+
],
150+
"x-ms-enum": {
151+
"name": "StringIndexType",
152+
"modelAsString": true,
153+
"values": [
154+
{
155+
"value": "TextElements_v8",
156+
"description": "Returned offset and length values will correspond to TextElements (Graphemes and Grapheme clusters) confirming to the Unicode 8.0.0 standard. Use this option if your application is written in .Net Framework or .Net Core and you will be using StringInfo."
157+
},
158+
{
159+
"value": "UnicodeCodePoint",
160+
"description": "Returned offset and length values will correspond to Unicode code points. Use this option if your application is written in a language that support Unicode, for example Python."
161+
},
162+
{
163+
"value": "Utf16CodeUnit",
164+
"description": "Returned offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript."
165+
}
166+
]
167+
}
168+
}
169+
},
170+
"parameters": {
171+
"Endpoint": {
172+
"name": "Endpoint",
173+
"description": "Supported Cognitive Services endpoint (e.g., https://<resource-name>.api.cognitiveservices.azure.com).",
174+
"x-ms-parameter-location": "client",
175+
"required": true,
176+
"type": "string",
177+
"in": "path",
178+
"x-ms-skip-url-encoding": true
179+
},
180+
"ProjectNameQueryParameter": {
181+
"name": "projectName",
182+
"in": "query",
183+
"required": true,
184+
"type": "string",
185+
"description": "The name of the project to use.",
186+
"x-ms-parameter-location": "method"
187+
},
188+
"ProjectNamePathParameter": {
189+
"name": "projectName",
190+
"in": "path",
191+
"required": true,
192+
"type": "string",
193+
"maxLength": 100,
194+
"description": "The name of the project to use.",
195+
"x-ms-parameter-location": "method"
196+
},
197+
"DeploymentNameQueryParameter": {
198+
"name": "deploymentName",
199+
"in": "query",
200+
"required": true,
201+
"type": "string",
202+
"description": "The name of the specific deployment of the project to use.",
203+
"x-ms-parameter-location": "method"
204+
},
205+
"DeploymentNamePathParameter": {
206+
"name": "deploymentName",
207+
"in": "path",
208+
"required": true,
209+
"type": "string",
210+
"description": "The name of the specific deployment of the project to use.",
211+
"x-ms-parameter-location": "method"
212+
},
213+
"ApiVersionParameter": {
214+
"name": "api-version",
215+
"in": "query",
216+
"required": true,
217+
"type": "string",
218+
"description": "Client API version."
219+
},
220+
"TopParameter": {
221+
"name": "top",
222+
"in": "query",
223+
"description": "The maximum number of resources to return from the collection.",
224+
"type": "integer",
225+
"format": "int32",
226+
"x-ms-parameter-location": "method"
227+
},
228+
"SkipParameter": {
229+
"name": "skip",
230+
"in": "query",
231+
"description": "An offset into the collection of the first resource to be returned.",
232+
"type": "integer",
233+
"format": "int32",
234+
"x-ms-parameter-location": "method"
235+
},
236+
"MaxPageSizeParameter": {
237+
"name": "maxpagesize",
238+
"in": "query",
239+
"description": "The maximum number of resources to include in a single response.",
240+
"type": "integer",
241+
"format": "int32",
242+
"x-ms-parameter-location": "method"
243+
}
244+
}
245+
}

‎specification/cognitiveservices/data-plane/Language/preview/2022-02-01-preview/examples/SuccessfulAnalyzeTextJobsMultipleTaskStatusRequest.json‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
{
2+
"parameters": {
3+
"Ocp-Apim-Subscription-Key": "{API key}",
4+
"api-version": "2022-02-01-preview",
5+
"Endpoint": "{Endpoint}",
6+
"jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18"
7+
},
8+
"responses": {
9+
"200": {
10+
"headers": {},
11+
"body": {
12+
"createdDateTime": "2020-10-01T15:00:45Z",
13+
"displayName": "Extracting Location & US Region",
14+
"expirationDateTime": "2020-10-03T15:01:03Z",
15+
"jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18",
16+
"lastUpdateDateTime": "2020-10-01T15:01:03Z",
17+
"status": "succeeded",
18+
"tasks": {
19+
"completed": 2,
20+
"failed": 0,
21+
"inProgress": 0,
22+
"total": 2,
23+
"items": [
24+
{
25+
"kind": "EntityRecognitionLROResults",
26+
"taskName": "Recognize Entities",
27+
"lastUpdateDateTime": "2020-10-01T15:01:03Z",
28+
"status": "succeeded",
29+
"results": {
30+
"documents": [
31+
{
32+
"entities": [
33+
{
34+
"category": "Event",
35+
"confidenceScore": 0.61,
36+
"length": 4,
37+
"offset": 18,
38+
"text": "trip"
39+
},
40+
{
41+
"category": "Location",
42+
"confidenceScore": 0.82,
43+
"length": 7,
44+
"offset": 26,
45+
"subcategory": "GPE",
46+
"text": "Seattle"
47+
},
48+
{
49+
"category": "DateTime",
50+
"confidenceScore": 0.8,
51+
"length": 9,
52+
"offset": 34,
53+
"subcategory": "DateRange",
54+
"text": "last week"
55+
}
56+
],
57+
"id": "1",
58+
"warnings": []
59+
},
60+
{
61+
"entities": [
62+
{
63+
"category": "Location",
64+
"confidenceScore": 0.52,
65+
"length": 3,
66+
"offset": 14,
67+
"subcategory": "GPE",
68+
"text": "NYC"
69+
},
70+
{
71+
"category": "DateTime",
72+
"confidenceScore": 0.8,
73+
"length": 8,
74+
"offset": 18,
75+
"subcategory": "Date",
76+
"text": "tomorrow"
77+
}
78+
],
79+
"id": "2",
80+
"warnings": []
81+
}
82+
],
83+
"errors": [],
84+
"modelVersion": "2020-04-01"
85+
}
86+
},
87+
{
88+
"kind": "CustomEntityRecognitionLROResults",
89+
"taskName": "Recognize US Regions",
90+
"lastUpdateDateTime": "2020-10-01T15:01:03Z",
91+
"status": "succeeded",
92+
"results": {
93+
"documents": [
94+
{
95+
"entities": [
96+
{
97+
"category": "USRegion",
98+
"confidenceScore": 0.85,
99+
"length": 17,
100+
"offset": 45,
101+
"text": "Pacific Northwest"
102+
}
103+
],
104+
"id": "1",
105+
"warnings": []
106+
},
107+
{
108+
"entities": [
109+
{
110+
"category": "USRegion",
111+
"confidenceScore": 0.88,
112+
"length": 10,
113+
"offset": 63,
114+
"text": "East Coast"
115+
}
116+
],
117+
"id": "2",
118+
"warnings": []
119+
}
120+
],
121+
"errors": [],
122+
"projectName": "MyProject",
123+
"deploymentName": "MyDeployment"
124+
}
125+
}
126+
]
127+
}
128+
}
129+
}
130+
}
131+
}

0 commit comments

Comments
 (0)