-
Notifications
You must be signed in to change notification settings - Fork 5.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add Text Analytics V3.0-Preview.1 #7133
Conversation
In Testing, Please Ignore[Logs] (Generated from 875b9ef, Iteration 24)Python: test-repo-billy/azure-sdk-for-python [Logs] [Diff]
Java: test-repo-billy/azure-sdk-for-java [Logs] [Diff]
Go: test-repo-billy/azure-sdk-for-go [Logs] [Diff]
JavaScript: test-repo-billy/azure-sdk-for-js [Logs] [Diff]
Ruby: test-repo-billy/azure-sdk-for-ruby [Logs] [Diff]
|
Automation for azure-sdk-for-pythonA PR has been created for you based on this PR content. Once this PR will be merged, content will be added to your service PR: |
Automation for azure-sdk-for-goNothing to generate for azure-sdk-for-go |
Can one of the admins verify this patch? |
...ication/cognitiveservices/data-plane/TextAnalytics/preview/v3.0-Preview.1/TextAnalytics.json
Outdated
Show resolved
Hide resolved
}, | ||
"/entities/linking" : { | ||
"post" : { | ||
"summary" : "Well-known entities.", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could we possibly improve this summary. Possibly "Extract well known entities from text." or something along those lines
...ication/cognitiveservices/data-plane/TextAnalytics/preview/v3.0-Preview.1/TextAnalytics.json
Outdated
Show resolved
Hide resolved
"parameters" : [ { | ||
"name" : "modelVersion", | ||
"in" : "query", | ||
"description" : "(optional) This value indicates which model be used for scoring .", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we may want to work on making this a little more descriptive or add alink to see where the versions are where that is ready
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Versions will change overtime. Might worth to add a link for release annoucement related with model versions?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
First pass. Please see comments.
"version" : "V3.0-Preview.1", | ||
"title" : "Text Analytics API (V3.0-Preview.1)" | ||
}, | ||
"host" : "westus.api.cognitive.microsoft.com", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure if the host
is needed in the spec repo. Check the previous spec to be sure.
"/entities" : { | ||
"post" : { | ||
"summary" : "Entities from open domain", | ||
"description" : "The API returns a list of general named entities (\\\"Person\\\", \\\"Location\\\", \\\"Organization\\\" etc) in a given document. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-entity-linking#supported-types-for-named-entity-recognition\">Supported Entity Types in Text Analytics API</a> for the list of supported Entity Types. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/text-analytics-supported-languages\">Supported languages in Text Analytics API</a> for the list of enabled languages.\n", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should change this description to not include the list of entity types and instead refer back to our documentation and an aka.ms/<> links.
"parameters" : [ { | ||
"name" : "modelVersion", | ||
"in" : "query", | ||
"description" : "(optional) This value indicates which model be used for scoring .", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: space before "."
} ], | ||
"responses" : { | ||
"200" : { | ||
"description" : "A successful call results in a list of recognized entities returned for each valid document", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit: end all descriptions with "."
"/entities/biomedical" : { | ||
"post" : { | ||
"summary" : "Entities from biomedical domain", | ||
"description" : "The API returns a list of biomedical entities (\\\"Treatment\\\", \\\"Medication\\\", \\\"Dosage\\\" etc) in a given document. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/text-analytics-supported-languages\">Supported languages in Text Analytics API</a> for the list of enabled languages.\n", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Same comments as before. We shouldn't specify the entity type list here, otherwise it may get very long and hard to keep up to date. We should link to a single page which would be the source of truth.
} | ||
}, | ||
"statistics" : { | ||
"description" : "(Optional) if showStats=true was specified in the request this field will contain information about the \r\n document payload." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We should probably group the statistics item under a new type. Not sure why this only has a description field.
...ication/cognitiveservices/data-plane/TextAnalytics/preview/v3.0-Preview.1/TextAnalytics.json
Outdated
Show resolved
Hide resolved
"$ref" : "#/definitions/MatchRecord" | ||
} | ||
}, | ||
"wikipediaLanguage" : { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we may want to change this to be more generic to support other data sources as well.
For example: have a dataSourceLanguage
, dataSourceId
, etc. and a dataSource
with a Wikipedia
value.
"wikipediaScore" : { | ||
"type" : "number", | ||
"format" : "double", | ||
"description" : "(optional) If a well-known item with Wikipedia link is recognized,\r\n a decimal number denoting the confidence level of the Wikipedia info will be returned." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Format description.
} | ||
} | ||
}, | ||
"x-servers" : [ { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should probably be removed.
Hi @HanLiMS if you want to release SDK for this new RP, you should update the readme files correspondingly. |
"name" : "modelVersion", | ||
"in" : "query", | ||
"description" : "(optional) This value indicates which model be used for scoring .", | ||
"required" : false, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
By default, OpenAPI keeps every parameter as optional. So, adding a required: false
on a query parameter is not a required.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please update the readme files correspondingly.
"readOnly" : true, | ||
"$ref" : "#/definitions/RequestStatistics" | ||
} | ||
}, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Invalid json (trailing comma)?
} | ||
], | ||
"x-ms-parameterized-host": { | ||
"hostTemplate": "{Endpoint}/text/analytics/v2.1-preview", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
v3.0-preview?
"info" : { | ||
"description" : "The Text Analytics API is a suite of text analytics web services built with best-in-class Microsoft machine learning algorithms. \nThe API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase and entity extraction as well as language detection. \nNo training data is needed to use this API; just bring your text data. \nThis API uses advanced natural language processing techniques to deliver best in class predictions.\n\nFurther documentation can be found in https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview\n\nThis API is currently available in:\n\n* Australia East - australiaeast.api.cognitive.microsoft.com\n* Brazil South - brazilsouth.api.cognitive.microsoft.com\n* Canada Central - canadacentral.api.cognitive.microsoft.com\n* Central India - centralindia.api.cognitive.microsoft.com\n* Central US - centralus.api.cognitive.microsoft.com\n* East Asia - eastasia.api.cognitive.microsoft.com\n* East US - eastus.api.cognitive.microsoft.com\n* East US 2 - eastus2.api.cognitive.microsoft.com\n* France Central - francecentral.api.cognitive.microsoft.com\n* Japan East - japaneast.api.cognitive.microsoft.com\n* Japan West - japanwest.api.cognitive.microsoft.com\n* Korea Central - koreacentral.api.cognitive.microsoft.com\n* North Central US - northcentralus.api.cognitive.microsoft.com\n* North Europe - northeurope.api.cognitive.microsoft.com\n* South Africa North - southafricanorth.api.cognitive.microsoft.com\n* South Central US - southcentralus.api.cognitive.microsoft.com\n* Southeast Asia - southeastasia.api.cognitive.microsoft.com\n* UK South - uksouth.api.cognitive.microsoft.com\n* West Central US - westcentralus.api.cognitive.microsoft.com\n* West Europe - westeurope.api.cognitive.microsoft.com\n* West US - westus.api.cognitive.microsoft.com\n* West US 2 - westus2.api.cognitive.microsoft.com", | ||
"version" : "V3.0-Preview.1", | ||
"title" : "Text Analytics API (V3.0-Preview.1)", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
autorest will use the title field to generate the name for the client - "Text Analytics Client"
"post" : { | ||
"summary" : "Entities from open domain", | ||
"description" : "The API returns a list of general named entities in a given document. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-entity-linking#supported-types-for-named-entity-recognition\">Supported Entity Types in Text Analytics API</a> for the list of supported Entity Types. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/text-analytics-supported-languages\">Supported languages in Text Analytics API</a> for the list of enabled languages.\n", | ||
"operationId" : "5ac4251d5b4ccd1554da7631", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Similarly here, autorest will use the operationID as the name of the method - "entities"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated to "/entities/recognition/general"? Does this look good as "operationId"?
Hi @raych1 could you please help us on identifying the errors in |
} | ||
} | ||
}, | ||
"example": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you remove this example part since it has x-ms-examples to cover already?
} | ||
}, | ||
"description": "Contains a set of input documents to be analyzed by the service.", | ||
"example": { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you remove this example part since it has x-ms-examples to cover already?
@HanLiMS , can you remove the example part in swagger since it's covered in x-ms-examples already? There's a bug in modelvalidation would check the non-required parameter for example within swagger file. cc: @ArcturusZhang |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@HanLiMS , can you remove the example part in swagger since it's covered in x-ms-examples already? There's a bug in modelvalidation would check the non-required parameter for example within swagger file. cc: @ArcturusZhang
Hi I updated according to your suggestion but still could not pass the validations. Any more suggestions?
Thanks!
...ication/cognitiveservices/data-plane/TextAnalytics/preview/v3.0-Preview.1/TextAnalytics.json
Outdated
Show resolved
Hide resolved
"parameters" : [ { | ||
"name" : "modelVersion", | ||
"in" : "query", | ||
"description" : "(optional) This value indicates which model be used for scoring .", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Versions will change overtime. Might worth to add a link for release annoucement related with model versions?
"format" : "int32", | ||
"description" : "The sentence length as given by StringInfo's LengthInTextElements property." | ||
}, | ||
"warnings" : { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Following the definitions in v3.0-preview for /sentiment:
https://cognitivewubvt.portal.azure-api.net/docs/services/TextAnalytics-v3-0-Preview/export?DocumentFormat=Swagger&ApiName=Text%20Analytics%20API%20(v3.0-Preview)
] | ||
}, | ||
"paths" : { | ||
"/entities/recognition" : { |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
/entities/recognition/general
{ | ||
"swagger" : "2.0", | ||
"info" : { | ||
"description" : "The Text Analytics API is a suite of text analytics web services built with best-in-class Microsoft machine learning algorithms. \nThe API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase and entity extraction as well as language detection. \nNo training data is needed to use this API; just bring your text data. \nThis API uses advanced natural language processing techniques to deliver best in class predictions.\n\nFurther documentation can be found in https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview\n\nThis API is currently available in:\n\n* Australia East - australiaeast.api.cognitive.microsoft.com\n* Brazil South - brazilsouth.api.cognitive.microsoft.com\n* Canada Central - canadacentral.api.cognitive.microsoft.com\n* Central India - centralindia.api.cognitive.microsoft.com\n* Central US - centralus.api.cognitive.microsoft.com\n* East Asia - eastasia.api.cognitive.microsoft.com\n* East US - eastus.api.cognitive.microsoft.com\n* East US 2 - eastus2.api.cognitive.microsoft.com\n* France Central - francecentral.api.cognitive.microsoft.com\n* Japan East - japaneast.api.cognitive.microsoft.com\n* Japan West - japanwest.api.cognitive.microsoft.com\n* Korea Central - koreacentral.api.cognitive.microsoft.com\n* North Central US - northcentralus.api.cognitive.microsoft.com\n* North Europe - northeurope.api.cognitive.microsoft.com\n* South Africa North - southafricanorth.api.cognitive.microsoft.com\n* South Central US - southcentralus.api.cognitive.microsoft.com\n* Southeast Asia - southeastasia.api.cognitive.microsoft.com\n* UK South - uksouth.api.cognitive.microsoft.com\n* West Central US - westcentralus.api.cognitive.microsoft.com\n* West Europe - westeurope.api.cognitive.microsoft.com\n* West US - westus.api.cognitive.microsoft.com\n* West US 2 - westus2.api.cognitive.microsoft.com", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Check with PMs for the description of everything.
} | ||
}, | ||
"InternalError": { | ||
"type": "object", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"required": true.
additional innererror/ details: optional.
"post" : { | ||
"summary" : "Entities from open domain", | ||
"description" : "The API returns a list of general named entities in a given document. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-entity-linking#supported-types-for-named-entity-recognition\">Supported Entity Types in Text Analytics API</a> for the list of supported Entity Types. See the <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/text-analytics-supported-languages\">Supported languages in Text Analytics API</a> for the list of enabled languages.\n", | ||
"operationId" : "5ac4251d5b4ccd1554da7631", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated to "/entities/recognition/general"? Does this look good as "operationId"?
"parameters" : [ { | ||
"name" : "modelVersion", | ||
"in" : "query", | ||
"description" : "(optional) This value indicates which model will be used for scoring. If a model-version is not specified, the API should default to the latest, non-preview version. ", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated to model-version. Which part of description need to be updated with camelCase?
...ication/cognitiveservices/data-plane/TextAnalytics/preview/v3.0-Preview.1/TextAnalytics.json
Outdated
Show resolved
Hide resolved
"type" : "array", | ||
"description" : "Errors by document id.", | ||
"items" : { | ||
"$ref" : "#/definitions/ErrorResponse" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right! Update in the ErrorResponse.
* add ta v3.0-preview.1 * resolve comments * fix spaces * update examples * resolve comments * update /healthcare and score * update Bioentity and entityrecord * temp * update api changes based on meeting discussions * update healthcare * update entity linking * update naming/description * update pii * update required * udpate required --> still need kv pair for details inside innererror * update summary and description * resolve comments -- update opreationid, model-version, errors, etc * update error * update error * remove optional in response, update uppercase of Optional in requests * update space * resolve comments * revole comments * remove /healthcare * update score range in description * update description * update aka.ms links * update pii description to use personal information * resolve comments -- updte detectedLnauges & operationId * update error enum * update /readme.md * update aka.ms links * update aka.ms links * update preview read me name & descrition * update all examples to /examples * update unkown word to custom-word.txt * git update folder case name * update input name to match with example json files * update 500 to default --> same as previous version .json files * update MultiLanguageBatchInput * update examples formatting * update formatting of .json * update x-ms-examples descriptions * test required false for model-version&showStats * update model-version and showStats * update formatting * add x-nullabletrue * update formmating * update pii example forammating * update formaating * update formatting * update textanalytics.json format * testing * update model-vesrion * detele required false * prettier --write * remove exmpales from TextAnalytics.json * test keyphrase * keyphrase * keyphrase retry * update keyphrase back * update ta.json split []
Latest improvements:
MSFT employees can try out our new experience at OpenAPI Hub - one location for using our validation tools and finding your workflow.
Contribution checklist:
ARM API Review Checklist
Failure to comply may result in delays for manifest application. Note this does not apply to data plane APIs.
Please follow the link to find more details on API review process.