Microsoft Azure :Analyze Text API

openapi: 3.2.0
info:
  title: Microsoft Azure Microsoft Cognitive Language Service - Text…
  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: 2023-04-15-preview
security:
- AADToken:
  - https://cognitiveservices.azure.com/.default
- apim_key: []
tags:
- name: :Analyze Text
paths:
  /:analyze-text:
    post:
      summary: Microsoft Azure Request Text Analysis Over A Collection Of Documents
      description: Submit a collection of text documents for analysis. Specify a single unique task to be executed immediately.
      operationId: microsoftAzureAnalyzetext
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: common.json#/parameters/ShowStats
      responses:
        '200':
          description: A successful call result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeTextTaskResult'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Entity Linking Request:
          $ref: ./examples/text/SuccessfulEntityLinkingRequest.json
        Successful Entity Recognition Request:
          $ref: ./examples/text/SuccessfulEntityRecognitionRequest.json
        Successful Entity Recognition Inclusion Request:
          $ref: ./examples/text/SuccessfulEntityRecognitionInclusionRequest.json
        Successful Entity Recognition Exclusion Request:
          $ref: ./examples/text/SuccessfulEntityRecognitionExclusionRequest.json
        Successful Entity Recognition Overlap Policy Request:
          $ref: ./examples/text/SuccessfulEntityRecognitionOverlapPolicy.json
        Successful Key Phrase Extraction Request:
          $ref: ./examples/text/SuccessfulKeyPhraseExtractionRequest.json
        Successful PII Entity Recognition Request:
          $ref: ./examples/text/SuccessfulPiiEntityRecognitionRequest.json
        Successful PII Entity Recognition Redaction Request:
          $ref: ./examples/text/SuccessfulPiiEntityRecognitionRedactionRequest.json
        Successful PII Entity Recognition Exclusion Request:
          $ref: ./examples/text/SuccessfulPiiEntityRecognitionExclusionRequest.json
        Successful Language Detection Request:
          $ref: ./examples/text/SuccessfulLanguageDetectionRequest.json
        Successful Sentiment Analysis Request:
          $ref: ./examples/text/SuccessfulSentimentAnalysisRequest.json
        Successful Dynamic Classification Request:
          $ref: ./examples/text/SuccessfuDynamicClassificationRequest.json
      tags:
      - :Analyze Text
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeTextTask'
        description: Collection of documents to analyze and a single task to execute.
        required: true
  /analyze-text/jobs:
    post:
      description: Submit a collection of text documents for analysis. Specify one or more unique tasks to be executed as a long-running operation.
      operationId: microsoftAzureAnalyzetextSubmitjob
      summary: Microsoft Azure Submit Text Analysis Job
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '202':
          description: A successful call results with an Operation-Location header used to check the status of the analysis job.
          headers:
            Operation-Location:
              schema:
                type: string
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Submit Analysis Job Request:
          $ref: ./examples/text/SuccessfulAnalyzeTextJobsMultipleTaskSubmitRequest.json
        Successful Healthcare Post Request:
          $ref: ./examples/text/SuccessfulHealthcarePostRequest.json
        Successful Custom Healthcare Post Request:
          $ref: ./examples/text/SuccessfulCustomHealthcarePostRequest.json
        Successful Submit Abstractive Summarization Task:
          $ref: ./examples/text/SuccessfulAbstractiveSummarizationTaskSubmit.json
        Successful Submit Custom Abstractive Summarization Task:
          $ref: ./examples/text/SuccessfulCustomAbstractiveSummarizationTaskSubmit.json
        Successful Healthcare DocumentType Post Request:
          $ref: ./examples/text/SuccessfulHealthcareDocumentTypePostRequest.json
        Successful Custom Sentiment Analysis Post Request:
          $ref: ./examples/text/SuccessfulCustomSentimentAnalysisTaskSubmit.json
      x-ms-long-running-operation: true
      tags:
      - :Analyze Text
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeTextJobsInput'
        description: Collection of documents to analyze and one or more tasks to execute.
        required: true
  /analyze-text/jobs/{jobId}:
    get:
      description: Get the status of an analysis job. A job may consist of one or more tasks. Once all tasks are succeeded, the job will transition to the succeeded state and results will be available for each task.
      operationId: microsoftAzureAnalyzetextJobstatus
      summary: Microsoft Azure Get Analysis Status And Results
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: common.json#/parameters/JobId
      - $ref: common.json#/parameters/ShowStats
      - $ref: common.json#/parameters/TopParameter
      - $ref: common.json#/parameters/SkipParameter
      responses:
        '200':
          description: Analysis job status and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeTextJobState'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Get Text Analysis Job Status Request:
          $ref: ./examples/text/SuccessfulAnalyzeTextJobsMultipleTaskStatusRequest.json
        Successful Get Text Analysis Health Request:
          $ref: ./examples/text/SuccessfulHealthcareTaskStatusRequest.json
        Successful Get Text Analysis Custom Health Request:
          $ref: ./examples/text/SuccessfulCustomHealthcareTaskStatusRequest.json
        Successful Get Abstractive Summarization Result:
          $ref: ./examples/text/SuccessfulAbstractiveSummarizationTaskResult.json
        Successful Get Custom Abstractive Summarization Result:
          $ref: ./examples/text/SuccessfulCustomAbstractiveSummarizationTaskResult.json
        Successful Get Text Analysis Health DocumentType Request:
          $ref: ./examples/text/SuccessfulHealthcareDocumentTypeTaskStatusRequest.json
        Successful Get Text Analysis Custom Sentiment Analysis Request:
          $ref: ./examples/text/SuccessfulCustomSentimentAnalysisTaskStatusRequest.json
      tags:
      - :Analyze Text
  /analyze-text/jobs/{jobId}:cancel:
    post:
      description: Cancel a long-running Text Analysis job.
      operationId: microsoftAzureAnalyzetextCanceljob
      summary: Microsoft Azure Cancel A Long Running Text Analysis Job
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: common.json#/parameters/JobId
      responses:
        '202':
          description: Cancel Job request has been received.
          headers:
            Operation-Location:
              schema:
                type: string
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Job Delete Request:
          $ref: ./examples/text/SuccessfulAnalyzeTextJobsCancelRequest.json
      x-ms-long-running-operation: true
      tags:
      - :Analyze Text
components:
  schemas:
    AnalyzeTextTaskResultsKind:
      type: string
      description: Enumeration of supported Text Analysis task results.
      enum:
      - SentimentAnalysisResults
      - EntityRecognitionResults
      - PiiEntityRecognitionResults
      - KeyPhraseExtractionResults
      - LanguageDetectionResults
      - EntityLinkingResults
      - DynamicClassificationResults
      x-ms-enum:
        name: AnalyzeTextTaskResultsKind
        modelAsString: true
    AnalyzeTextTask:
      type: object
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeTextTaskKind'
    AnalyzeTextTaskKind:
      type: string
      description: Enumeration of supported Text Analysis tasks.
      enum:
      - SentimentAnalysis
      - EntityRecognition
      - PiiEntityRecognition
      - KeyPhraseExtraction
      - LanguageDetection
      - EntityLinking
      - DynamicClassification
      x-ms-enum:
        name: AnalyzeTextTaskKind
        modelAsString: true
    AnalyzeTextTaskResult:
      type: object
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeTextTaskResultsKind'
    AnalyzeTextLROResultsKind:
      type: string
      description: Enumeration of supported Text Analysis long-running operation task results.
      enum:
      - SentimentAnalysisLROResults
      - EntityRecognitionLROResults
      - PiiEntityRecognitionLROResults
      - KeyPhraseExtractionLROResults
      - EntityLinkingLROResults
      - HealthcareLROResults
      - CustomHealthcareLROResults
      - ExtractiveSummarizationLROResults
      - CustomEntityRecognitionLROResults
      - CustomSingleLabelClassificationLROResults
      - CustomMultiLabelClassificationLROResults
      - AbstractiveSummarizationLROResults
      - CustomSentimentAnalysisLROResults
      - CustomAbstractiveSummarizationLROResults
      x-ms-enum:
        name: AnalyzeTextLROResultsKind
        modelAsString: true
    AnalyzeTextLROTask:
      type: object
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeTextLROTaskKind'
      allOf:
      - $ref: common.json#/definitions/TaskIdentifier
    AnalyzeTextJobsInput:
      type: object
      properties:
        displayName:
          description: Optional display name for the analysis job.
          type: string
        defaultLanguage:
          description: Default language to use for records requesting automatic language detection.
          type: string
        analysisInput:
          $ref: '#/components/schemas/MultiLanguageAnalysisInput'
        tasks:
          description: The set of tasks to execute on the input documents.
          type: array
          items:
            $ref: '#/components/schemas/AnalyzeTextLROTask'
      required:
      - analysisInput
      - tasks
    TasksState:
      properties:
        tasks:
          properties:
            completed:
              type: integer
              format: int64
            failed:
              type: integer
              format: int64
            inProgress:
              type: integer
              format: int64
            total:
              type: integer
              format: int64
            items:
              type: array
              items:
                $ref: '#/components/schemas/AnalyzeTextLROResult'
          required:
          - total
          - completed
          - failed
          - inProgress
          type: object
      required:
      - tasks
      type: object
    AnalyzeTextLROTaskKind:
      type: string
      description: Enumeration of supported long-running Text Analysis tasks.
      enum:
      - SentimentAnalysis
      - EntityRecognition
      - PiiEntityRecognition
      - KeyPhraseExtraction
      - EntityLinking
      - Healthcare
      - CustomHealthcare
      - ExtractiveSummarization
      - CustomEntityRecognition
      - CustomSingleLabelClassification
      - CustomMultiLabelClassification
      - AbstractiveSummarization
      - CustomSentimentAnalysis
      - CustomAbstractiveSummarization
      x-ms-enum:
        name: AnalyzeTextLROTaskKind
        modelAsString: true
    MultiLanguageInput:
      type: object
      description: Contains an input document to be analyzed by the service.
      required:
      - id
      - text
      properties:
        id:
          type: string
          description: A unique, non-empty document identifier.
        text:
          type: string
          description: The input text to process.
        language:
          type: string
          description: (Optional) This is the 2 letter ISO 639-1 representation of a language. For example, use "en" for English; "es" for Spanish etc. For Auto Language Detection, use "auto". If not set, use "en" for English as default.
    AnalyzeTextJobState:
      allOf:
      - $ref: common.json#/definitions/JobState
      - $ref: '#/components/schemas/TasksState'
      - $ref: '#/components/schemas/AnalyzeTextJobStatistics'
    MultiLanguageAnalysisInput:
      type: object
      properties:
        documents:
          type: array
          items:
            $ref: '#/components/schemas/MultiLanguageInput'
    AnalyzeTextLROResult:
      type: object
      discriminator:
        propertyName: kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeTextLROResultsKind'
      allOf:
      - $ref: '#/components/schemas/TaskState'
      - $ref: common.json#/definitions/TaskIdentifier
      required:
      - kind
    TaskState:
      properties:
        lastUpdateDateTime:
          format: date-time
          type: string
        status:
          type: string
          enum:
          - notStarted
          - running
          - succeeded
          - failed
          - cancelled
          - cancelling
          x-ms-enum:
            modelAsString: true
            name: State
      required:
      - status
      - lastUpdateDateTime
      type: object
    AnalyzeTextJobStatistics:
      properties:
        statistics:
          $ref: common.json#/definitions/RequestStatistics
      type: object
  securitySchemes:
    AADToken:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://cognitiveservices.azure.com/.default: https://cognitiveservices.azure.com/.default
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      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."
    apim_key:
      type: apiKey
      description: A subscription key for a Language service resource.
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/language'
  useSchemePrefix: false
  parameters:
  - $ref: common.json#/parameters/Endpoint