Microsoft Azure DictionaryExamples API

openapi: 3.2.0
info:
  version: '3.0'
  title: Microsoft Azure Translator Text Client Dictionary Examples…
  termsOfService: http://www.microsoftvolumelicensing.com/DocumentSearch.aspx?Mode=3&DocumentTypeId=31
  contact:
    name: Microsoft Translator team
    email: translator@microsoft.com
    url: https://www.microsoft.com/translator
  description: '# Introduction


    The Microsoft Translator Text API provides a JSON-based Web API. It provides:


    * Translation between any supported languages to any other supported language. * Translation to multiple languages in one request. * Transliteration to convert text from one script to another script of the same language. * Language detection, translation, and transliteration in one request. * Dictionary to lookup alternative translations of a term, to find back-translations and examples showing terms used in context. * Rich language detection. # Base URLs


    The Translator Text API is available in the following clouds:


    | Description | Region | Base URL |

    | ------- | -------- | ------- |

    | Azure | Global | api.cognitive.microsofttranslator.com |

    | Azure | Europe | api-eur.cognitive.microsofttranslator.com |


    # Authentication


    Subscribe to the Translator Text API, part of Azure Cognitive Services, and use your subscription key from the Azure portal to authenticate. You can follow the steps in https://docs.microsoft.com/en-us/azure/cognitive-services/translator/translator-text-how-to-signup. The simplest way is to pass your Azure secret key to the Translator service using the http request header `Ocp-Apim-Subscription-Key`. If you prefer using a short-lived authentication, you may use your secret key to obtain an authorization token from the token service. In that case you pass the authorization token to the Translator service using the `Authorization` request header. To obtain an authorization token, make a `POST` request to the following URL:


    | Environment | Authentication service URL |

    | ---------- | ---------- |

    | Azure | `https://api.cognitive.microsoft.com/sts/v1.0/issueToken` |


    Here are example requests to obtain a token with a lifetime of 10 minutes, given a secret key:


    ```python

    // Pass secret key using header

    curl --header ''Ocp-Apim-Subscription-Key: '' --data "" ''https://api.cognitive.microsoft.com/sts/v1.0/issueToken''

    // Pass secret key using query string parameter

    curl --data "" ''https://api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=''

    ```


    A successful request returns the encoded access token as plain text in the response body. The valid token is passed to the Translator service as a bearer token in the Authorization. ```

    Authorization: Bearer

    ```


    An authentication token is valid for 10 minutes. The token should be re-used when making multiple calls to the Translator APIs. If you make requests to the Translator API over an extended period of time, you must request a new access token at regular intervals before the token expires, for instance every 9 minutes. To summarize, a client request to the Translator API will include one authorization header taken from the following table:


    | Headers | Description |

    | ---------- | ---------- |

    | Ocp-Apim-Subscription-key | Use with Cognitive Services subscription if you are passing your secret key. The value is the Azure secret key for your subscription to Translator Text API. |

    | Authorization | Use with Cognitive Services subscription if you are passing an authentication token. The value is the Bearer token: `Bearer `. |


    ## All-in-one subscription

    The last authentication option is to use a Cognitive Service’s all-in-one subscription. This allows you to use a single secret key to authenticate requests for multiple services. When you use an all-in-one secret key, you must include two authentication headers with your request. The first passes the secret key, the second specifies the region associated with your subscription. `Ocp-Api-Subscription-Key` `Ocp-Apim-Subscription-Region`

    If you pass the secret key in the query string with the parameter `Subscription-Key`, then you must specify the region with query parameter `Subscription-Region`. If you use a bearer token, you must obtain the token from the region endpoint:

    `https://.api.cognitive.microsoft.com/sts/v1.0/issueToken`.'
servers:
- url: https://api.cognitive.microsofttranslator.com
security:
- apim_key: []
- api_key_all_in_one: []
- api_region_all_in_one: []
tags:
- name: DictionaryExamples
paths:
  /Dictionary/Examples:
    post:
      description: Provides examples that show how terms in the dictionary are used in context. This operation is used in tandem with `Dictionary lookup`.
      tags:
      - DictionaryExamples
      operationId: microsoftAzureTranslatorDictionaryexamples
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - name: from
        description: Specifies the language of the input text. The source language must be one of the supported languages included in the `dictionary` scope.
        in: query
        required: true
        schema:
          type: string
      - name: to
        description: Specifies the language of the output text. The target language must be one of the supported languages included in the `dictionary` scope.
        in: query
        required: true
        schema:
          type: string
      - name: X-ClientTraceId
        description: A client-generated GUID to uniquely identify the request. Note that you can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.
        in: header
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DictionaryExampleResult'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      x-ms-examples:
        DictionaryExample success example:
          $ref: ./examples/dictionaryExampleSuccess.json
      deprecated: false
      summary: Microsoft Azure Post Dictionary Examples
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DictionaryExampleTextInput'
        description: "# Request body\nThe body of the request is a JSON array. Each array element is a JSON object with the following properties:\n* `Text-` A string specifying the term to lookup. This should be the value of a `normalizedText` field from the back-translations of a previous Dictionary lookup request. It can also be the value of the `normalizedSource` field.\n* `Translation-` A string specifying the translated text previously returned by the Dictionary lookup operation. This should be the value from the `normalizedTarget` field in the `translations` list of the Dictionary lookup response. The service will return examples for the specific source-target word-pair.\n\nThe following limitations apply:\n* The array can have at most 10 elements.\n* The text value of an array element cannot exceed 100 characters including spaces.\n\n# Response body\nA successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:\n* `normalizedSource-` A string giving the normalized form of the source term. Generally, this should be identical to the value of the `Text` field at the matching list index in the body of the request.\n* `normalizedTarget-` A string giving the normalized form of the target term. Generally, this should be identical to the value of the `Translation` field at the matching list index in the body of the request.\n* `examples-` A list of examples for the (source term, target term) pair. Each element of the list is an object with the following properties:\n  * `sourcePrefix-` The string to concatenate before the value of `sourceTerm` to form a complete example. Do not add a space character, since it is already there when it should be. This value may be an empty string.\n  * `sourceTerm-` A string equal to the actual term looked up. The string is added with `sourcePrefix` and `sourceSuffix` to form the complete example. Its value is separated so it can be marked in a user interface, e.g., by bolding it.\n  * `sourceSuffix-` The string to concatenate after the value of `sourceTerm` to form a complete example. Do not add a space character, since it is already there when it should be. This value may be an empty string.\n  * `targetPrefix-` A string similar to `sourcePrefix` but for the target.\n  * `targetTerm-` A string similar to `sourceTerm` but for the target.\n  * `targetSuffix-` A string similar to `sourceSuffix` but for the target.\n\n# Response Header\nX-RequestId - Value generated by the service to identify the request. It is used for troubleshooting purposes.\nNOTE - If there are no examples in the dictionary, the response is 200 (OK) but the `examples` list is an empty list.\n"
        required: true
components:
  schemas:
    ErrorMessage:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    DictionaryExampleTextInput:
      type: object
      description: 'Text needed for a dictionary example request '
      properties:
        text:
          type: string
          maximum: 100
        translation:
          type: string
      example:
        text: bug
        translation: bicho
    DictionaryExampleResult:
      type: array
      description: Example of a successful dictionary example request
      items:
        type: object
        properties:
          normalizedSource:
            type: string
          normalizedTarget:
            type: string
          examples:
            type: array
            items:
              type: object
              properties:
                sourcePrefix:
                  type: string
                sourceTerm:
                  type: string
                sourceSuffix:
                  type: string
                targetPrefix:
                  type: string
                targetTerm:
                  type: string
                targetSuffix:
                  type: string
  parameters:
    ApiVersion:
      name: api-version
      description: Version of the API requested by the client. Value must be **3.0**.
      in: query
      required: true
      schema:
        type: string
        default: '3.0'
  securitySchemes:
    apim_key:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    api_key_all_in_one:
      type: apiKey
      name: Ocp-Apim-Subscription-Key
      in: header
    api_region_all_in_one:
      type: apiKey
      name: Ocp-Apim-Subscription-Region
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'