Microsoft Azure Sentiment API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Sentiment API
tags:
- name: Sentiment
paths:
  /sentiment:
    post:
      summary: Microsoft Azure Sentiment
      description: The API returns a detailed sentiment analysis for the input text. The analysis is done in multiple levels of granularity, start from the a document level, down to sentence and key terms (targets and assessments).
      operationId: microsoftAzureSentiment
      parameters:
      - $ref: '#/components/parameters/ModelVersion'
      - $ref: '#/components/parameters/ShowStats'
      - name: opinionMining
        in: query
        description: (Optional) if set to true, response will contain not only sentiment prediction but also opinion mining (aspect-based sentiment analysis) results.
        schema:
          type: boolean
      - $ref: '#/components/parameters/StringIndexType'
      - $ref: '#/components/parameters/MultiLanguageInput'
      responses:
        '200':
          description: A successful call results in a document sentiment prediction, as well as sentiment scores for each sentiment class (Positive, Negative, and Neutral)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SentimentResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/SentimentResponse'
        '400':
          description: Bad Request.
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal error response
          x-ms-error-response: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-ms-examples:
        Successful Sentiment request:
          $ref: .//examples//SuccessfulSentimentRequest.json
      deprecated: false
      tags:
      - Sentiment
components:
  schemas:
    TextAnalyticsError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - InvalidRequest
          - InvalidArgument
          - InternalServerError
          - ServiceUnavailable
          - NotFound
          x-ms-enum:
            name: ErrorCodeValue
            modelAsString: false
          description: Error code.
        message:
          type: string
          description: Error message.
        target:
          type: string
          description: Error target.
        innererror:
          $ref: '#/components/schemas/InnerError'
          description: Inner error contains more specific information.
        details:
          type: array
          description: Details about specific errors that led to this reported error.
          items:
            $ref: '#/components/schemas/TextAnalyticsError'
    SentenceAssessment:
      type: object
      required:
      - confidenceScores
      - isNegated
      - length
      - offset
      - sentiment
      - text
      properties:
        sentiment:
          type: string
          enum:
          - positive
          - mixed
          - negative
          x-ms-enum:
            name: TokenSentimentValue
            modelAsString: false
          description: Assessment sentiment in the sentence.
        confidenceScores:
          description: Assessment sentiment confidence scores in the sentence.
          $ref: '#/components/schemas/TargetConfidenceScoreLabel'
        offset:
          type: integer
          format: int32
          description: The assessment offset from the start of the sentence.
        length:
          type: integer
          format: int32
          description: The length of the assessment.
        text:
          type: string
          description: The assessment text detected.
        isNegated:
          type: boolean
          description: The indicator representing if the assessment is negated.
    TargetConfidenceScoreLabel:
      type: object
      required:
      - negative
      - positive
      properties:
        positive:
          type: number
          format: double
        negative:
          type: number
          format: double
      description: 'Represents the confidence scores across all sentiment classes: positive, neutral, negative.'
    InnerError:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - InvalidParameterValue
          - InvalidRequestBodyFormat
          - EmptyRequest
          - MissingInputRecords
          - InvalidDocument
          - ModelVersionIncorrect
          - InvalidDocumentBatch
          - UnsupportedLanguageCode
          - InvalidCountryHint
          x-ms-enum:
            name: InnerErrorCodeValue
            modelAsString: true
          description: Error code.
        message:
          type: string
          description: Error message.
        details:
          type: object
          additionalProperties:
            type: string
          description: Error details.
        target:
          type: string
          description: Error target.
        innererror:
          $ref: '#/components/schemas/InnerError'
          description: Inner error contains more specific information.
    DocumentError:
      type: object
      required:
      - id
      - error
      properties:
        id:
          type: string
          description: Document Id.
        error:
          type: object
          description: Document Error.
          $ref: '#/components/schemas/TextAnalyticsError'
    TextAnalyticsWarning:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - LongWordsInDocument
          - DocumentTruncated
          x-ms-enum:
            name: WarningCodeValue
            modelAsString: true
          description: Error code.
        message:
          type: string
          description: Warning message.
        targetRef:
          type: string
          description: A JSON pointer reference indicating the target object.
    SentimentConfidenceScorePerLabel:
      type: object
      required:
      - positive
      - neutral
      - negative
      properties:
        positive:
          type: number
          format: double
        neutral:
          type: number
          format: double
        negative:
          type: number
          format: double
      description: 'Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative.'
    MultiLanguageInput:
      type: object
      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. If not set, use "en" for English as default.
      description: Contains an input document to be analyzed by the service.
    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
          description: Number of transactions for the request.
      description: if showStats=true was specified in the request this field will contain information about the request payload.
    MultiLanguageBatchInput:
      type: object
      required:
      - documents
      properties:
        documents:
          type: array
          description: The set of documents to process as part of this batch.
          items:
            $ref: '#/components/schemas/MultiLanguageInput'
      description: Contains a set of input documents to be analyzed by the service.
    DocumentSentiment:
      type: object
      required:
      - id
      - sentiment
      - confidenceScores
      - sentences
      - warnings
      properties:
        id:
          type: string
          description: Unique, non-empty document identifier.
        sentiment:
          type: string
          description: Predicted sentiment for document (Negative, Neutral, Positive, or Mixed).
          enum:
          - positive
          - neutral
          - negative
          - mixed
          x-ms-enum:
            name: DocumentSentimentValue
            modelAsString: false
        statistics:
          $ref: '#/components/schemas/DocumentStatistics'
        confidenceScores:
          description: Document level sentiment confidence scores between 0 and 1 for each sentiment class.
          $ref: '#/components/schemas/SentimentConfidenceScorePerLabel'
        sentences:
          type: array
          description: Sentence level sentiment analysis.
          items:
            $ref: '#/components/schemas/SentenceSentiment'
        warnings:
          type: array
          description: Warnings encountered while processing document.
          items:
            $ref: '#/components/schemas/TextAnalyticsWarning'
    SentenceTarget:
      type: object
      required:
      - confidenceScores
      - length
      - offset
      - relations
      - sentiment
      - text
      properties:
        sentiment:
          type: string
          enum:
          - positive
          - mixed
          - negative
          x-ms-enum:
            name: TokenSentimentValue
            modelAsString: false
          description: Targeted sentiment in the sentence.
        confidenceScores:
          description: Target sentiment confidence scores for the target in the sentence.
          $ref: '#/components/schemas/TargetConfidenceScoreLabel'
        offset:
          type: integer
          format: int32
          description: The target offset from the start of the sentence.
        length:
          type: integer
          format: int32
          description: The length of the target.
        text:
          type: string
          description: The target text detected.
        relations:
          type: array
          description: The array of either assessment or target objects which is related to the target.
          items:
            $ref: '#/components/schemas/TargetRelation'
    DocumentStatistics:
      type: object
      required:
      - charactersCount
      - transactionsCount
      properties:
        charactersCount:
          type: integer
          format: int32
          description: Number of text elements recognized in the document.
        transactionsCount:
          type: integer
          format: int32
          description: Number of transactions for the document.
      description: if showStats=true was specified in the request this field will contain information about the document payload.
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          description: Document Error.
          $ref: '#/components/schemas/TextAnalyticsError'
    TargetRelation:
      type: object
      required:
      - ref
      - relationType
      properties:
        relationType:
          type: string
          enum:
          - assessment
          - target
          x-ms-enum:
            name: TargetRelationType
            modelAsString: false
          description: The type related to the target.
        ref:
          type: string
          description: The JSON pointer indicating the linked object.
    SentenceSentiment:
      type: object
      required:
      - text
      - sentiment
      - confidenceScores
      - offset
      - length
      properties:
        text:
          type: string
          description: The sentence text.
        sentiment:
          type: string
          description: The predicted Sentiment for the sentence.
          enum:
          - positive
          - neutral
          - negative
          x-ms-enum:
            name: SentenceSentimentValue
            modelAsString: false
        confidenceScores:
          description: The sentiment confidence score between 0 and 1 for the sentence for all classes.
          $ref: '#/components/schemas/SentimentConfidenceScorePerLabel'
        offset:
          type: integer
          format: int32
          description: The sentence offset from the start of the document.
        length:
          type: integer
          format: int32
          description: The length of the sentence.
        targets:
          type: array
          description: The array of sentence targets for the sentence.
          items:
            $ref: '#/components/schemas/SentenceTarget'
        assessments:
          type: array
          description: The array of assessments for the sentence.
          items:
            $ref: '#/components/schemas/SentenceAssessment'
    SentimentResponse:
      type: object
      required:
      - documents
      - errors
      - modelVersion
      properties:
        documents:
          type: array
          description: Sentiment analysis per document.
          items:
            $ref: '#/components/schemas/DocumentSentiment'
        errors:
          type: array
          description: Errors by document id.
          items:
            $ref: '#/components/schemas/DocumentError'
        statistics:
          $ref: '#/components/schemas/RequestStatistics'
        modelVersion:
          type: string
          description: This field indicates which model is used for scoring.
  parameters:
    StringIndexType:
      name: stringIndexType
      in: query
      description: (Optional) Specifies the method used to interpret string offsets.  Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets
      x-ms-enum:
        name: StringIndexType
        modelAsString: true
        values:
        - value: TextElements_v8
          description: Returned offset and length values will correspond to TextElements (Graphemes and Grapheme clusters) confirming to the Unicode 8.0.0 standard. Use this option if your application is written in .Net Framework or .Net Core and you will be using StringInfo.
        - value: UnicodeCodePoint
          description: Returned offset and length values will correspond to Unicode code points. Use this option if your application is written in a language that support Unicode, for example Python.
        - value: Utf16CodeUnit
          description: Returned offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript.
      x-ms-parameter-location: method
      schema:
        type: string
        enum:
        - TextElements_v8
        - UnicodeCodePoint
        - Utf16CodeUnit
        default: TextElements_v8
    MultiLanguageInput:
      in: body
      name: input
      description: Collection of documents to analyze.
      required: true
      schema:
        $ref: '#/components/schemas/MultiLanguageBatchInput'
      x-ms-parameter-location: method
    ModelVersion:
      name: model-version
      in: query
      description: '(Optional) This value indicates which model will be used for scoring. If a model-version is not specified, the API should default to the latest, non-preview version. '
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    ShowStats:
      name: showStats
      in: query
      description: (Optional) if set to true, response will contain request and document level statistics.
      required: false
      x-ms-parameter-location: method
      schema:
        type: boolean
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'