Skip to content
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

Merged
merged 62 commits into from
Nov 20, 2019
Merged

Conversation

HanLiMS
Copy link
Contributor

@HanLiMS HanLiMS commented Sep 5, 2019

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:

  • I have reviewed the documentation for the workflow.
  • Validation tools were run on swagger spec(s) and have all been fixed in this PR.
  • The OpenAPI Hub was used for checking validation status and next steps.

ARM API Review Checklist

  • Service team MUST add the "WaitForARMFeedback" label if the management plane API changes fall into one of the below categories.
  • adding/removing APIs.
  • adding/removing properties.
  • adding/removing API-version.
  • adding a new service in Azure.

Failure to comply may result in delays for manifest application. Note this does not apply to data plane APIs.

  • If you are blocked on ARM review and want to get the PR merged urgently, please get the ARM oncall for reviews (RP Manifest Approvers team under Azure Resource Manager service) from IcM and reach out to them.
    Please follow the link to find more details on API review process.

@openapi-sdkautomation
Copy link

openapi-sdkautomation bot commented Sep 5, 2019

In Testing, Please Ignore

[Logs] (Generated from 875b9ef, Iteration 24)

Succeeded Python: test-repo-billy/azure-sdk-for-python [Logs] [Diff]
Warning Java: test-repo-billy/azure-sdk-for-java [Logs] [Diff]
  • No packages generated.
Warning Go: test-repo-billy/azure-sdk-for-go [Logs] [Diff]
Warning JavaScript: test-repo-billy/azure-sdk-for-js [Logs] [Diff]
  • Warning @azure/cognitiveservices-textanalytics [Logs]
Warning Ruby: test-repo-billy/azure-sdk-for-ruby [Logs] [Diff]
  • No packages generated.

@AutorestCI
Copy link

AutorestCI commented Sep 5, 2019

Automation for azure-sdk-for-python

A 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:
Azure/azure-sdk-for-python#8734

@HanLiMS HanLiMS changed the title add ta v3.0-preview.1 Add Text Analytics v3.0-preview.1 Sep 5, 2019
@HanLiMS HanLiMS changed the title Add Text Analytics v3.0-preview.1 Add Text Analytics V3.0-Preview.1 Sep 5, 2019
@AutorestCI
Copy link

AutorestCI commented Sep 5, 2019

Automation for azure-sdk-for-go

Nothing to generate for azure-sdk-for-go

@azuresdkci
Copy link
Contributor

Can one of the admins verify this patch?

},
"/entities/linking" : {
"post" : {
"summary" : "Well-known entities.",
Copy link

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

"parameters" : [ {
"name" : "modelVersion",
"in" : "query",
"description" : "(optional) This value indicates which model be used for scoring .",
Copy link

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

Copy link
Contributor Author

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?

Copy link
Contributor

@assafi assafi left a 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",
Copy link
Contributor

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",
Copy link
Contributor

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 .",
Copy link
Contributor

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",
Copy link
Contributor

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",
Copy link
Contributor

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."
Copy link
Contributor

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.

"$ref" : "#/definitions/MatchRecord"
}
},
"wikipediaLanguage" : {
Copy link
Contributor

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."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Format description.

}
}
},
"x-servers" : [ {
Copy link
Contributor

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.

@ArcturusZhang
Copy link
Member

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,
Copy link
Member

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.

Copy link
Member

@ArcturusZhang ArcturusZhang left a 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"
}
},
Copy link
Member

@johanste johanste Sep 11, 2019

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",
Copy link
Member

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)",
Copy link
Member

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",
Copy link
Member

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"

Copy link
Contributor Author

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"?

@ArcturusZhang
Copy link
Member

Hi @raych1 could you please help us on identifying the errors in ModelValidation?

}
}
},
"example": {
Copy link
Member

@raych1 raych1 Nov 18, 2019

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": {
Copy link
Member

@raych1 raych1 Nov 18, 2019

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?

@raych1
Copy link
Member

raych1 commented Nov 18, 2019

@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

Copy link
Contributor Author

@HanLiMS HanLiMS left a 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!

"parameters" : [ {
"name" : "modelVersion",
"in" : "query",
"description" : "(optional) This value indicates which model be used for scoring .",
Copy link
Contributor Author

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" : {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

]
},
"paths" : {
"/entities/recognition" : {
Copy link
Contributor Author

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",
Copy link
Contributor Author

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",
Copy link
Contributor Author

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",
Copy link
Contributor Author

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. ",
Copy link
Contributor Author

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?

"type" : "array",
"description" : "Errors by document id.",
"items" : {
"$ref" : "#/definitions/ErrorResponse"
Copy link
Contributor Author

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.

@johanste johanste added AzureAPIBoardSignedOff and removed APIStewardshipBoard-ReviewRequested This should be reviewed by the Azure API Stewardship team in partnership with the service team. labels Nov 19, 2019
@ArcturusZhang ArcturusZhang merged commit d1b0790 into Azure:master Nov 20, 2019
TalluriAnusha pushed a commit to AsrOneSdk/azure-rest-api-specs that referenced this pull request Dec 11, 2019
* 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 []
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

10 participants