다음을 통해 공유


Translator 3.0: 사전 조회

하나의 단어와 소수의 관용구에 대한 대체 번역을 제공합니다. 각 번역에는 음성 부분과 백 번역 목록이 있습니다. 백 번역을 사용하면 사용자가 컨텍스트에서 번역을 이해할 수 있습니다. 사전 예제 작업에는 각 번역 쌍의 예제 사용이 포함됩니다.

요청 URL

다음에 POST 요청을 보냅니다.

https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0

Translator 서비스가 선택한 네트워크와 프라이빗 엔드포인트 구성 및 지원에 대해서는 Virtual Network 지원참조하세요.

요청 매개 변수

쿼리 문자열에 전달된 요청 매개 변수는 다음과 같습니다.

쿼리 매개 변수 설명
api-version 필수 매개 변수입니다.
클라이언트에서 요청한 API 버전입니다. 값은 3.0여야 합니다.
보낸 사람 필수 매개 변수입니다.
입력 텍스트의 언어를 지정합니다. 원본 언어는 dictionary 범위에 포함된 지원되는 언어 중 하나여야 합니다.
필수 매개 변수입니다.
출력 텍스트의 언어를 지정합니다. 대상 언어는 dictionary 범위에 포함된 지원되는 언어 중 하나여야 합니다.

요청 헤더에는 다음이 포함됩니다.

헤더 설명
인증 헤더 필요한 요청 헤더입니다.
인증을 참조하세요.
Content-Type 필요한 요청 헤더입니다.
페이로드의 콘텐츠 형식을 지정합니다. 가능한 값은 application/json입니다.
Content-Length 선택 사항.
요청 본문의 길이입니다.
X-ClientTraceId 선택 사항.
요청을 고유하게 식별하는 클라이언트 생성 ID입니다. 쿼리 매개 변수를 ClientTraceId사용하여 쿼리 문자열에 추적 ID를 포함하는 경우 이 헤더를 생략할 수 있습니다.

요청 본문

요청 본문은 JSON 배열입니다. 각 배열 요소는 조회할 용어를 나타내는 Text라는 문자열 속성이 포함된 JSON 개체입니다.

[
    {"Text":"fly"}
]

다음과 같은 제한 사항이 적용됩니다.

  • 배열에는 최대 10개 요소가 있을 수 있습니다.
  • 배열 요소의 텍스트 값은 공백을 포함하여 100자를 초과할 수 없습니다.

응답 본문

성공적인 응답은 입력 배열의 각 문자열에 대해 하나의 결과가 있는 JSON 배열입니다. 결과 개체에는 다음 속성이 포함됩니다.

  • normalizedSource: 소스 용어의 정규화된 형식을 제공하는 문자열입니다. 예를 들어 요청이 JOHN인 경우 정규화된 형식은 john이 됩니다. 이 필드의 콘텐츠는 조회 예제의 입력이 됩니다.

  • displaySource: 최종 사용자 표시에 가장 적합한 형식으로 제공되는 원본 용어를 제공하는 문자열입니다. 예를 들어 입력이 JOHN이면 표시 형식에는 이 이름의 일반적인 철자인 John이 반영됩니다.

  • translations: 원본 용어에 대한 번역 목록입니다. 목록의 각 요소는 다음 속성을 가진 개체입니다.

  • normalizedTarget: 대상 언어로 이 용어의 정규화된 형식을 제공하는 문자열입니다. 이 값은 조회 예제에 대한 입력으로 사용해야 합니다.

  • displayTarget: 대상 언어 및 최종 사용자 표시에 가장 적합한 형식으로 용어를 제공하는 문자열입니다. 일반적으로 이 속성은 normalizedTarget과 대/소문자만 차이를 보입니다. 예를 들어 Juan과 같은 고유 명사는 normalizedTarget = "juan"displayTarget = "Juan"이 지정됩니다.

  • posTag: 이 용어를 음성 부분 태그에 연결하는 문자열입니다.

    태그 이름 설명
    ADJ 형용사
    ADV 부사
    CONJ 접속사
    DET 결정자
    MODAL 동사
    NOUN 명사
    PREP 전치사
    PRON 대명사
    VERB 동사
    OTHER 기타

    영어 쪽에 음성 부분 태그를 지정한 후 각 원본/대상 쌍에 대해 가장 자주 나오는 태그가 선택되는 방식으로 구현되었습니다. 따라서 사람들이 스페인어 단어를 영어로 다른 음성 부분 태그로 자주 번역하는 경우 태그 택시가 잘못됩니다(스페인어 단어와 관련하여).

  • confidence: 번역 쌍의 “신뢰도”(또는 좀 더 정확히 나타내자면 “학습 데이터의 확률”)를 나타내는 0.0과 1.0 사이의 값입니다. 하나의 원본 단어에 대한 신뢰도 점수의 합계는 1.0으로 합산할 수 있거나 합할 수 없습니다.

  • prefixWord: 번역의 접두사로 표시할 단어를 제공하는 문자열입니다. 현재 이 속성은 성별 결정자가 있는 언어에서 명사에 대한 성별 결정자입니다. 예를 들어, 스페인어 단어 mosca는 스페인어에서 여성 명사이므로 mosca의 접두사는 la가 됩니다. 이 값은 원본이 아닌 번역에만 종속됩니다. 접두사가 없는 경우 빈 문자열입니다.

  • backTranslations: 대상의 "뒤로 번역" 목록입니다. 예를 들어 대상이 번역할 수 있는 소스 단어입니다. 목록에 요청된 원본 단어가 포함되도록 보장됩니다(예: 조회 flyfly 중인 원본 단어가 있는 경우 목록에 포함 backTranslations 됨). 그러나 첫 번째 위치에 표시될 것으로 보장할 수는 없으며 그렇지 않은 경우가 많습니다. backTranslations 목록의 각 요소는 다음과 같은 속성으로 설명되는 개체입니다.

    • normalizedText: 대상의 역 변환인 소스 용어의 정규화된 형식을 제공하는 문자열입니다. 이 값은 조회 예제에 대한 입력으로 사용해야 합니다.

    • displayText: 최종 사용자 표시에 가장 적합한 형식으로 대상의 역 변환인 소스 용어를 제공하는 문자열입니다.

    • numExamples: 이 번역 쌍에 대해 사용할 수 있는 예제 수를 나타내는 정수입니다. 실제 예제는 조회 예제에 대한 별도의 호출을 사용하여 검색해야 합니다. 이 숫자는 주로 UX에서 쉽게 표시하기 위한 것입니다. 예를 들어 예제 수가 0보다 큰 경우 사용자 인터페이스가 백 번역에 하이퍼링크를 추가할 수 있습니다. 예제가 없는 경우 역번역을 일반 텍스트로 표시합니다. 조회 예제 호출에서 반환된 실제 예제 수는 "잘못된" 예제를 제거하기 위해 더 많은 필터링을 즉석에서 적용할 수 있으므로 보다 numExamples적을 수 있습니다.

    • frequencyCount: 데이터에서 이 변환 쌍의 빈도를 나타내는 정수입니다. 이 필드의 주요 목적은 가장 빈번한 용어가 먼저 표시되도록 백 번역을 정렬하는 수단을 사용자 인터페이스에 제공하는 것입니다.

      참고 항목

      조회 중인 용어가 사전에 없는 경우 응답은 200(확인)이지만 translations 목록은 빈 목록입니다.

예제

이 예제에서는 영어 용어인 fly의 스페인어 대체 번역을 조회하는 방법을 보여 줍니다.

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0&from=en&to=es" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly'}]"

응답 본문은 다음과 같습니다(명확히 나타내기 위해 축약됨).

[
    {
        "normalizedSource":"fly",
        "displaySource":"fly",
        "translations":[
            {
                "normalizedTarget":"volar",
                "displayTarget":"volar",
                "posTag":"VERB",
                "confidence":0.4081,
                "prefixWord":"",
                "backTranslations":[
                    {"normalizedText":"fly","displayText":"fly","numExamples":15,"frequencyCount":4637},
                    {"normalizedText":"flying","displayText":"flying","numExamples":15,"frequencyCount":1365},
                    {"normalizedText":"blow","displayText":"blow","numExamples":15,"frequencyCount":503},
                    {"normalizedText":"flight","displayText":"flight","numExamples":15,"frequencyCount":135}
                ]
            },
            {
                "normalizedTarget":"mosca",
                "displayTarget":"mosca",
                "posTag":"NOUN",
                "confidence":0.2668,
                "prefixWord":"",
                "backTranslations":[
                    {"normalizedText":"fly","displayText":"fly","numExamples":15,"frequencyCount":1697},
                    {"normalizedText":"flyweight","displayText":"flyweight","numExamples":0,"frequencyCount":48},
                    {"normalizedText":"flies","displayText":"flies","numExamples":9,"frequencyCount":34}
                ]
            },
            //
            // ...list abbreviated for documentation clarity
            //
        ]
    }
]

이 예제는 조회되는 용어가 유효한 사전 쌍에 없을 때 나타나는 결과를 보여 줍니다.

curl -X POST "https://api.cognitive.microsofttranslator.com/dictionary/lookup?api-version=3.0&from=en&to=es" -H "X-ClientTraceId: 875030C7-5380-40B8-8A03-63DACCF69C11" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'fly123456'}]"

이 용어는 사전에서 찾을 수 없으므로 응답 본문에 빈 translations 목록이 포함됩니다.

[
    {
        "normalizedSource":"fly123456",
        "displaySource":"fly123456",
        "translations":[]
    }
]