diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ccfd3b1e62a1..7839310f6d33 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,63 +1,7 @@ -MSFT employees can try out our new experience at [OpenAPI Hub](https://aka.ms/openapiportal) - one location for using our validation tools and finding your workflow. - -Azure 1st Party Service can try out the [Shift Left](https://aka.ms/ShiftLeft) experience to initiate API design review from ADO code repo. If you are interested, may request engineering support by filling in with the form https://aka.ms/ShiftLeftSupportForm. +# Choose a PR Template -### Changelog -Add a changelog entry for this PR by answering the following questions: - 1. What's the purpose of the update? - - [ ] new service onboarding - - [ ] new API version - - [ ] update existing version for new feature - - [ ] update existing version to fix swagger quality issue in s360 - - [ ] Other, please clarify - 2. When are you targeting to deploy the new service/feature to public regions? Please provide the date or, if the date is not yet available, the month. - 3. When do you expect to publish the swagger? Please provide date or, the the date is not yet available, the month. - 4. If updating an existing version, please select the specific language SDKs and CLIs that must be refreshed after the swagger is published. - - [ ] SDK of .NET (need service team to ensure code readiness) - - [ ] SDK of Python - - [ ] SDK of Java - - [ ] SDK of Js - - [ ] SDK of Go - - [ ] PowerShell - - [ ] CLI - - [ ] Terraform - - [ ] No refresh required for updates in this PR +Switch to "Preview" on this description then select one of the choices below. -### Contribution checklist: -- [ ] I commit to follow the [Breaking Change Policy](http://aka.ms/bcforapi) of "no breaking changes" -- [ ] I have reviewed the [documentation](https://aka.ms/ameonboard) for the workflow. -- [ ] [Validation tools](https://aka.ms/swaggertools) were run on swagger spec(s) and errors have all been fixed in this PR. [How to fix?](https://aka.ms/ci-fix) +Click here to open a PR for a Data Plane API. -If any further question about AME onboarding or validation tools, please view the [FAQ](https://aka.ms/faqinprreview). - -### ARM API Review Checklist - -> **Applicability**: :warning: -> -> If your changes encompass only the following scenarios, you should SKIP this section, as these scenarios do not require ARM review. -> - Change to data plane APIs -> - Adding new properties -> - All removals - -Otherwise your PR may be subject to ARM review requirements. Complete the following: -- [ ] Check this box if any of the following appy to the PR so that the label "ARMReview" and "WaitForARMFeedback" will be added by bot to kick off ARM API Review. Missing to check this box in the following scenario may result in delays to the ARM manifest review and deployment. - - Adding a new service - - Adding new API(s) - - Adding a new API version - -[ ] To review changes efficiently, ensure you are using OpenAPIHub to initialize the PR for adding a new version. More details, refer to the [wiki](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/208/OpenAPI-Hub-Adding-new-API-version). - -- [ ] Ensure you've reviewed following [guidelines](https://aka.ms/rpguidelines) including [ARM resource provider contract](https://github.com/Azure/azure-resource-manager-rpc) and [REST guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md). Estimated time (4 hours). This is required before you can request review from ARM API Review board. - -- [ ] If you are blocked on ARM review and want to get the PR merged with urgency, please get the ARM oncall for reviews (*RP Manifest Approvers* team under Azure Resource Manager service) from IcM and reach out to them. - -### Breaking Change Review Checklist -If any of the following scenarios apply to the PR, request approval from the Breaking Change Review Board as defined in the [Breaking Change Policy](http://aka.ms/bcforapi). -- [ ] Removing API(s) in a stable version -- [ ] Removing properties in a stable version -- [ ] Removing API version(s) in a stable version -- [ ] Updating API in a stable or public preview version with Breaking Change Validation errors -- [ ] Updating API(s) in public preview over 1 year (refer to [Retirement of Previews](https://dev.azure.com/msazure/AzureWiki/_wiki/wikis/AzureWiki.wiki/37683/Retirement-of-Previews)) - -**Action**: to initiate an evaluation of the breaking change, create a new intake using the [template for breaking changes](https://aka.ms/Breakingchangetemplate). Addition details on the process and office hours are on the [Breaking change Wiki](https://dev.azure.com/msazure/AzureWiki/_wiki/wikis/AzureWiki.wiki/37684/Breaking-Changes). - -Please follow the link to find more details on [PR review process](https://aka.ms/SwaggerPRReview). +Click here to open a PR for a Control Plane (ARM) API. diff --git a/.github/comment.yml b/.github/comment.yml index 37b505ca33bd..7ffda2d3b904 100644 --- a/.github/comment.yml +++ b/.github/comment.yml @@ -3,7 +3,7 @@ type: checkbox keywords: - "WaitForARMFeedback" - booleanFilterExpression: "!(ARMSignedOff||ARMChangesRequested||Approved-OkToMerge||WaitForARMRevisit)" + booleanFilterExpression: "!(ARMSignedOff||ARMChangesRequested||Approved-OkToMerge||WaitForARMRevisit||BreakingChangeReviewRequired)" onCheckedLabels: - WaitForARMFeedback - ARMReview @@ -77,6 +77,13 @@ onLabeledComments: "Please ensure to respond feedbacks from the ARM API reviewer. When you are ready to continue the ARM API review, please remove `ARMChangesRequested`" onLabeledRemoveLabels: - WaitForARMFeedback + +- rule: + type: label + label: Approved-BreakingChange + booleanFilterExpression: "!(ARMSignedOff||ARMChangesRequested||Approved-OkToMerge||WaitForARMRevisit)&&ARMReview" + onLabeledAddLabels: + - WaitForARMFeedback - rule: diff --git a/.github/pull_request_assignment.yml b/.github/pull_request_assignment.yml index f5326c940a72..aaa0a50c408d 100644 --- a/.github/pull_request_assignment.yml +++ b/.github/pull_request_assignment.yml @@ -46,6 +46,7 @@ # data-plane PR paths: - "specification/**/data-plane/**" + - "dev/**/data-plane/**" reviewers: - anuchandy - jhendrixMSFT diff --git a/CODEOWNERS b/CODEOWNERS index e9d1951929cf..835a168bcaf1 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -5,6 +5,14 @@ # Specification ######### +######### +# Codeowner assignments are made from the _last_ matching entry in CODEOWNERS, so catch-all entries must come first +######### +/specification/*/data-plane/ @Azure/api-stewardship-board + +# PRLabel: %Schema Registry +/specification/schemaregistry/ @hmlam @nickghardwick @lmazuel @deyaaeldeen @JoshLove-msft @swathipil @conniey + # PRLabel: %Cognitive Services /dev/cognitiveservices/data-plane/Language/ @assafi @rokulka @ChongTang @annatisch @heaths @deyaaeldeen @kristapratico @mssfang @Azure/api-stewardship-board @@ -222,7 +230,7 @@ /specification/subscriptions/ @navysingla # PRLabel: %Synapses -/specification/synapse/ @idear1203 @wonner +/specification/synapse/ @wonner @yanjungao718 # PRLabel: %TimeseriesInsights /specification/timeseriesinsights/ @sandshadow @@ -241,4 +249,3 @@ /specification/**/resource-manager/**/readme.cli.md @jsntcy @qiaozha /specification/**/resource-manager/**/readme.go.md @ArcturusZhang /specification/**/resource-manager/**/readme.python.md @msyyc @BigCat20196 -/specification/*/data-plane/ @Azure/api-stewardship-board diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1243191899cc..4be9efc24c2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,18 +11,19 @@ This file provides general guidance for developers that are creating or updating -- [Reporting problems](#reporting-problems) +- [Reporting Problems](#reporting-problems) - [Avoid Breaking Changes](#avoid-breaking-changes) - [Design Guidelines](#design-guidelines) - * [Exceptions for consistency within a service](#exceptions-for-consistency-within-a-service) + * [Exceptions for Consistency within a Service](#exceptions-for-consistency-within-a-service) - [Coding Style](#coding-style) - [Directory Structure](#directory-structure) - [Pull Requests](#pull-requests) -- [Pull Request checks](#pull-request-checks) +- [Pull Request Checks](#pull-request-checks) +- [Internal Contribution Guide](#internal-contribution-guide) -## Reporting problems +## Reporting Problems If you discover a problem with a REST API document in this repo, feel free to [open an issue](https://github.com/Azure/azure-rest-api-specs/issues/new). But please do not report issues with service behavior / functionality in this repo. @@ -40,7 +41,7 @@ There is a [YouTube video series](https://www.youtube.com/watch?v=9Ng00IlBCtw) b Another resource is the [Considerations for Service Design](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md), which is an introduction to REST API design mainly for services that are just getting started. -### Exceptions for consistency within a service +### Exceptions for Consistency within a Service There are situations where a service has GA'd their API with design patterns that do not follow our guidelines and it would be a breaking change to adopt the API design in the guidelines. Because the first rule is to avoid breaking changes and because we want APIs to be consistent within a service, these design patterns are considered the standard for that service and should be followed in all subsequent (non-breaking) versions of that service's REST API. @@ -70,7 +71,7 @@ If you want to contribute to the repository, follow these steps: Microsoft employees can try out the experience at [OpenAPI Hub](https://aka.ms/openapihub) for [adding a new API version using OpenAPI Hub](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/208/OpenAPI-Hub-Adding-new-API-version). -## Pull Request checks +## Pull Request Checks Every PR in this repo will go through a series of PR checks, including: @@ -90,3 +91,10 @@ Every PR in this repo will go through a series of PR checks, including: When any of these PR checks fails it will post a comment to the PR with links to information on how to resolve the problem. There is also the [CI Fix Guide](https://aka.ms/ci-fix) that describes how to fix common PR check failures. + +## Internal Contribution Guide +For management plane, please refer to https://aka.ms/rpguidelines; + +For data-plane, please refer to [Guide to design and creation of Data Plane REST API and Client Libraries](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/591/Guide-to-design-and-creation-of-Data-Plane-REST-API-and-Client-Libraries); + +For contribution access to spec repos, please refer to [Public repo vs. Private repo: To get write access](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/202/Overall-Process-of-Management-Plane-SDK-Onboarding?anchor=2.-create/update-the-openapi-specifications%2C-and-launch-swagger-pr-review) diff --git a/README.md b/README.md index 8f248602db08..e03a87ea8d4b 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ External Contributors can read [Getting Started with OpenAPI Specifications](htt - **Offerings**, **Skus**, and **Features** - These are distinct entities represented in Eco Manager and Service Tree. While the Offering/Sku/Feature entities and hierarchy represent the externally marketed product, **service/components** entities in service tree represent corresponding engineering entities that together power these external products. Refer to [Product Taxonomy](https://dev.azure.com/msazure/AzureWiki/_wiki/wikis/AzureWiki.wiki/40783/Service-Tree-Product-Taxonomy) for details. -- **Resource Provider** - When a service onboard new functionality onto ARM, it is required to complete [Resource Provider Registration](https://armwiki.azurewebsites.net/rp_onboarding/ResourceProviderRegistration.html). For existing **Resource Provider to Service Mapping**, refer to [Match resource provider to service](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service)* +- **Resource Provider** - When a service onboards new functionality onto ARM, it is required to complete [Resource Provider Registration](https://armwiki.azurewebsites.net/rp_onboarding/ResourceProviderRegistration.html). For existing **Resource Provider to Service Mapping**, refer to [Match resource provider to service](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service)* ## Directory Structure @@ -34,13 +34,13 @@ The structure of the directory should strictly follow these rules: > > - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities? > - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future? - > - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that need to be referred cross RP folders should to be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). + > - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). > - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). -4. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else) . There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present. +4. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present. -5. **'cadl' Folders**: this folder holds CADL specs of either `resource-manager` or `data-plane`. CADL is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the CADL repo: [CADL tutorial](http://aka.ms/cadlTutorial). You can also ask questions for provide feedback in the teams channel [CADL Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47). +5. **'cadl' Folders**: this folder holds CADL specs of either `resource-manager` or `data-plane`. CADL is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the CADL repo: [CADL tutorial](http://aka.ms/cadlTutorial). You can also ask questions for providing feedback in the teams channel [CADL Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47). 6. **'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting). @@ -56,7 +56,7 @@ The structure of the directory should strictly follow these rules: 9. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples. -> Note: some general guidance for folder names, file names under `specification`: +> Note: some general guidance for folder names, and file names under `specification`: > > - Folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers. > - Generic folder names should be lower-case @@ -110,7 +110,7 @@ The structure should appear like so: | \---readme.md ``` ### Folder Structure for Service Group -If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboaration, especially supporting: +If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboration, especially supporting: - To collect API definition of multiple components/services with different versioning cycle in one rp folder - To share some common entity types among services or components under the same rp folder. @@ -174,7 +174,7 @@ Specification files and AutoRest configuration files in one RP folder are better ## Next steps -The next step in the process after a spec is completed is to generate SDKs and API reference documentation. If you're Microsoft employee, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk) for more information. +The next step in the process after a spec is completed is to generate SDKs and API reference documentation. If you're a Microsoft employee, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk) for more information. External Contributors can read [Getting Started with OpenAPI Specifications](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md). diff --git a/custom-words.txt b/custom-words.txt index 9354919f94f6..30b689d31488 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -23,6 +23,7 @@ ACLs aclspec acquisitionid acrapi +ACSS ACSSMS actionplans activedirectory @@ -47,6 +48,7 @@ adultscore afd afdx affinitized +AFRI AFRINIC agentpool aggregatedcost @@ -176,6 +178,7 @@ authprovider authproviders Auths authsettings +authtoken authsid autobackup Autocompletes @@ -415,6 +418,7 @@ Coffeelake cognitiveservices colls colocation +Cololocation COLUMNSTORE commandshistory commitmentplans @@ -597,9 +601,12 @@ deserializer deserializing destaging destinationshares +detectorproperties deterministically devcenter devcenters +devbox +devboxes devboxdefinitions deviceclass deviceclasses @@ -727,6 +734,7 @@ Eventhub eventhubconnections eventhubs eventroutes +eventstream eventtime eventtypes EWDG @@ -1064,6 +1072,8 @@ johnsmith JSONLD Jtoken jumpbox +jwks +jwks_uri jwts K’iche Kabuverdianu @@ -1129,6 +1139,7 @@ largefacelists largepersongroups lastfile lastmodified +LATAM Latn l'avion LDAP @@ -1149,6 +1160,7 @@ Liftr Linestring linkedservices linkexpiryinminutes +linkworkspaces LISTAFTERID listbackups listbyrg @@ -1456,6 +1468,7 @@ numa numofmessages numrecords nvarchar +NVME Nynorsk nysiis OAEP @@ -2125,6 +2138,7 @@ swedensouth switchprotection switzerlandnorth switzerlandwest +synapselink Sybase Syncer syncfunctiontriggers @@ -2360,6 +2374,8 @@ virtualmachine virtualmachineimagebuilder virtualmachines virtualnetworkgateways +virtualnetworkgatewaypolicygroups +vngclientconnectionconfigurations virtualnetworkrules virtualnetworks Virtustream @@ -2469,6 +2485,7 @@ workbooktemplates Workernode workitemsource workloadmonitor +workspace workspaces workspace's wrapkey @@ -2656,6 +2673,8 @@ verifyx removex generateverificationcodex favorited +datawarehousequeries +Dataware SIMIDs ICCID unversioned @@ -2708,5 +2727,38 @@ Skolt Thangmi Tuvan Uyghur +occured +Occured Paramter -Spza \ No newline at end of file +Spza +metallb +kubevirt +vmip +xlargerc +largerc +mediumrc +smallrc +Autotune +Showmount +autogrid +remediatable +KubeProxyConfig +IPVS +TCPFIN +taginheritance +questionanswers +Satya +Nadella +Telangana +servicehealth +metricstaticthreshold +metricsdynamicthreshold +logalert +logalertv2 +smartalert +webtestalert +logalertv1numresult +logalertv1metricmeasurement +resourcehealth +activitylog +budget diff --git a/dev/cognitiveservices/data-plane/Language/analyzeconversations-authoring.json b/dev/cognitiveservices/data-plane/Language/analyzeconversations-authoring.json index 56c0c55d36d4..ceaa21cb692c 100644 --- a/dev/cognitiveservices/data-plane/Language/analyzeconversations-authoring.json +++ b/dev/cognitiveservices/data-plane/Language/analyzeconversations-authoring.json @@ -2,18 +2,31 @@ "swagger": "2.0", "info": { "title": "Microsoft Cognitive Language Service - Analyze Conversations Authoring", - "version": "2022-07-01-preview", + "version": "2022-10-01-preview", "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 https://docs.microsoft.com/en-us/azure/cognitive-services/language-service/overview." }, "securityDefinitions": { + "AADToken": { + "type": "oauth2", + "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", + "flow": "implicit", + "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts.", + "scopes": { + "https://cognitiveservices.azure.com/.default": "https://cognitiveservices.azure.com/.default" + } + }, "apim_key": { "type": "apiKey", - "description": "A subscription key for a Language service resource.", "name": "Ocp-Apim-Subscription-Key", "in": "header" } }, "security": [ + { + "AADToken": [ + "https://cognitiveservices.azure.com/.default" + ] + }, { "apim_key": [] } diff --git a/dev/cognitiveservices/data-plane/Language/analyzeconversations.json b/dev/cognitiveservices/data-plane/Language/analyzeconversations.json index 62a5fd187b55..af1831a8a98d 100644 --- a/dev/cognitiveservices/data-plane/Language/analyzeconversations.json +++ b/dev/cognitiveservices/data-plane/Language/analyzeconversations.json @@ -6,14 +6,27 @@ "version": "2022-10-01-preview" }, "securityDefinitions": { + "AADToken": { + "type": "oauth2", + "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", + "flow": "implicit", + "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts.", + "scopes": { + "https://cognitiveservices.azure.com/.default": "https://cognitiveservices.azure.com/.default" + } + }, "apim_key": { "type": "apiKey", - "description": "A subscription key for a Language service resource.", "name": "Ocp-Apim-Subscription-Key", "in": "header" } }, "security": [ + { + "AADToken": [ + "https://cognitiveservices.azure.com/.default" + ] + }, { "apim_key": [] } @@ -135,6 +148,9 @@ }, "Successful Conversation Summarization Task Submit": { "$ref": "./examples/conversations/SuccessfulConversationSummarizationTaskSubmit.json" + }, + "Successful Conversation Sentiment Analysis Job Request": { + "$ref": "./examples/conversations/SuccessfulConversationSentimentSubmit.json" } }, "x-ms-long-running-operation": true @@ -180,6 +196,9 @@ "Successful Get Text Conversation Analysis Job Status Request": { "$ref": "./examples/conversations/SuccessfulConversationSummarizationTaskStatusRequest.json" }, + "Successful Get Conversation Sentiment Analysis Job Status Request": { + "$ref": "./examples/conversations/SuccessfulConversationSentimentTaskStatusRequest.json" + }, "Successful Get Conversation Summarization Result": { "$ref": "./examples/conversations/SuccessfulConversationSummarizationTaskResult.json" } @@ -251,6 +270,7 @@ } }, "AnalyzeConversationTask": { + "type": "object", "description": "The base class of a conversation input task.", "discriminator": "kind", "required": [ @@ -263,6 +283,7 @@ } }, "AnalyzeConversationTaskResult": { + "type": "object", "description": "The base class of a conversation task result.", "discriminator": "kind", "required": [ @@ -275,6 +296,7 @@ } }, "ConversationalTask": { + "type": "object", "description": "The input for a custom conversation task.", "allOf": [ { @@ -393,6 +415,7 @@ "additionalProperties": true }, "TextConversationItem": { + "type": "object", "description": "The text modality of an input conversation.", "allOf": [ { @@ -804,7 +827,7 @@ "description": "The collection of entity resolution objects.", "type": "array", "items": { - "$ref": "#/definitions/BaseResolution" + "$ref": "common.json#/definitions/BaseResolution" } }, "extraInformation": { @@ -826,7 +849,8 @@ "type": "string", "enum": [ "EntitySubtype", - "ListKey" + "ListKey", + "RegexKey" ], "x-ms-enum": { "name": "ExtraInformationKind", @@ -870,660 +894,26 @@ } } }, - "BaseResolution": { - "description": "The abstract base class for entity resolutions.", - "type": "object", - "discriminator": "resolutionKind", - "properties": { - "resolutionKind": { - "description": "The entity resolution object kind.", - "type": "string", - "enum": [ - "BooleanResolution", - "DateTimeResolution", - "NumberResolution", - "OrdinalResolution", - "SpeedResolution", - "WeightResolution", - "LengthResolution", - "VolumeResolution", - "AreaResolution", - "AgeResolution", - "InformationResolution", - "TemperatureResolution", - "CurrencyResolution", - "NumericRangeResolution", - "TemporalSpanResolution" - ], - "x-ms-enum": { - "name": "ResolutionKind", - "modelAsString": true - } - } - }, - "required": [ - "resolutionKind" - ] - }, - "QuantityResolution": { - "description": "Represents resolutions for quantities.", - "type": "object", - "properties": { - "value": { - "type": "number", - "format": "double", - "description": "The numeric value that the extracted text denotes." - } - }, - "required": [ - "value" - ] - }, - "AgeResolution": { - "description": "Represents the Age entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "AgeResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "Year", - "Month", - "Week", - "Day" - ], - "x-ms-enum": { - "name": "AgeUnit", - "modelAsString": true - }, - "description": "The Age Unit of measurement" - } - }, - "required": [ - "unit" - ] - }, - "VolumeResolution": { - "description": "Represents the volume entity resolution model.", + "RegexKey": { + "description": "The regex key extra data kind.", "allOf": [ { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "VolumeResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "CubicMeter", - "CubicCentimeter", - "CubicMillimeter", - "Hectoliter", - "Decaliter", - "Liter", - "Centiliter", - "Milliliter", - "CubicYard", - "CubicInch", - "CubicFoot", - "CubicMile", - "FluidOunce", - "Teaspoon", - "Tablespoon", - "Pint", - "Quart", - "Cup", - "Gill", - "Pinch", - "FluidDram", - "Barrel", - "Minim", - "Cord", - "Peck", - "Bushel", - "Hogshead" - ], - "x-ms-enum": { - "name": "VolumeUnit", - "modelAsString": true - }, - "description": "The Volume Unit of measurement" - } - }, - "required": [ - "unit" - ] - }, - "SpeedResolution": { - "description": "Represents the speed entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "SpeedResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "MetersPerSecond", - "KilometersPerHour", - "KilometersPerMinute", - "KilometersPerSecond", - "MilesPerHour", - "Knot", - "FootPerSecond", - "FootPerMinute", - "YardsPerMinute", - "YardsPerSecond", - "MetersPerMillisecond", - "CentimetersPerMillisecond", - "KilometersPerMillisecond" - ], - "x-ms-enum": { - "name": "SpeedUnit", - "modelAsString": true - }, - "description": "The speed Unit of measurement" - } - }, - "required": [ - "unit" - ] - }, - "AreaResolution": { - "description": "Represents the area entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "AreaResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "SquareKilometer", - "SquareHectometer", - "SquareDecameter", - "SquareDecimeter", - "SquareMeter", - "SquareCentimeter", - "SquareMillimeter", - "SquareInch", - "SquareFoot", - "SquareMile", - "SquareYard", - "Acre" - ], - "x-ms-enum": { - "name": "AreaUnit", - "modelAsString": true - }, - "description": "The area Unit of measurement" - } - }, - "required": [ - "unit" - ] - }, - "LengthResolution": { - "description": "Represents the length entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "LengthResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "Kilometer", - "Hectometer", - "Decameter", - "Meter", - "Decimeter", - "Centimeter", - "Millimeter", - "Micrometer", - "Nanometer", - "Picometer", - "Mile", - "Yard", - "Inch", - "Foot", - "LightYear", - "Pt" - ], - "x-ms-enum": { - "name": "LengthUnit", - "modelAsString": true - }, - "description": "The length Unit of measurement" - } - }, - "required": [ - "unit" - ] - }, - "InformationResolution": { - "description": "Represents the information (data) entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "InformationResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "Bit", - "Kilobit", - "Megabit", - "Gigabit", - "Terabit", - "Petabit", - "Byte", - "Kilobyte", - "Megabyte", - "Gigabyte", - "Terabyte", - "Petabyte" - ], - "x-ms-enum": { - "name": "InformationUnit", - "modelAsString": true - }, - "description": "The information (data) Unit of measurement." - } - }, - "required": [ - "unit" - ] - }, - "TemperatureResolution": { - "description": "Represents the temperature entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "TemperatureResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "Fahrenheit", - "Kelvin", - "Rankine", - "Celsius" - ], - "x-ms-enum": { - "name": "TemperatureUnit", - "modelAsString": true - }, - "description": "The temperature Unit of measurement." - } - }, - "required": [ - "unit" - ] - }, - "WeightResolution": { - "description": "Represents the weight entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "WeightResolution", - "properties": { - "unit": { - "type": "string", - "enum": [ - "Unspecified", - "Kilogram", - "Gram", - "Milligram", - "Gallon", - "MetricTon", - "Ton", - "Pound", - "Ounce", - "Grain", - "PennyWeight", - "LongTonBritish", - "ShortTonUS", - "ShortHundredWeightUS", - "Stone", - "Dram" - ], - "x-ms-enum": { - "name": "WeightUnit", - "modelAsString": true - }, - "description": "The weight Unit of measurement." - } - }, - "required": [ - "unit" - ] - }, - "CurrencyResolution": { - "description": "Represents the currency entity resolution model.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - }, - { - "$ref": "#/definitions/QuantityResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "CurrencyResolution", - "properties": { - "ISO4217": { - "type": "string", - "description": "The alphabetic code based on another ISO standard, ISO 3166, which lists the codes for country names. The first two letters of the ISO 4217 three-letter code are the same as the code for the country name, and, where possible, the third letter corresponds to the first letter of the currency name." - }, - "value": { - "type": "number", - "format": "double", - "description": "The money amount captured in the extracted entity" - }, - "unit": { - "type": "string", - "description": "The unit of the amount captured in the extracted entity" - } - }, - "required": [ - "value", - "unit" - ] - }, - "BooleanResolution": { - "description": "A resolution for boolean expressions", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "BooleanResolution", - "properties": { - "value": { - "type": "boolean" - } - }, - "required": [ - "value" - ] - }, - "DateTimeResolution": { - "description": "A resolution for datetime entity instances.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "DateTimeResolution", - "properties": { - "timex": { - "$ref": "#/definitions/TimeExpression" - }, - "dateTimeSubKind": { - "type": "string", - "enum": [ - "Time", - "Date", - "DateTime", - "Duration", - "Set" - ], - "x-ms-enum": { - "name": "DateTimeSubKind", - "modelAsString": true - }, - "description": "The DateTime SubKind" - }, - "value": { - "type": "string", - "description": "The actual time that the extracted text denote." - }, - "modifier": { - "$ref": "#/definitions/TemporalModifier" - } - }, - "required": [ - "timex", - "dateTimeSubKind", - "value" - ] - }, - "NumberResolution": { - "description": "A resolution for numeric entity instances.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "NumberResolution", - "properties": { - "numberKind": { - "type": "string", - "enum": [ - "Integer", - "Decimal", - "Power", - "Fraction", - "Percent", - "Unspecified" - ], - "x-ms-enum": { - "name": "NumberKind", - "modelAsString": true - }, - "description": "The type of the extracted number entity." - }, - "value": { - "type": "string", - "description": "A numeric representation of what the extracted text denotes." - } - }, - "required": [ - "numberKind", - "value" - ] - }, - "OrdinalResolution": { - "description": "A resolution for ordinal numbers entity instances.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "OrdinalResolution", - "properties": { - "offset": { - "type": "string", - "description": "The offset With respect to the reference (e.g., offset = -1 in \"show me the second to last\"" - }, - "relativeTo": { - "type": "string", - "enum": [ - "Current", - "End", - "Start" - ], - "x-ms-enum": { - "name": "RelativeTo", - "modelAsString": true - }, - "description": "The reference point that the ordinal number denotes." - }, - "value": { - "type": "string", - "description": "A simple arithmetic expression that the ordinal denotes." - } - }, - "required": [ - "offset", - "relativeTo", - "value" - ] - }, - "TemporalSpanResolution": { - "description": "represents the resolution of a date and/or time span.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" + "$ref": "#/definitions/BaseExtraInformation" } ], "type": "object", - "x-ms-discriminator-value": "TemporalSpanResolution", + "x-ms-discriminator-value": "RegexKey", "properties": { - "begin": { - "$ref": "#/definitions/TimeExpression" - }, - "end": { - "$ref": "#/definitions/TimeExpression" - }, - "duration": { + "key": { "type": "string", - "description": "An optional duration value formatted based on the ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601#Durations)" + "description": "The key of the regex pattern used in extracting the entity." }, - "modifier": { - "$ref": "#/definitions/TemporalModifier" - } - } - }, - "NumericRangeResolution": { - "description": "represents the resolution of numeric intervals.", - "allOf": [ - { - "$ref": "#/definitions/BaseResolution" - } - ], - "type": "object", - "x-ms-discriminator-value": "NumericRangeResolution", - "properties": { - "rangeKind": { + "regexPattern": { "type": "string", - "enum": [ - "Number", - "Speed", - "Weight", - "Length", - "Volume", - "Area", - "Age", - "Information", - "Temperature", - "Currency" - ], - "x-ms-enum": { - "name": "RangeKind", - "modelAsString": true - }, - "description": "The kind of range that the resolution object represents." - }, - "minimum": { - "type": "number", - "format": "double", - "description": "The beginning value of the interval." - }, - "maximum": { - "type": "number", - "format": "double", - "description": "The ending value of the interval." + "description": "The .NET regex pattern used in extracting the entity. Please visit https://docs.microsoft.com/dotnet/standard/base-types/regular-expressions for more information about .NET regular expressions." } - }, - "required": [ - "rangeKind", - "minimum", - "maximum" - ] - }, - "TemporalModifier": { - "type": "string", - "description": "An optional modifier of a date/time instance.", - "enum": [ - "AfterApprox", - "Before", - "BeforeStart", - "Approx", - "ReferenceUndefined", - "SinceEnd", - "AfterMid", - "Start", - "After", - "BeforeEnd", - "Until", - "End", - "Less", - "Since", - "AfterStart", - "BeforeApprox", - "Mid", - "More" - ], - "x-ms-enum": { - "name": "TemporalModifier", - "modelAsString": true } }, - "TimeExpression": { - "type": "string", - "description": "An extended ISO 8601 date/time representation as described in (https://github.com/Microsoft/Recognizers-Text/blob/master/Patterns/English/English-DateTime.yaml)" - }, "LuisTargetIntentResult": { "type": "object", "description": "It is a wrap up of LUIS Generally Available response.", @@ -1557,6 +947,7 @@ } }, "AnalyzeConversationJobsInput": { + "type": "object", "properties": { "displayName": { "description": "Optional display name for the analysis job.", @@ -1579,6 +970,7 @@ ] }, "AnalyzeConversationLROTask": { + "type": "object", "description": "The base class for an long running conversation input task.", "discriminator": "kind", "required": [ @@ -1597,10 +989,11 @@ }, "AnalyzeConversationLROTaskKind": { "type": "string", - "description": "Enumeration of supported analysis tasks on a collection of conversations.", + "description": "Enumeration of supported analysis tasks on a collection of conversation.", "enum": [ "ConversationalPIITask", - "ConversationalSummarizationTask" + "ConversationalSummarizationTask", + "ConversationalSentimentTask" ], "x-ms-enum": { "name": "AnalyzeConversationLROTaskKind", @@ -1612,7 +1005,8 @@ "description": "Enumeration of supported Conversation Analysis task results.", "enum": [ "ConversationalPIIResults", - "ConversationalSummarizationResults" + "ConversationalSummarizationResults", + "ConversationalSentimentResults" ], "x-ms-enum": { "name": "AnalyzeConversationResultsKind", @@ -1658,6 +1052,7 @@ } }, "MultiLanguageConversationAnalysisInput": { + "type": "object", "required": [ "conversations" ], @@ -1722,6 +1117,7 @@ } }, "TextConversation": { + "type": "object", "x-ms-discriminator-value": "text", "required": [ "conversationItems" @@ -1742,6 +1138,7 @@ } }, "TranscriptConversation": { + "type": "object", "x-ms-discriminator-value": "transcript", "required": [ "conversationItems" @@ -1950,6 +1347,7 @@ ] }, "ConversationPIIResult": { + "type": "object", "description": "The result from PII detection and redaction operation for each conversation.", "required": [ "conversationItems" @@ -2176,6 +1574,124 @@ "text" ] }, + "AnalyzeConversationalSentimentTask": { + "type": "object", + "description": "Task definition for a sentiment analysis in conversations.", + "properties": { + "parameters": { + "$ref": "#/definitions/ConversationalSentimentTaskParameters" + } + }, + "allOf": [ + { + "$ref": "#/definitions/AnalyzeConversationLROTask" + } + ], + "x-ms-discriminator-value": "ConversationalSentimentTask" + }, + "ConversationalSentimentTaskParameters": { + "type": "object", + "description": "Supported parameters for a Conversational sentiment analysis task.", + "properties": { + "predictionSource": { + "type": "string", + "description": "For transcript conversations, this parameter provides information regarding which content type should be used for sentiment analysis. The details of the sentiment analysis - like the offset, length and the text itself - will correspond to the text type selected here.", + "$ref": "#/definitions/TranscriptContentType" + } + }, + "allOf": [ + { + "$ref": "common.json#/definitions/PreBuiltTaskParameters" + } + ] + }, + "AnalyzeConversationSentimentResult": { + "type": "object", + "description": "Result from the sentiment analysis operation performed on a list of conversations.", + "allOf": [ + { + "$ref": "#/definitions/AnalyzeConversationJobResult" + } + ], + "properties": { + "results": { + "$ref": "#/definitions/ConversationSentimentResults" + } + }, + "required": [ + "results" + ], + "x-ms-discriminator-value": "ConversationalSentimentResults" + }, + "ConversationSentimentResults": { + "type": "object", + "description": "The result from sentiment analysis operation for each conversation.", + "required": [ + "conversations" + ], + "properties": { + "conversations": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/definitions/ConversationSentimentResult" + }, + { + "$ref": "#/definitions/ConversationResultBase" + } + ] + } + } + }, + "allOf": [ + { + "$ref": "common.json#/definitions/PreBuiltResult" + } + ] + }, + "ConversationSentimentResult": { + "type": "object", + "description": "The result from sentiment analysis operation for each conversation item.", + "required": [ + "conversationItems" + ], + "properties": { + "conversationItems": { + "description": "Enumeration of Sentiment operation results for all the conversation items in a conversation.", + "type": "array", + "items": { + "$ref": "#/definitions/ConversationSentimentItemResult" + } + } + } + }, + "ConversationSentimentItemResult": { + "type": "object", + "required": [ + "id", + "participantId", + "sentiment", + "confidenceScores" + ], + "properties": { + "id": { + "description": "The identifier for the conversation item", + "type": "string" + }, + "participantId": { + "description": "The identifier for the speaker", + "type": "string" + }, + "sentiment": { + "$ref": "common.json#/definitions/Sentiment" + }, + "confidenceScores": { + "type": "object", + "$ref": "common.json#/definitions/SentimentConfidenceScores" + } + } + }, "AnalyzeConversationJobState": { "description": "Contains the status of the analyze conversations job submitted along with related statistics.", "allOf": [ @@ -2206,19 +1722,23 @@ "properties": { "completed": { "description": "Count of tasks completed successfully.", - "type": "integer" + "type": "integer", + "format": "int32" }, "failed": { "description": "Count of tasks that failed.", - "type": "integer" + "type": "integer", + "format": "int32" }, "inProgress": { "description": "Count of tasks in progress currently.", - "type": "integer" + "type": "integer", + "format": "int32" }, "total": { "description": "Total count of tasks submitted as part of the job.", - "type": "integer" + "type": "integer", + "format": "int32" }, "items": { "description": "List of results from tasks (if available).", diff --git a/dev/cognitiveservices/data-plane/Language/analyzetext-authoring.json b/dev/cognitiveservices/data-plane/Language/analyzetext-authoring.json index 23cb97ef516f..265c4682b982 100644 --- a/dev/cognitiveservices/data-plane/Language/analyzetext-authoring.json +++ b/dev/cognitiveservices/data-plane/Language/analyzetext-authoring.json @@ -2,18 +2,31 @@ "swagger": "2.0", "info": { "title": "Microsoft Cognitive Language Service - Analyze Text Authoring", - "version": "2022-07-01-preview", + "version": "2022-10-01-preview", "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 https://docs.microsoft.com/en-us/azure/cognitive-services/language-service/overview." }, "securityDefinitions": { + "AADToken": { + "type": "oauth2", + "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", + "flow": "implicit", + "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts.", + "scopes": { + "https://cognitiveservices.azure.com/.default": "https://cognitiveservices.azure.com/.default" + } + }, "apim_key": { "type": "apiKey", - "description": "A subscription key for a Language service resource.", "name": "Ocp-Apim-Subscription-Key", "in": "header" } }, "security": [ + { + "AADToken": [ + "https://cognitiveservices.azure.com/.default" + ] + }, { "apim_key": [] } diff --git a/dev/cognitiveservices/data-plane/Language/analyzetext.json b/dev/cognitiveservices/data-plane/Language/analyzetext.json index f6bc4ba24384..59d43bfb11d3 100644 --- a/dev/cognitiveservices/data-plane/Language/analyzetext.json +++ b/dev/cognitiveservices/data-plane/Language/analyzetext.json @@ -2,18 +2,31 @@ "swagger": "2.0", "info": { "title": "Microsoft Cognitive Language Service - Text Analysis", - "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 https://docs.microsoft.com/en-us/azure/cognitive-services/language-service/overview.0", + "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 https://docs.microsoft.com/azure/cognitive-services/language-service/overview.0", "version": "2022-10-01-preview" }, "securityDefinitions": { + "AADToken": { + "type": "oauth2", + "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", + "flow": "implicit", + "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts.", + "scopes": { + "https://cognitiveservices.azure.com/.default": "https://cognitiveservices.azure.com/.default" + } + }, "apim_key": { "type": "apiKey", - "description": "A subscription key for a Language service resource.", "name": "Ocp-Apim-Subscription-Key", "in": "header" } }, "security": [ + { + "AADToken": [ + "https://cognitiveservices.azure.com/.default" + ] + }, { "apim_key": [] } @@ -88,6 +101,9 @@ }, "Successful Sentiment Analysis Request": { "$ref": "./examples/text/SuccessfulSentimentAnalysisRequest.json" + }, + "Successful Dynamic Classification Request": { + "$ref": "./examples/text/SuccessfuDynamicClassificationRequest.json" } } } @@ -142,6 +158,9 @@ }, "Successful Submit Abstractive Summarization Task": { "$ref": "./examples/text/SuccessfulAbstractiveSummarizationTaskSubmit.json" + }, + "Successful Healthcare DocumentType Post Request": { + "$ref": "./examples/text/SuccessfulHealthcareDocumentTypePostRequest.json" } }, "x-ms-long-running-operation": true @@ -195,6 +214,9 @@ }, "Successful Get Abstractive Summarization Result": { "$ref": "./examples/text/SuccessfulAbstractiveSummarizationTaskResult.json" + }, + "Successful Get Text Analysis Health DocumentType Request": { + "$ref": "./examples/text/SuccessfulHealthcareDocumentTypeTaskStatusRequest.json" } } } @@ -250,7 +272,8 @@ "PiiEntityRecognition", "KeyPhraseExtraction", "LanguageDetection", - "EntityLinking" + "EntityLinking", + "DynamicClassification" ], "x-ms-enum": { "name": "AnalyzeTextTaskKind", @@ -287,7 +310,8 @@ "PiiEntityRecognitionResults", "KeyPhraseExtractionResults", "LanguageDetectionResults", - "EntityLinkingResults" + "EntityLinkingResults", + "DynamicClassificationResults" ], "x-ms-enum": { "name": "AnalyzeTextTaskResultsKind", @@ -316,6 +340,7 @@ } }, "MultiLanguageAnalysisInput": { + "type": "object", "properties": { "documents": { "type": "array", @@ -326,6 +351,7 @@ } }, "LanguageDetectionAnalysisInput": { + "type": "object", "properties": { "documents": { "type": "array", @@ -336,6 +362,7 @@ } }, "AnalyzeTextTask": { + "type": "object", "discriminator": "kind", "required": [ "kind" @@ -347,6 +374,7 @@ } }, "AnalyzeTextLROTask": { + "type": "object", "discriminator": "kind", "required": [ "kind" @@ -363,6 +391,7 @@ ] }, "AnalyzeTextTaskResult": { + "type": "object", "discriminator": "kind", "required": [ "kind" @@ -374,6 +403,7 @@ } }, "AnalyzeTextEntityLinkingInput": { + "type": "object", "properties": { "analysisInput": { "$ref": "#/definitions/MultiLanguageAnalysisInput" @@ -390,6 +420,7 @@ "x-ms-discriminator-value": "EntityLinking" }, "AnalyzeTextEntityRecognitionInput": { + "type": "object", "properties": { "analysisInput": { "$ref": "#/definitions/MultiLanguageAnalysisInput" @@ -406,6 +437,7 @@ "x-ms-discriminator-value": "EntityRecognition" }, "AnalyzeTextKeyPhraseExtractionInput": { + "type": "object", "properties": { "analysisInput": { "$ref": "#/definitions/MultiLanguageAnalysisInput" @@ -422,6 +454,7 @@ "x-ms-discriminator-value": "KeyPhraseExtraction" }, "AnalyzeTextPiiEntitiesRecognitionInput": { + "type": "object", "properties": { "analysisInput": { "$ref": "#/definitions/MultiLanguageAnalysisInput" @@ -438,6 +471,7 @@ "x-ms-discriminator-value": "PiiEntityRecognition" }, "AnalyzeTextLanguageDetectionInput": { + "type": "object", "properties": { "analysisInput": { "$ref": "#/definitions/LanguageDetectionAnalysisInput" @@ -454,6 +488,7 @@ "x-ms-discriminator-value": "LanguageDetection" }, "AnalyzeTextSentimentAnalysisInput": { + "type": "object", "properties": { "analysisInput": { "$ref": "#/definitions/MultiLanguageAnalysisInput" @@ -469,7 +504,25 @@ ], "x-ms-discriminator-value": "SentimentAnalysis" }, + "AnalyzeTextDynamicClassificationInput": { + "type": "object", + "properties": { + "analysisInput": { + "$ref": "#/definitions/MultiLanguageAnalysisInput" + }, + "parameters": { + "$ref": "#/definitions/DynamicClassificationTaskParameters" + } + }, + "allOf": [ + { + "$ref": "#/definitions/AnalyzeTextTask" + } + ], + "x-ms-discriminator-value": "DynamicClassification" + }, "AnalyzeTextJobsInput": { + "type": "object", "properties": { "displayName": { "description": "Optional display name for the analysis job.", @@ -519,6 +572,7 @@ ] }, "CustomResult": { + "type": "object", "properties": { "errors": { "type": "array", @@ -728,6 +782,25 @@ "modelAsString": true } }, + "documentType": { + "x-ms-enum": { + "name": "documentType", + "modelAsString": true + }, + "type": "string", + "description": "Document type that can be provided as input for Fhir Documents. Expect to have fhirVersion provided when used. Behavior of using None enum is the same as not using the documentType parameter.", + "enum": [ + "None", + "ClinicalTrial", + "DischargeSummary", + "ProgressNote", + "HistoryAndPhysical", + "Consult", + "Imaging", + "Pathology", + "ProcedureNote" + ] + }, "stringIndexType": { "$ref": "common.json#/definitions/StringIndexType" } @@ -761,6 +834,9 @@ "allOf": [ { "$ref": "#/definitions/HealthcareEntitiesDocumentResult" + }, + { + "$ref": "#/definitions/DocumentDetectedLanguage" } ] } @@ -823,32 +899,32 @@ "type": "string", "description": "Healthcare Entity Category.", "enum": [ - "BODY_STRUCTURE", - "AGE", - "GENDER", - "EXAMINATION_NAME", - "DATE", - "DIRECTION", - "FREQUENCY", - "MEASUREMENT_VALUE", - "MEASUREMENT_UNIT", - "RELATIONAL_OPERATOR", - "TIME", - "GENE_OR_PROTEIN", - "VARIANT", - "ADMINISTRATIVE_EVENT", - "CARE_ENVIRONMENT", - "HEALTHCARE_PROFESSION", - "DIAGNOSIS", - "SYMPTOM_OR_SIGN", - "CONDITION_QUALIFIER", - "MEDICATION_CLASS", - "MEDICATION_NAME", - "DOSAGE", - "MEDICATION_FORM", - "MEDICATION_ROUTE", - "FAMILY_RELATION", - "TREATMENT_NAME" + "BodyStructure", + "Age", + "Gender", + "ExaminationName", + "Date", + "Direction", + "Frequency", + "MeasurementValue", + "MeasurementUnit", + "RelationalOperator", + "Time", + "GeneOrProtein", + "Variant", + "AdministrativeEvent", + "CareEnvironment", + "HealthcareProfession", + "Diagnosis", + "SymptomOrSign", + "ConditionQualifier", + "MedicationClass", + "MedicationName", + "Dosage", + "MedicationForm", + "MedicationRoute", + "FamilyRelation", + "TreatmentName" ] }, "subcategory": { @@ -1068,9 +1144,6 @@ "allOf": [ { "$ref": "#/definitions/AnalyzeTextTaskResult" - }, - { - "$ref": "#/definitions/DocumentDetectedLanguage" } ], "required": [ @@ -1088,6 +1161,9 @@ "allOf": [ { "$ref": "#/definitions/SentimentDocumentResult" + }, + { + "$ref": "#/definitions/DocumentDetectedLanguage" } ] } @@ -1449,7 +1525,7 @@ "type": "array", "description": "Recognized entities in the document.", "items": { - "$ref": "#/definitions/Entity" + "$ref": "#/definitions/EntityWithResolution" } } }, @@ -1501,6 +1577,23 @@ } } }, + "EntityWithResolution": { + "type": "object", + "allOf": [ + { + "$ref": "#/definitions/Entity" + } + ], + "properties": { + "resolutions": { + "description": "The collection of entity resolution objects.", + "type": "array", + "items": { + "$ref": "common.json#/definitions/BaseResolution" + } + } + } + }, "EntityLinkingTaskParameters": { "type": "object", "description": "Supported parameters for an Entity Linking task.", @@ -2292,9 +2385,95 @@ "type": "number", "format": "double", "description": "A confidence score between 0 and 1. Scores close to 1 indicate 100% certainty that the identified language is true." + }, + "script": { + "type": "string", + "description": "Identifies the script of the input document.", + "enum": [ + "Latin" + ], + "x-ms-enum": { + "name": "ScriptKind", + "modelAsString": true + } } } }, + "DynamicClassificationTaskParameters": { + "type": "object", + "description": "Supported parameters for a Zero Shot Classification task.", + "properties": { + "classificationType": { + "type": "string", + "description": "Specifies either one or multiple categories per document. Defaults to multi classification which may return more than one class for each document.", + "default": "Multi", + "enum": [ + "Single", + "Multi" + ], + "x-ms-enum": { + "name": "ClassificationType", + "modelAsString": true + } + }, + "categories": { + "type": "array", + "description": "a list of categories to which input is classified to.", + "items": { + "type": "string" + } + } + }, + "allOf": [ + { + "$ref": "common.json#/definitions/PreBuiltTaskParameters" + } + ], + "required": [ + "categories" + ] + }, + "DynamicClassificationTaskResult": { + "type": "object", + "properties": { + "results": { + "$ref": "#/definitions/DynamicClassificationResult" + } + }, + "allOf": [ + { + "$ref": "#/definitions/AnalyzeTextTaskResult" + } + ], + "required": [ + "results" + ], + "x-ms-discriminator-value": "DynamicClassificationResults" + }, + "DynamicClassificationResult": { + "type": "object", + "properties": { + "documents": { + "type": "array", + "description": "Response by document", + "items": { + "allOf": [ + { + "$ref": "#/definitions/ClassificationDocumentResult" + } + ] + } + } + }, + "allOf": [ + { + "$ref": "common.json#/definitions/PreBuiltResult" + } + ], + "required": [ + "documents" + ] + }, "AnalyzeTextJobState": { "allOf": [ { @@ -2583,7 +2762,7 @@ "type": "object", "properties": { "detectedLanguage": { - "type": "string", + "$ref": "#/definitions/DetectedLanguage", "description": "If 'language' is set to 'auto' for the document in the request this field will contain a 2 letter ISO 639-1 representation of the language detected for this document." } } @@ -2757,7 +2936,7 @@ } ] }, - "AbstractiveSummarizationLROResults": { + "AbstractiveSummarizationLROResult": { "type": "object", "description": "An object representing the results for an Abstractive Summarization task.", "properties": { diff --git a/dev/cognitiveservices/data-plane/Language/common.json b/dev/cognitiveservices/data-plane/Language/common.json index e93bb48519e0..4306a76d215c 100644 --- a/dev/cognitiveservices/data-plane/Language/common.json +++ b/dev/cognitiveservices/data-plane/Language/common.json @@ -16,10 +16,7 @@ "description": "The error object.", "$ref": "#/definitions/Error" } - }, - "required": [ - "error" - ] + } }, "Error": { "type": "object", @@ -193,7 +190,7 @@ ], "x-ms-enum": { "modelAsString": true, - "name": "TaskState" + "name": "State" } } }, @@ -270,7 +267,7 @@ "type": "string", "x-ms-enum": { "modelAsString": true, - "name": "JobState" + "name": "State" } }, "errors": { @@ -345,9 +342,27 @@ "RequestStatistics": { "type": "object", "required": [ + "documentsCount", + "validDocumentsCount", + "erroneousDocumentsCount", "transactionsCount" ], "properties": { + "documentsCount": { + "type": "integer", + "format": "int32", + "description": "Number of documents submitted in the request." + }, + "validDocumentsCount": { + "type": "integer", + "format": "int32", + "description": "Number of valid documents. This excludes empty, over-size limit or non-supported languages documents." + }, + "erroneousDocumentsCount": { + "type": "integer", + "format": "int32", + "description": "Number of invalid documents. This includes empty, over-size limit or non-supported languages documents." + }, "transactionsCount": { "type": "integer", "format": "int64", @@ -723,13 +738,72 @@ } } }, + "Sentiment": { + "type": "string", + "description": "Predicted sentiment.", + "enum": [ + "positive", + "neutral", + "negative", + "mixed" + ], + "x-ms-enum": { + "name": "TextSentiment", + "modelAsString": true, + "values": [ + { + "value": "positive", + "description": "Positive sentiment." + }, + { + "value": "neutral", + "description": "Neutral sentiment." + }, + { + "value": "negative", + "description": "Negative sentiment." + }, + { + "value": "mixed", + "description": "Mixed sentiment." + } + ] + } + }, + "SentimentConfidenceScores": { + "type": "object", + "required": [ + "positive", + "neutral", + "negative" + ], + "properties": { + "positive": { + "type": "number", + "format": "double", + "description": "Confidence score for positive sentiment" + }, + "neutral": { + "type": "number", + "format": "double", + "description": "Confidence score for neutral sentiment" + }, + "negative": { + "type": "number", + "format": "double", + "description": "Confidence score for negative sentiment" + } + }, + "description": "Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative." + }, "AbstractiveSummarizationTaskParametersBase": { "type": "object", "description": "Supported parameters for an Abstractive Summarization task.", "properties": { "sentenceCount": { "type": "integer", - "format": "int32" + "format": "int32", + "description": "It controls the approximate number of sentences in the output summaries." }, "stringIndexType": { "$ref": "#/definitions/StringIndexType" @@ -806,6 +880,660 @@ "description": "The length of the context. Use of different 'stringIndexType' values can affect the length returned." } } + }, + "BaseResolution": { + "description": "The abstract base class for entity resolutions.", + "type": "object", + "discriminator": "resolutionKind", + "properties": { + "resolutionKind": { + "description": "The entity resolution object kind.", + "type": "string", + "enum": [ + "BooleanResolution", + "DateTimeResolution", + "NumberResolution", + "OrdinalResolution", + "SpeedResolution", + "WeightResolution", + "LengthResolution", + "VolumeResolution", + "AreaResolution", + "AgeResolution", + "InformationResolution", + "TemperatureResolution", + "CurrencyResolution", + "NumericRangeResolution", + "TemporalSpanResolution" + ], + "x-ms-enum": { + "name": "ResolutionKind", + "modelAsString": true + } + } + }, + "required": [ + "resolutionKind" + ] + }, + "QuantityResolution": { + "description": "Represents resolutions for quantities.", + "type": "object", + "properties": { + "value": { + "type": "number", + "format": "double", + "description": "The numeric value that the extracted text denotes." + } + }, + "required": [ + "value" + ] + }, + "AgeResolution": { + "description": "Represents the Age entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "AgeResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "Year", + "Month", + "Week", + "Day" + ], + "x-ms-enum": { + "name": "AgeUnit", + "modelAsString": true + }, + "description": "The Age Unit of measurement" + } + }, + "required": [ + "unit" + ] + }, + "VolumeResolution": { + "description": "Represents the volume entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "VolumeResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "CubicMeter", + "CubicCentimeter", + "CubicMillimeter", + "Hectoliter", + "Decaliter", + "Liter", + "Centiliter", + "Milliliter", + "CubicYard", + "CubicInch", + "CubicFoot", + "CubicMile", + "FluidOunce", + "Teaspoon", + "Tablespoon", + "Pint", + "Quart", + "Cup", + "Gill", + "Pinch", + "FluidDram", + "Barrel", + "Minim", + "Cord", + "Peck", + "Bushel", + "Hogshead" + ], + "x-ms-enum": { + "name": "VolumeUnit", + "modelAsString": true + }, + "description": "The Volume Unit of measurement" + } + }, + "required": [ + "unit" + ] + }, + "SpeedResolution": { + "description": "Represents the speed entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "SpeedResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "MetersPerSecond", + "KilometersPerHour", + "KilometersPerMinute", + "KilometersPerSecond", + "MilesPerHour", + "Knot", + "FootPerSecond", + "FootPerMinute", + "YardsPerMinute", + "YardsPerSecond", + "MetersPerMillisecond", + "CentimetersPerMillisecond", + "KilometersPerMillisecond" + ], + "x-ms-enum": { + "name": "SpeedUnit", + "modelAsString": true + }, + "description": "The speed Unit of measurement" + } + }, + "required": [ + "unit" + ] + }, + "AreaResolution": { + "description": "Represents the area entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "AreaResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "SquareKilometer", + "SquareHectometer", + "SquareDecameter", + "SquareDecimeter", + "SquareMeter", + "SquareCentimeter", + "SquareMillimeter", + "SquareInch", + "SquareFoot", + "SquareMile", + "SquareYard", + "Acre" + ], + "x-ms-enum": { + "name": "AreaUnit", + "modelAsString": true + }, + "description": "The area Unit of measurement" + } + }, + "required": [ + "unit" + ] + }, + "LengthResolution": { + "description": "Represents the length entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "LengthResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "Kilometer", + "Hectometer", + "Decameter", + "Meter", + "Decimeter", + "Centimeter", + "Millimeter", + "Micrometer", + "Nanometer", + "Picometer", + "Mile", + "Yard", + "Inch", + "Foot", + "LightYear", + "Pt" + ], + "x-ms-enum": { + "name": "LengthUnit", + "modelAsString": true + }, + "description": "The length Unit of measurement" + } + }, + "required": [ + "unit" + ] + }, + "InformationResolution": { + "description": "Represents the information (data) entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "InformationResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "Bit", + "Kilobit", + "Megabit", + "Gigabit", + "Terabit", + "Petabit", + "Byte", + "Kilobyte", + "Megabyte", + "Gigabyte", + "Terabyte", + "Petabyte" + ], + "x-ms-enum": { + "name": "InformationUnit", + "modelAsString": true + }, + "description": "The information (data) Unit of measurement." + } + }, + "required": [ + "unit" + ] + }, + "TemperatureResolution": { + "description": "Represents the temperature entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "TemperatureResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "Fahrenheit", + "Kelvin", + "Rankine", + "Celsius" + ], + "x-ms-enum": { + "name": "TemperatureUnit", + "modelAsString": true + }, + "description": "The temperature Unit of measurement." + } + }, + "required": [ + "unit" + ] + }, + "WeightResolution": { + "description": "Represents the weight entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "WeightResolution", + "properties": { + "unit": { + "type": "string", + "enum": [ + "Unspecified", + "Kilogram", + "Gram", + "Milligram", + "Gallon", + "MetricTon", + "Ton", + "Pound", + "Ounce", + "Grain", + "PennyWeight", + "LongTonBritish", + "ShortTonUS", + "ShortHundredWeightUS", + "Stone", + "Dram" + ], + "x-ms-enum": { + "name": "WeightUnit", + "modelAsString": true + }, + "description": "The weight Unit of measurement." + } + }, + "required": [ + "unit" + ] + }, + "CurrencyResolution": { + "description": "Represents the currency entity resolution model.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + }, + { + "$ref": "#/definitions/QuantityResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "CurrencyResolution", + "properties": { + "ISO4217": { + "type": "string", + "description": "The alphabetic code based on another ISO standard, ISO 3166, which lists the codes for country names. The first two letters of the ISO 4217 three-letter code are the same as the code for the country name, and, where possible, the third letter corresponds to the first letter of the currency name." + }, + "value": { + "type": "number", + "format": "double", + "description": "The money amount captured in the extracted entity" + }, + "unit": { + "type": "string", + "description": "The unit of the amount captured in the extracted entity" + } + }, + "required": [ + "value", + "unit" + ] + }, + "BooleanResolution": { + "description": "A resolution for boolean expressions", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "BooleanResolution", + "properties": { + "value": { + "type": "boolean" + } + }, + "required": [ + "value" + ] + }, + "DateTimeResolution": { + "description": "A resolution for datetime entity instances.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "DateTimeResolution", + "properties": { + "timex": { + "$ref": "#/definitions/TimeExpression" + }, + "dateTimeSubKind": { + "type": "string", + "enum": [ + "Time", + "Date", + "DateTime", + "Duration", + "Set" + ], + "x-ms-enum": { + "name": "DateTimeSubKind", + "modelAsString": true + }, + "description": "The DateTime SubKind" + }, + "value": { + "type": "string", + "description": "The actual time that the extracted text denote." + }, + "modifier": { + "$ref": "#/definitions/TemporalModifier" + } + }, + "required": [ + "timex", + "dateTimeSubKind", + "value" + ] + }, + "NumberResolution": { + "description": "A resolution for numeric entity instances.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "NumberResolution", + "properties": { + "numberKind": { + "type": "string", + "enum": [ + "Integer", + "Decimal", + "Power", + "Fraction", + "Percent", + "Unspecified" + ], + "x-ms-enum": { + "name": "NumberKind", + "modelAsString": true + }, + "description": "The type of the extracted number entity." + }, + "value": { + "type": "string", + "description": "A numeric representation of what the extracted text denotes." + } + }, + "required": [ + "numberKind", + "value" + ] + }, + "OrdinalResolution": { + "description": "A resolution for ordinal numbers entity instances.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "OrdinalResolution", + "properties": { + "offset": { + "type": "string", + "description": "The offset With respect to the reference (e.g., offset = -1 in \"show me the second to last\"" + }, + "relativeTo": { + "type": "string", + "enum": [ + "Current", + "End", + "Start" + ], + "x-ms-enum": { + "name": "RelativeTo", + "modelAsString": true + }, + "description": "The reference point that the ordinal number denotes." + }, + "value": { + "type": "string", + "description": "A simple arithmetic expression that the ordinal denotes." + } + }, + "required": [ + "offset", + "relativeTo", + "value" + ] + }, + "TemporalSpanResolution": { + "description": "represents the resolution of a date and/or time span.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "TemporalSpanResolution", + "properties": { + "begin": { + "$ref": "#/definitions/TimeExpression" + }, + "end": { + "$ref": "#/definitions/TimeExpression" + }, + "duration": { + "type": "string", + "description": "An optional duration value formatted based on the ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601#Durations)" + }, + "modifier": { + "$ref": "#/definitions/TemporalModifier" + } + } + }, + "NumericRangeResolution": { + "description": "represents the resolution of numeric intervals.", + "allOf": [ + { + "$ref": "#/definitions/BaseResolution" + } + ], + "type": "object", + "x-ms-discriminator-value": "NumericRangeResolution", + "properties": { + "rangeKind": { + "type": "string", + "enum": [ + "Number", + "Speed", + "Weight", + "Length", + "Volume", + "Area", + "Age", + "Information", + "Temperature", + "Currency" + ], + "x-ms-enum": { + "name": "RangeKind", + "modelAsString": true + }, + "description": "The kind of range that the resolution object represents." + }, + "minimum": { + "type": "number", + "format": "double", + "description": "The beginning value of the interval." + }, + "maximum": { + "type": "number", + "format": "double", + "description": "The ending value of the interval." + } + }, + "required": [ + "rangeKind", + "minimum", + "maximum" + ] + }, + "TemporalModifier": { + "type": "string", + "description": "An optional modifier of a date/time instance.", + "enum": [ + "AfterApprox", + "Before", + "BeforeStart", + "Approx", + "ReferenceUndefined", + "SinceEnd", + "AfterMid", + "Start", + "After", + "BeforeEnd", + "Until", + "End", + "Less", + "Since", + "AfterStart", + "BeforeApprox", + "Mid", + "More" + ], + "x-ms-enum": { + "name": "TemporalModifier", + "modelAsString": true + } + }, + "TimeExpression": { + "type": "string", + "description": "An extended ISO 8601 date/time representation as described in (https://github.com/Microsoft/Recognizers-Text/blob/master/Patterns/English/English-DateTime.yaml)" } }, "parameters": { diff --git a/dev/cognitiveservices/data-plane/Language/examples/conversations/SuccessfulConversationSentimentSubmit.json b/dev/cognitiveservices/data-plane/Language/examples/conversations/SuccessfulConversationSentimentSubmit.json new file mode 100644 index 000000000000..605bb7c25d74 --- /dev/null +++ b/dev/cognitiveservices/data-plane/Language/examples/conversations/SuccessfulConversationSentimentSubmit.json @@ -0,0 +1,47 @@ +{ + "parameters": { + "Ocp-Apim-Subscription-Key": "{API key}", + "api-version": "2022-10-01-preview", + "Endpoint": "{Endpoint}", + "jobId": "{Job ID}", + "body": { + "displayName": "Sentiment Analysis from a call center conversation", + "analysisInput": { + "conversations": [ + { + "id": "1", + "language": "en", + "modality": "transcript", + "conversationItems": [ + { + "participantId": "1", + "id": "1", + "text": "I like the service. I do not like the food", + "lexical": "i like the service i do not like the food", + "itn": "", + "maskedItn": "" + } + ] + } + ] + }, + "tasks": [ + { + "taskName": "Conversation Sentiment Analysis", + "kind": "ConversationalSentimentTask", + "parameters": { + "modelVersion": "latest", + "predictionSource": "text" + } + } + ] + } + }, + "responses": { + "202": { + "headers": { + "Operation-Location": "{Endpoint}/language/analyze-conversation/jobs/{jobId}?api-version={api-version}" + } + } + } +} diff --git a/dev/cognitiveservices/data-plane/Language/examples/conversations/SuccessfulConversationSentimentTaskStatusRequest.json b/dev/cognitiveservices/data-plane/Language/examples/conversations/SuccessfulConversationSentimentTaskStatusRequest.json new file mode 100644 index 000000000000..6c67be4feda3 --- /dev/null +++ b/dev/cognitiveservices/data-plane/Language/examples/conversations/SuccessfulConversationSentimentTaskStatusRequest.json @@ -0,0 +1,60 @@ +{ + "parameters": { + "Ocp-Apim-Subscription-Key": "{API key}", + "api-version": "2022-10-01-preview", + "Endpoint": "{Endpoint}", + "jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18" + }, + "responses": { + "200": { + "headers": {}, + "body": { + "createdDateTime": "2022-04-01T15:00:45Z", + "displayName": "Sentiment Analysis from a call center conversation", + "expirationDateTime": "2022-04-01T15:00:45Z", + "jobId": "c0f2a446-05d9-48fc-ba8f-3ef4af8d0b18", + "lastUpdatedDateTime": "2022-04-01T15:00:45Z", + "status": "succeeded", + "tasks": { + "completed": 1, + "failed": 0, + "inProgress": 0, + "total": 1, + "items": [ + { + "kind": "ConversationalSentimentResults", + "taskName": "Conversation Sentiment", + "lastUpdateDateTime": "2022-04-01T15:00:45Z", + "status": "succeeded", + "results": { + "conversations": [ + { + "id": "1", + "conversationItems": [ + { + "id": "1", + "participantId": "agent_1", + "sentiment": "mixed", + "confidenceScores": { + "positive": 0.5, + "neutral": 0.01, + "negative": 0.49 + } + } + ], + "warnings": [], + "statistics": { + "transactionsCount": 1 + } + } + ], + "errors": [], + "modelVersion": "2022-10-01-preview" + } + } + ] + } + } + } + } +} diff --git a/dev/cognitiveservices/data-plane/Language/examples/questionanswering/SuccessfulQueryKnowledgebases.json b/dev/cognitiveservices/data-plane/Language/examples/questionanswering/SuccessfulQueryKnowledgebases.json index 6e4c04cc6a92..059856e31de4 100644 --- a/dev/cognitiveservices/data-plane/Language/examples/questionanswering/SuccessfulQueryKnowledgebases.json +++ b/dev/cognitiveservices/data-plane/Language/examples/questionanswering/SuccessfulQueryKnowledgebases.json @@ -10,7 +10,7 @@ "question": "how long it takes to charge surface?", "top": 3, "userId": "sd53lsY=", - "confidenceScoreThreshold": 0.20, + "confidenceScoreThreshold": 0.2, "context": { "previousQnaId": 9, "previousUserQuery": "Where are QnA Maker quickstarts?" @@ -38,7 +38,7 @@ }, "answerSpanRequest": { "enable": true, - "confidenceScoreThreshold": 0.20, + "confidenceScoreThreshold": 0.2, "topAnswersWithSpan": 1 }, "includeUnstructuredSources": true @@ -78,7 +78,7 @@ }, "answerSpan": { "text": "two to four hours", - "confidenceScore": 0.30, + "confidenceScore": 0.3, "offset": 33, "length": 50 } diff --git a/dev/cognitiveservices/data-plane/Language/examples/questionanswering/authoring/SuccessfulProjectSubmitExportJob.json b/dev/cognitiveservices/data-plane/Language/examples/questionanswering/authoring/SuccessfulProjectSubmitExportJob.json index 0a37b03d5f77..4b6597a8f3c8 100644 --- a/dev/cognitiveservices/data-plane/Language/examples/questionanswering/authoring/SuccessfulProjectSubmitExportJob.json +++ b/dev/cognitiveservices/data-plane/Language/examples/questionanswering/authoring/SuccessfulProjectSubmitExportJob.json @@ -3,7 +3,7 @@ "Endpoint": "{Endpoint}", "Ocp-Apim-Subscription-Key": "{API key}", "Content-Type": "application/json", - "api-version": "2022-07-01-preview", + "api-version": "2022-10-01-preview", "projectName": "proj1", "body": { "exportAssetTypes": [ @@ -13,6 +13,18 @@ } }, "responses": { + "200": { + "headers": {}, + "body": { + "errors": [], + "createdDateTime": "2021-05-01T17:21:14Z", + "expirationDateTime": "2021-05-01T17:21:14Z", + "jobId": "635c2741-15c4-4c2c-9f78-bfd30b6b2a4a", + "lastUpdatedDateTime": "2021-05-01T17:21:14Z", + "status": "succeeded", + "resultUrl": "https:///language/authoring/query-knowledgebases/projects/proj1/export/jobs/job1/result?api-version=2022-10-01-preview" + } + }, "202": { "description": "A successful call results with an Operation-Location header used to check the status of the analysis job.", "headers": { diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfuDynamicClassificationRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfuDynamicClassificationRequest.json new file mode 100644 index 000000000000..d0f1f5290875 --- /dev/null +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfuDynamicClassificationRequest.json @@ -0,0 +1,92 @@ +{ + "parameters": { + "Ocp-Apim-Subscription-Key": "{API key}", + "api-version": "2022-10-01-preview", + "Endpoint": "{Endpoint}", + "body": { + "kind": "DynamicClassification", + "parameters": { + "categories": [ + "Health", + "Politics", + "Music", + "Sports" + ], + "classificationType": "Multi", + "modelVersion": "latest" + }, + "analysisInput": { + "documents": [ + { + "id": "1", + "language": "en", + "text": "The WHO is issuing a warning about Monkey Pox." + }, + { + "id": "2", + "language": "en", + "text": "Mo Salah plays in Liverpool FC in England." + } + ] + } + } + }, + "responses": { + "200": { + "headers": {}, + "body": { + "kind": "DynamicClassificationResults", + "results": { + "documents": [ + { + "id": "1", + "class": [ + { + "category": "Health", + "confidenceScore": 0.9 + }, + { + "category": "Politics", + "confidenceScore": 0.8 + }, + { + "category": "Music", + "confidenceScore": 0.7 + }, + { + "category": "Sports", + "confidenceScore": 0.6 + } + ], + "warnings": [] + }, + { + "id": "2", + "class": [ + { + "category": "Health", + "confidenceScore": 0.9 + }, + { + "category": "Politics", + "confidenceScore": 0.8 + }, + { + "category": "Music", + "confidenceScore": 0.7 + }, + { + "category": "Sports", + "confidenceScore": 0.6 + } + ], + "warnings": [] + } + ], + "errors": [], + "modelVersion": "2022-10-01-preview" + } + } + } + } +} diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulEntityRecognitionRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulEntityRecognitionRequest.json index 166686751a03..ed4c7829dc23 100644 --- a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulEntityRecognitionRequest.json +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulEntityRecognitionRequest.json @@ -13,7 +13,7 @@ { "id": "1", "language": "en", - "text": "Microsoft was founded by Bill Gates and Paul Allen." + "text": "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975." }, { "id": "2", @@ -53,6 +53,22 @@ "length": 10, "offset": 40, "text": "Paul Allen" + }, + { + "text": "April 4, 1975", + "category": "DateTime", + "subcategory": "Date", + "offset": 54, + "length": 13, + "confidenceScore": 0.99, + "resolutions": [ + { + "resolutionKind": "DateTimeResolution", + "dateTimeSubKind": "Date", + "timex": "1975-04-04", + "value": "1975-04-04" + } + ] } ], "id": "1", diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareDocumentTypePostRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareDocumentTypePostRequest.json new file mode 100644 index 000000000000..df2c19c697a7 --- /dev/null +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareDocumentTypePostRequest.json @@ -0,0 +1,36 @@ +{ + "parameters": { + "Ocp-Apim-Subscription-Key": "{API key}", + "api-version": "2022-10-01-preview", + "Endpoint": "{Endpoint}", + "jobId": "{Job ID}", + "body": { + "analysisInput": { + "documents": [ + { + "text": "Prescribed 100mg ibuprofen, taken twice daily.", + "id": "1", + "language": "en" + } + ] + }, + "tasks": [ + { + "kind": "Healthcare", + "parameters": { + "modelVersion": "latest", + "fhirVersion": "4.0.1", + "documentType": "DischargeSummary" + } + } + ] + } + }, + "responses": { + "202": { + "headers": { + "Operation-Location": "{Endpoint}/language/analyze-text/jobs/{jobId}?api-version={api-version}" + } + } + } +} diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareDocumentTypeTaskStatusRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareDocumentTypeTaskStatusRequest.json new file mode 100644 index 000000000000..addffd05af3a --- /dev/null +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareDocumentTypeTaskStatusRequest.json @@ -0,0 +1,552 @@ +{ + "parameters": { + "Ocp-Apim-Subscription-Key": "{API key}", + "api-version": "2022-10-01-preview", + "Endpoint": "{Endpoint}", + "jobId": "15e4a46b-62e2-4386-8d36-9c2a92bb45dd" + }, + "responses": { + "200": { + "headers": {}, + "body": { + "createdDateTime": "2022-09-06T23:47:43Z", + "displayName": "Providing Document Type", + "expirationDateTime": "2022-09-07T23:47:43Z", + "jobId": "15e4a46b-62e2-4386-8d36-9c2a92bb45dd", + "lastUpdatedDateTime": "2022-09-06T23:48:10Z", + "status": "succeeded", + "errors": [], + "tasks": { + "completed": 1, + "failed": 0, + "inProgress": 0, + "total": 1, + "items": [ + { + "kind": "HealthcareLROResults", + "lastUpdateDateTime": "2022-09-06T23:48:10.1762027Z", + "status": "succeeded", + "results": { + "documents": [ + { + "id": "a", + "entities": [ + { + "offset": 11, + "length": 5, + "text": "100mg", + "category": "Dosage", + "confidenceScore": 0.98 + }, + { + "offset": 17, + "length": 9, + "text": "ibuprofen", + "category": "MedicationName", + "confidenceScore": 1.0, + "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" + } + ] + }, + { + "offset": 34, + "length": 11, + "text": "twice daily", + "category": "Frequency", + "confidenceScore": 1.0 + } + ], + "relations": [ + { + "confidenceScore": 1.0, + "relationType": "DosageOfMedication", + "entities": [ + { + "ref": "#/results/documents/0/entities/0", + "role": "Dosage" + }, + { + "ref": "#/results/documents/0/entities/1", + "role": "Medication" + } + ] + }, + { + "confidenceScore": 1.0, + "relationType": "FrequencyOfMedication", + "entities": [ + { + "ref": "#/results/documents/0/entities/1", + "role": "Medication" + }, + { + "ref": "#/results/documents/0/entities/2", + "role": "Frequency" + } + ] + } + ], + "warnings": [], + "fhirBundle": { + "resourceType": "Bundle", + "id": "6ee4a7c0-5911-4c4b-bea2-3c2a1fe5c65f", + "meta": { + "profile": [ + "http://hl7.org/fhir/4.0.1/StructureDefinition/Bundle" + ] + }, + "identifier": { + "system": "urn:ietf:rfc:3986", + "value": "urn:uuid:6ee4a7c0-5911-4c4b-bea2-3c2a1fe5c65f" + }, + "type": "document", + "entry": [ + { + "fullUrl": "Composition/5bd33290-b92e-4aa5-becf-535578207946", + "resource": { + "resourceType": "Composition", + "id": "5bd33290-b92e-4aa5-becf-535578207946", + "status": "final", + "type": { + "coding": [ + { + "system": "http://loinc.org", + "code": "18842-5", + "display": "Discharge summary" + } + ], + "text": "Discharge summary" + }, + "subject": { + "reference": "Patient/efcccdf7-87f0-4061-b553-09fc11734594", + "type": "Patient" + }, + "encounter": { + "reference": "Encounter/76214457-f94c-4ccf-95ef-ab31e7232d63", + "type": "Encounter", + "display": "unknown" + }, + "date": "2022-09-06", + "author": [ + { + "reference": "Practitioner/bba2dee3-2eb3-4973-b4b9-62d498b17046", + "type": "Practitioner", + "display": "Unknown" + } + ], + "title": "Discharge summary", + "section": [ + { + "title": "General", + "code": { + "coding": [ + { + "system": "", + "display": "Unrecognized Section" + } + ], + "text": "General" + }, + "text": { + "status": "additional", + "div": "
\r\n\t\t\t\t\t\t\t

General

\r\n\t\t\t\t\t\t\t

Prescribed 100mg ibuprofen, taken twice daily.

\r\n\t\t\t\t\t
" + }, + "entry": [ + { + "reference": "List/6d743a3e-e7a2-4cee-a0b5-64361b6c93ad", + "type": "List", + "display": "General" + } + ] + } + ] + } + }, + { + "fullUrl": "Practitioner/bba2dee3-2eb3-4973-b4b9-62d498b17046", + "resource": { + "resourceType": "Practitioner", + "id": "bba2dee3-2eb3-4973-b4b9-62d498b17046", + "name": [ + { + "text": "Unknown", + "family": "Unknown" + } + ] + } + }, + { + "fullUrl": "Patient/efcccdf7-87f0-4061-b553-09fc11734594", + "resource": { + "resourceType": "Patient", + "id": "efcccdf7-87f0-4061-b553-09fc11734594", + "gender": "unknown" + } + }, + { + "fullUrl": "Encounter/76214457-f94c-4ccf-95ef-ab31e7232d63", + "resource": { + "resourceType": "Encounter", + "id": "76214457-f94c-4ccf-95ef-ab31e7232d63", + "meta": { + "profile": [ + "http://hl7.org/fhir/us/core/StructureDefinition/us-core-encounter" + ] + }, + "status": "finished", + "class": { + "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", + "display": "unknown" + }, + "subject": { + "reference": "Patient/efcccdf7-87f0-4061-b553-09fc11734594", + "type": "Patient" + }, + "period": { + "start": "2022-09-06", + "end": "2022-09-06" + } + } + }, + { + "fullUrl": "MedicationStatement/ac0264b6-63b7-4cf2-a7c3-f7340788aca7", + "resource": { + "resourceType": "MedicationStatement", + "id": "ac0264b6-63b7-4cf2-a7c3-f7340788aca7", + "extension": [ + { + "extension": [ + { + "url": "offset", + "valueInteger": 17 + }, + { + "url": "length", + "valueInteger": 9 + } + ], + "url": "http://hl7.org/fhir/StructureDefinition/derivation-reference" + } + ], + "status": "active", + "medicationCodeableConcept": { + "coding": [ + { + "system": "http://www.nlm.nih.gov/research/umls", + "code": "C0020740", + "display": "ibuprofen" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/aod", + "code": "0000019879" + }, + { + "system": "http://www.whocc.no/atc", + "code": "M01AE01" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/ccpss", + "code": "0046165" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/chv", + "code": "0000006519" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/csp", + "code": "2270-2077" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/drugbank", + "code": "DB01050" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/gs", + "code": "1611" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/lch_nw", + "code": "sh97005926" + }, + { + "system": "http://loinc.org", + "code": "LP16165-0" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/medcin", + "code": "40458" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/mmsl", + "code": "d00015" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/msh", + "code": "D007052" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/mthspl", + "code": "WK2XYI10QM" + }, + { + "system": "http://ncimeta.nci.nih.gov", + "code": "C561" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/nci_ctrp", + "code": "C561" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/nci_dcp", + "code": "00803" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/nci_dtp", + "code": "NSC0256857" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/nci_fda", + "code": "WK2XYI10QM" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/nci_nci-gloss", + "code": "CDR0000613511" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/nddf", + "code": "002377" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/pdq", + "code": "CDR0000040475" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/rcd", + "code": "x02MO" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/rxnorm", + "code": "5640" + }, + { + "system": "http://snomed.info/sct", + "code": "E-7772" + }, + { + "system": "http://snomed.info/sct", + "code": "C-603C0" + }, + { + "system": "http://snomed.info/sct", + "code": "387207008" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/usp", + "code": "m39860" + }, + { + "system": "http://www.nlm.nih.gov/research/umls/uspmg", + "code": "MTHU000060" + }, + { + "system": "http://hl7.org/fhir/ndfrt", + "code": "4017840" + } + ], + "text": "ibuprofen" + }, + "subject": { + "reference": "Patient/efcccdf7-87f0-4061-b553-09fc11734594", + "type": "Patient" + }, + "context": { + "reference": "Encounter/76214457-f94c-4ccf-95ef-ab31e7232d63", + "type": "Encounter", + "display": "unknown" + }, + "dosage": [ + { + "text": "100mg", + "timing": { + "repeat": { + "frequency": 2, + "period": 1, + "periodUnit": "d" + }, + "code": { + "text": "twice daily" + } + }, + "doseAndRate": [ + { + "doseQuantity": { + "value": 100 + } + } + ] + } + ] + } + }, + { + "fullUrl": "List/6d743a3e-e7a2-4cee-a0b5-64361b6c93ad", + "resource": { + "resourceType": "List", + "id": "6d743a3e-e7a2-4cee-a0b5-64361b6c93ad", + "status": "current", + "mode": "snapshot", + "title": "General", + "subject": { + "reference": "Patient/efcccdf7-87f0-4061-b553-09fc11734594", + "type": "Patient" + }, + "encounter": { + "reference": "Encounter/76214457-f94c-4ccf-95ef-ab31e7232d63", + "type": "Encounter", + "display": "unknown" + }, + "entry": [ + { + "item": { + "reference": "MedicationStatement/ac0264b6-63b7-4cf2-a7c3-f7340788aca7", + "type": "MedicationStatement", + "display": "ibuprofen" + } + } + ] + } + } + ] + } + } + ], + "errors": [], + "modelVersion": "2022-03-01" + } + } + ] + } + } + } + } +} diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcarePostRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcarePostRequest.json index e43dd063fb2a..24008d037df8 100644 --- a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcarePostRequest.json +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcarePostRequest.json @@ -1,7 +1,7 @@ { "parameters": { "Ocp-Apim-Subscription-Key": "{API key}", - "api-version": "2022-07-01-preview", + "api-version": "2022-10-01-preview", "Endpoint": "{Endpoint}", "jobId": "{Job ID}", "body": { diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareTaskStatusRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareTaskStatusRequest.json index 9b2118f9571d..2e7c456a31d0 100644 --- a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareTaskStatusRequest.json +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulHealthcareTaskStatusRequest.json @@ -1,7 +1,7 @@ { "parameters": { "Ocp-Apim-Subscription-Key": "{API key}", - "api-version": "2022-07-01-preview", + "api-version": "2022-10-01-preview", "Endpoint": "{Endpoint}", "jobId": "1780194a-e9c1-4298-b0d4-fdc59ba818a0" }, diff --git a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulLanguageDetectionRequest.json b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulLanguageDetectionRequest.json index 9aea23cf3940..ce942d2d2de3 100644 --- a/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulLanguageDetectionRequest.json +++ b/dev/cognitiveservices/data-plane/Language/examples/text/SuccessfulLanguageDetectionRequest.json @@ -21,6 +21,10 @@ { "id": "3", "text": "Hola mundo" + }, + { + "id": "4", + "text": "Tumhara naam kya hai?" } ] } @@ -59,6 +63,16 @@ }, "id": "3", "warnings": [] + }, + { + "detectedLanguage": { + "confidenceScore": 1, + "iso6391Name": "hi", + "name": "Hindi", + "script": "Latin" + }, + "id": "4", + "warnings": [] } ], "errors": [], diff --git a/dev/cognitiveservices/data-plane/Language/questionanswering-authoring.json b/dev/cognitiveservices/data-plane/Language/questionanswering-authoring.json index 144a827de3bc..97ad3849f6a0 100644 --- a/dev/cognitiveservices/data-plane/Language/questionanswering-authoring.json +++ b/dev/cognitiveservices/data-plane/Language/questionanswering-authoring.json @@ -3,7 +3,7 @@ "info": { "title": "Microsoft Cognitive Language Service - Question Answering - Authoring", "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 https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview.", - "version": "2022-07-01-preview" + "version": "2022-10-01-preview" }, "securityDefinitions": { "AADToken": { diff --git a/dev/cognitiveservices/data-plane/Language/questionanswering.json b/dev/cognitiveservices/data-plane/Language/questionanswering.json index 3809c333c119..54d4c5088c69 100644 --- a/dev/cognitiveservices/data-plane/Language/questionanswering.json +++ b/dev/cognitiveservices/data-plane/Language/questionanswering.json @@ -3,7 +3,7 @@ "info": { "title": "Microsoft Cognitive Language Service - Question Answering", "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 https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview.", - "version": "2022-07-01-preview" + "version": "2022-10-01-preview" }, "securityDefinitions": { "AADToken": { diff --git a/dev/cognitiveservices/data-plane/Language/readme.md b/dev/cognitiveservices/data-plane/Language/readme.md index 81e4097dbf2d..90f37fe19e79 100644 --- a/dev/cognitiveservices/data-plane/Language/readme.md +++ b/dev/cognitiveservices/data-plane/Language/readme.md @@ -57,7 +57,7 @@ This is not used by Autorest itself. ``` yaml $(swagger-to-sdk) swagger-to-sdk: - - repo: azure-sdk-for-net + - repo: azure-sdk-for-net-track2 - repo: azure-sdk-for-python ``` diff --git a/documentation/BreakingChange-Oad-Rules-Mapping.md b/documentation/BreakingChange-Oad-Rules-Mapping.md new file mode 100644 index 000000000000..bc8d7b66ab12 --- /dev/null +++ b/documentation/BreakingChange-Oad-Rules-Mapping.md @@ -0,0 +1,54 @@ +# Azure REST API Breaking Change And Oad Rules Mapping + +## Overview +This specification describes the relationship between [oad rules](https://github.com/Azure/openapi-diff/tree/main/docs) and [breaking change policy](https://aka.ms/AzBreakingChangesPolicy). + +## Mapping + +| oad rule | breaking change category +|---|---| +|[1002 - ProtocolNoLongerSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1002.md) | breaking change | +|[1003 - RequestBodyFormatNoLongerSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1003.md) | breaking change | +|[1004 - ResponseBodyFormatNowSupported](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1004.md) | breaking change | +|[1005 - RemovedPath](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1005.md) | breaking change | +|[1006 - RemovedDefinition](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1006.md) | breaking change | +|[1007 - RemovedClientParameter](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1007.md) | breaking change | +|[1008 - ModifiedOperationId](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1008.md) | breaking change | +|[1009 - RemovedRequiredParameter](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1009.md) | breaking change | +|[1010 - AddingRequiredParameter](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1010.md) | breaking change | +|[1011 - AddingResponseCode](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1011.md) | breaking change | +|[1012 - RemovedResponseCode](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1012.md) | breaking change | +|[1013 - AddingHeader](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1013.md) | breaking change | +|[1014 - RemovingHeader](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1014.md) | breaking change | +|[1015 - ParameterInHasChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1015.md) | breaking change | +|[1016 - ConstantStatusHasChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1016.md) | breaking change | +|[1017 - ReferenceRedirection](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1017.md) | breaking change | +|[1019 - RemovedEnumValue](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1019.md) | breaking change | +|[1020 - AddedEnumValue](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1020.md) |change allowed in a new api-version| +|[1021 - AddedAdditionalProperties](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1021.md) | breaking change | +|[1022 - RemovedAdditionalProperties](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1022.md) | breaking change | +|[1023 - TypeFormatChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1023.md) | breaking change | +|[1024 - ConstraintIsStronger](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1024.md) | breaking change | +|[1025 - RequiredStatusChange](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1025.md) | breaking change | +|[1026 - TypeChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1026.md) | breaking change | +|[1027 - DefaultValueChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1027.md) | breaking change | +|[1028 - ArrayCollectionFormatChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1028.md) | breaking change | +|[1029 - ReadonlyPropertyChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1029.md) | breaking change (exception: non if from 'true' to 'false')| +|[1030 - DifferentDiscriminator](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1030.md) | breaking change | +|[1031 - DifferentExtends](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1031.md) | breaking change | +|[1032 - DifferentAllOf](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1032.md) | breaking change | +|[1033 - RemovedProperty](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1033.md) | breaking change | +|[1034 - AddedRequiredProperty](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1034.md) | breaking change | +|[1035 - RemovedOperation](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1035.md) | breaking change | +|[1036 - ConstraintChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1036.md) | breaking change | +|[1037 - ConstraintIsWeaker](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1037.md) | breaking change (exception：non if applies to request parameter) | +|[1038 - AddedPath](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1038.md) |change allowed in a new api-version| +|[1039 - AddedOperation](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1039.md) |change allowed in a new api-version| +|[1040 - AddedReadOnlyPropertyInResponse](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1040.md) |change allowed in a new api-version | +|[1041 - AddedPropertyInResponse](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1041.md) | change allowed in a new api-version | +|[1042 - ChangedParameterOrder](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1042.md) | breaking change | +|[1043 - AddingOptionalParameter](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1043.md) | breaking change | +|[1044 - XmsLongRunningOperationChanged](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1044.md) | breaking change | +|[1045 - AddedOptionalProperty](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1045.md) | breaking change | +|[1046 - RemovedOptionalParameter](https://github.com/Azure/openapi-diff/blob/main/docs/rules/1046.md) | breaking change | + diff --git a/documentation/ContributingGuidelines.md b/documentation/ContributingGuidelines.md deleted file mode 100644 index 3f53d95f3f8f..000000000000 --- a/documentation/ContributingGuidelines.md +++ /dev/null @@ -1,5 +0,0 @@ -For internal contributor, for management plane, please refer to https://aka.ms/rpguidelines; - -For data-plane, please refer to [Guide to design and creation of Data Plane REST API and Client Libraries](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/591/Guide-to-design-and-creation-of-Data-Plane-REST-API-and-Client-Libraries); - -For contribution access to spec repos, please refer to [Public repo vs. Private repo: To get write access](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/202/Overall-Process-of-Management-Plane-SDK-Onboarding?anchor=2.-create/update-the-openapi-specifications%2C-and-launch-swagger-pr-review) diff --git a/documentation/api-scenario/how-to/GenerateABasicApiScenario.md b/documentation/api-scenario/how-to/GenerateABasicApiScenario.md index 19d6e75c4093..44212740228b 100644 --- a/documentation/api-scenario/how-to/GenerateABasicApiScenario.md +++ b/documentation/api-scenario/how-to/GenerateABasicApiScenario.md @@ -16,7 +16,7 @@ npm i -g oav 1. Compile Swagger into dependencies.json with Restler. ```bash -docker run --rm -v $(pwd)/specification:/swagger -w /swagger/.restler_output mcr.microsoft.com/restlerfuzzer/restler:v8.6.0 dotnet /RESTler/restler/Restler.dll compile --api_spec /swagger/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json +docker run --rm -v $(pwd)/specification:/swagger -w /swagger/.restler_output mcr.microsoft.com/restlerfuzzer/restler dotnet /RESTler/restler/Restler.dll compile --api_spec /swagger/appconfiguration/resource-manager/Microsoft.AppConfiguration/stable/2022-05-01/appconfiguration.json ``` 2. Generate a basic API Scenario file. diff --git a/documentation/api-scenario/readme.md b/documentation/api-scenario/readme.md index 5744871ee12a..c5bfcb1be874 100644 --- a/documentation/api-scenario/readme.md +++ b/documentation/api-scenario/readme.md @@ -24,7 +24,7 @@ API Scenario is a YAML file defining RESTful API usage scenarios of your service - [API Scenario Definition Reference](./references/ApiScenarioDefinition.md) - [API Scenario Variable Definition Reference](./references/Variables.md) - [API Scenario Runner Reference](./references/Runner.md) -- [API Scenario JSON Schema](./references/v1.1/schema.json) +- [API Scenario JSON Schema](./references/v1.2/schema.json) ## Feedback diff --git a/documentation/api-scenario/references/ApiScenarioDefinition.md b/documentation/api-scenario/references/ApiScenarioDefinition.md index 66d8fbc073a5..c31006f7f84a 100644 --- a/documentation/api-scenario/references/ApiScenarioDefinition.md +++ b/documentation/api-scenario/references/ApiScenarioDefinition.md @@ -81,7 +81,6 @@ It defines one API scenario that could go through on its own. ```yaml scenario: quickStart description: Quick start with AppConfiguration ConfigurationStores -shareScope: true steps: - step: Operations_CheckNameAvailability operationId: Operations_CheckNameAvailability @@ -101,13 +100,6 @@ variables: - **description** - **Type:** Optional, String - Description for this API scenario. -- **shareScope** - - **Type:** Optional, Boolean or String - - **Default:** true - - Describe how the scope (ResourceGroup if scope is ResourceGroup) could be shared with other scenarios. If true or the same string value for different API scenario, they share the same scope, which means: - - These API scenarios will run under the same scope (e.g. ResourceGroup). - - **prepareSteps** and **cleanUpSteps** will run only once in the scope. The variables will be shared. - - By default all the API scenario in one definition file will be launched in the same scope. If shareScope is false, the API scenarios will not share anything with others in the same file. - **variables** - **Type:** Optional, Map of Strings or Variables - See [Variables](./Variables.md) diff --git a/documentation/api-scenario/references/v1.2/schema.json b/documentation/api-scenario/references/v1.2/schema.json index b16aba41aa15..972f3f054d31 100644 --- a/documentation/api-scenario/references/v1.2/schema.json +++ b/documentation/api-scenario/references/v1.2/schema.json @@ -12,6 +12,9 @@ ], "default": "ResourceGroup" }, + "authentication": { + "$ref": "#/definitions/Authentication" + }, "variables": { "$ref": "#/definitions/Variables" }, @@ -47,6 +50,82 @@ "type": "string", "pattern": "^[A-Za-z_$][A-Za-z0-9_-]*$" }, + "Authentication": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "AADToken", + "AzureKey", + "None" + ], + "default": "AADToken" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "AADToken" + } + } + }, + "then": { + "properties": { + "type": {}, + "scope": { + "type": "string", + "description": "The resource identifier (application ID URI) of the resource you want, affixed with the .default suffix", + "examples": [ + "https://management.azure.com/.default", + "https://storage.azure.com/.default" + ] + } + }, + "required": [ + "scope" + ], + "additionalProperties": false + }, + "else": { + "if": { + "properties": { + "type": { + "const": "AzureKey" + } + } + }, + "then": { + "properties": { + "type": {}, + "key": { + "type": "string" + }, + "headerName": { + "type": "string", + "default": "Authorization" + } + }, + "required": [ + "key" + ], + "additionalProperties": false + }, + "else": { + "properties": { + "type": {} + }, + "additionalProperties": false + } + } + } + ] + }, "JsonPointer": { "type": "string", "description": "JSON Pointer described by RFC 6901, e.g. /foo/bar", @@ -274,14 +353,13 @@ "type": "string", "description": "A long description of the scenario" }, + "authentication": { + "$ref": "#/definitions/Authentication", + "description": "Authentication method to use for the scenario" + }, "variables": { "$ref": "#/definitions/Variables" }, - "shareScope": { - "type": "boolean", - "description": "Whether to share the scope and prepareSteps with other scenarios", - "default": true - }, "steps": { "type": "array", "items": { @@ -334,6 +412,9 @@ } ], "properties": { + "authentication": { + "$ref": "#/definitions/Authentication" + }, "outputVariables": { "type": "object", "propertyNames": { @@ -416,6 +497,7 @@ }, "step": {}, "description": {}, + "authentication": {}, "variables": {}, "outputVariables": {} }, @@ -436,6 +518,13 @@ "type": "string", "format": "uri-reference" }, + "operationId": { + "type": "string" + }, + "readmeTag": { + "type": "string", + "format": "uri-reference" + }, "requestUpdate": { "type": "array", "description": "Update request parameters", @@ -454,6 +543,7 @@ }, "step": {}, "description": {}, + "authentication": {}, "variables": {}, "outputVariables": {} }, diff --git a/documentation/ci-fix.md b/documentation/ci-fix.md index 263f3c5c2707..20b539546f0b 100644 --- a/documentation/ci-fix.md +++ b/documentation/ci-fix.md @@ -51,7 +51,7 @@ Refer to [Semantic and Model Violations Reference](https://github.com/Azure/azur ## Breaking Change Check - An API contract is identified by its api-version value. Once published, no changes to this API contract are allowed. This applies regardless of whether the API contract is for private preview, public preview, or GA (stable). - The same-version breaking change linter rules check for changes to an existing api-version swagger. -- When introducing a new API contract (preview or not), the new API contract must be backwards compatible with the previous GA’s API contract. +- When introducing a new API contract (preview or not), the new API contract must be backwards compatible with the previous GA’s API contract. - However, during a (private or public) preview cycle, a new preview API contract does not have to be backwards compatible with the previous preview API contract although it must still be backwards compatible with the latest GA API contract. - The cross version breaking change linter rules checks for this by comparing the new swagger with the latest GA swagger. If there is no latest GA swagger, then the latest preview if it > 1 year old. If nether a GA or preview > 1 year old exists, then the swagger is considered good. @@ -63,7 +63,7 @@ For the former, a label 'NewApiVersionRequired' will be added automatically; For run oad locally (the breaking change is reported by oad tool): ``` npm install -g @azure/oad -oad compare +oad compare ``` Please see [readme](https://github.com/Azure/openapi-diff/blob/main/README.md) for how to install or run tool in details. Or you can run it in [OpenAPI Hub](https://portal.azure-devex-tools.com/tools/diff). @@ -79,7 +79,7 @@ npm install -g autorest #### Given a swagger spec, run linter: ``` -autorest --validation --azure-validator --use=@microsoft.azure/classic-openapi-validator@latest --use=@microsoft.azure/openapi-validator@latest --input-file= +autorest --validation --azure-validator --use=@microsoft.azure/classic-openapi-validator@latest --use=@microsoft.azure/openapi-validator@latest --input-file= ``` #### Given a readme file, run linter: ``` @@ -111,7 +111,7 @@ Refer to [Avocado Readme](https://github.com/Azure/avocado/blob/master/README.md ## API Readiness Check -This CI check is to make sure service is ready before PR merge. Technically, the CI check send operationsList HTTP request to Azure Resource Provider. +This CI check is to make sure service is ready before PR merge. Technically, the CI check send operationsList HTTP request to Azure Resource Provider. To fix this CI check failure, if you haven't got ARM signed off, pls get ARM signed off first then deploy ARM manifest. After deploying ARM manifest, this operationsList HTTP request will succeed and CI pass. @@ -145,7 +145,7 @@ npm install -g autorest ``` #### Given a swagger spec, run the validator: ``` -autorest --v3 --azure-validator --use=@microsoft.azure/openapi-validator@latest --input-file= +autorest --v3 --azure-validator --use=@microsoft.azure/openapi-validator@latest --input-file= ``` #### Given a readme file, run the validator: ``` @@ -167,11 +167,11 @@ This validator is to ensure the cadl & swagger files in PR are consistent and th ## Traffic Validation -It generates traffics for all operations defined in swaggers under default tag of readme.md by using [RESTLer](https://github.com/microsoft/restler-fuzzer). Then it validates the request and response pairs from these traffics against correspondent swaggers. Finally, it provides a html report that reflects swagger accuracy. +This validator generates traffic for all operations defined in Swagger files under default tag of readme.md by using [RESTler](https://github.com/microsoft/restler-fuzzer). Then, it validates the request and response pairs from the traffic against the corresponding Swagger definitions. Finally, it provides an html report that reports the Swagger accuracy. ### How to understand and improve the report Please refer to [swagger-accuracy-report](./swagger-accuracy-report.md). ## Suppression Process -In case there are validation errors reported against your service that you believe do not apply, we have a suppression process you can follow to permanently remove these reported errors for your specs. Refer to [Swagger Suppression Process](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/85/Swagger-Suppression-Process) for detailed guidance. +In case there are validation errors reported against your service that you believe do not apply, we have a suppression process you can follow to permanently remove these reported errors for your specs. Refer to [Swagger Suppression Process](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/85/Swagger-Suppression-Process) for detailed guidance. diff --git a/documentation/images/check-in-restler-config.png b/documentation/images/check-in-restler-config.png new file mode 100644 index 000000000000..cec78a7f3343 Binary files /dev/null and b/documentation/images/check-in-restler-config.png differ diff --git a/documentation/images/traffic-validation-pipeline-artifacts.png b/documentation/images/traffic-validation-pipeline-artifacts.png new file mode 100644 index 000000000000..6964cb6b1637 Binary files /dev/null and b/documentation/images/traffic-validation-pipeline-artifacts.png differ diff --git a/documentation/images/traffic-validation-pipeline-comment.png b/documentation/images/traffic-validation-pipeline-comment.png new file mode 100644 index 000000000000..b8c014f9d577 Binary files /dev/null and b/documentation/images/traffic-validation-pipeline-comment.png differ diff --git a/documentation/swagger-accuracy-report.md b/documentation/swagger-accuracy-report.md index 7a60f70c11a4..7fecd8cb3c64 100644 --- a/documentation/swagger-accuracy-report.md +++ b/documentation/swagger-accuracy-report.md @@ -1,21 +1,98 @@ -# Swagger Accuracy Report -## What is this report about -[@Jeffrey to add details] +# Service Contract Accuracy Report -## How to improve report -There're two parts of the report need to be improved if it has content. -* First part is `Failed Operations` which includes the schema validation errors for listed operations, all the errors are supposed to be fixed. From the error code you could browse to the linked document about the error defintion and fix tips. -* Second part is `Untested Operations` which includes the operations which don't have the traffic generated by RESTler for validation. It could be because the dependent operations fails in validation in which case please fix failed operation firstly so that this untested operation will be unlocked automatically. +The purpose of the Service Contract (Swagger) Accuracy Report is to ensure that service contracts accuractly reflect true service behavior. It is critical that the contract be accurate because we use it to produce many assets such as documentation, SDKs (in many programming languages), and tools (Azure CLI & PowerShell). When the contract is incorrect, these assets are broken and fixing the contract later causes breaking changes and significant pain to all our customers. -## How to improve Untested Operations -All the traffics for each operation are generated by RESTler automatically, if the result says the operation is untested then you could try to modify RESTler config files to improve RESTler generation coverage. -[@Marina to add details on how to modify configs] +Our tooling ([RESTler](https://github.com/microsoft/restler-fuzzer) and [OAV](https://github.com/azure/oav)) that produces this report tests all service operations and compares the actual requests/responses against the contract for accuracy. -* Download and modify each RESTler config -[to add details] +--- -* Debug locally with updated RESTler configs -[to add details] +**IMPORTANT: _All operations must be tested and pass before the PR contract can be merged._** -* Check in updated RESTler configs to be used in swagger PR pipeline and re-run -[to add details] +--- + +For any `Failed Operations`, use the error information (and links provided) to either fix the contract or fix the service behavior. Fix failed operations first as this may enable our tooling to test some of the currently untested operations. + +For any `Untested Operations`, you must modify the RESTler configuration files to improve API coverage. + +## Steps to improve API coverage + +### 1. Download the RESTler configuration files + +In swagger PR pipeline, traffic validation pipeline will generate RESTler configuration files as artifacts. You could click the **pipeline artifact** to download the configuration files. + +![traffic-validation-pipeline-comment](./images/traffic-validation-pipeline-comment.png) + +Here is an example of the artifacts generated by the traffic validation pipeline: + +![traffic-validation-pipeline-artifacts](./images/traffic-validation-pipeline-artifacts.png) + +The red block in the above image is the generated RESTler configuration files and swaggerAccuracyReport. After downloading the configuration files, you could modify the configuration files and run RESTler locally to improve API coverage. + +### 1. Create an authentication script for RESTler + +RESTler needs a way to obtain authentication tokens to pass on service requests. +For services that use AAD authentication, you can get tokens from the Azure CLI. +The following bash script will obtain a token from the Azure CLI and print it in the format needed by RESTler. + +```sh +#!/bin/bash + +find . -name 'token.json' -depth 1 -mtime -1h | grep . &> /dev/null || az account get-access-token --scope > token.json + +token=$(jq -r '.accessToken' token.json) + +echo "{'user1':{}, 'user2':{}}" +echo "Authorization: bearer ${token}" +echo "Authorization: shadow_unit_test_token" +``` + +You can remove the `--scope` keyword from the `az account` command if the service does not require a specific scope. + +Save this script in a file on your machine and include `--token_refresh_command