次の方法で共有


Translator v3.0

最近のニュースは何ですか?

Translator のバージョン 3.0 には、最新の JSON ベースの Web API が用意されています。 既存の機能をより少ない操作に統合することで、使いやすさとパフォーマンスが向上し、新機能が提供されます。

  • ある言語のテキストをあるスクリプトから別のスクリプトに変換する表記変換。
  • 1 つの要求で複数の言語に翻訳します。
  • 1 つの要求での言語検出、翻訳、表記変換。
  • 用語の代替翻訳を検索し、コンテキストで使用される用語を示すバック翻訳と例を検索する辞書。
  • より有益な言語検出結果。

ベース URL

Translator への要求は、ほとんどの場合、要求が発生した場所に最も近いデータセンターによって処理されます。 グローバル エンドポイントの使用時にデータセンターの障害が発生した場合、要求が地理的な外部にルーティングされる可能性があります。

特定の地域内で要求を強制的に処理するには、目的の地理的エンドポイントを使用します。 すべての要求は、地域内のデータセンター間で処理されます。

✔️ 特徴: Translator Text

サービス エンドポイント 要求処理データ センター
グローバル (推奨):
api.cognitive.microsofttranslator.com
最も近い利用可能なデータセンター。
南北アメリカ:
api-nam.cognitive.microsofttranslator.com
米国東部 2 • 米国西部 2
アジア太平洋:
api-apc.cognitive.microsofttranslator.com
東日本 • 東南アジア
ヨーロッパ (スイスを除く):
api-eur.cognitive.microsofttranslator.com
フランス中部 • 西ヨーロッパ
スイス:
詳細については、「スイスのサービス エンドポイント」を "参照してください"。
スイス北部 • スイス西部

スイスのサービス エンドポイント

スイス北部またはスイス西部にあるリソースを使用しているお客様は、Text API 要求が確実にスイス内で処理されるようにすることができます。 要求がスイス内で処理されるようにするには、Translator リソースを Resource regionSwitzerland North または Switzerland West 内に作成した後、API 要求内でそのリソースのカスタム エンドポイントを使用します。

たとえば、Azure portal で [Resource region] を [Switzerland North] として Translator リソースを作成し、リソース名が my-swiss-n である場合、カスタム エンドポイントは "https​://my-swiss-n.cognitiveservices.azure.com" となります。 翻訳する要求の例を次に示します。

// Pass secret key and region using headers to a custom endpoint
curl -X POST "https://my-swiss-n.cognitiveservices.azure.com/translator/text/v3.0/translate?to=fr" \
-H "Ocp-Apim-Subscription-Key: xxx" \
-H "Ocp-Apim-Subscription-Region: switzerlandnorth" \
-H "Content-Type: application/json" \
-d "[{'Text':'Hello'}]" -v

カスタム翻訳ツールは、現在スイスでは使用できません。

認証

Azure AI サービスで Translator または マルチサービス をサブスクライブし、キー (Azure portal で利用可能) を使用して認証します。

サブスクリプションの認証に使用できるヘッダーは 3 つあります。 次の表では、それぞれの使用方法について説明します。

ヘッダー 説明
Ocp-Apim-Subscription-Key 秘密鍵を渡す場合は、Azure AI サービス サブスクリプションで使用します
値は、Translator へのサブスクリプションの Azure 秘密鍵です。
認証 認証トークンを渡す場合は、Azure AI サービス サブスクリプションで使用します。
値はベアラー トークンです: Bearer <token>
Ocp-Apim-Subscription-Region マルチサービスおよびリージョンのトランスレーター リソースで使用します。
値は、マルチサービスまたはリージョンのトランスレーター リソースのリージョンです。 グローバル トランスレーター リソースを使用する場合、この値は省略可能です。

秘密鍵

最初のオプションは、 Ocp-Apim-Subscription-Key ヘッダーを使用して認証することです。 Ocp-Apim-Subscription-Key: <YOUR_SECRET_KEY> ヘッダーを要求に追加します。

グローバル リソースを使用した認証

グローバル トランスレーター リソースを使用する場合は、Translator を呼び出すために 1 つのヘッダーを含める必要があります。

ヘッダー 説明
Ocp-Apim-Subscription-Key 値は、Translator へのサブスクリプションの Azure 秘密鍵です。

グローバル トランスレーター リソースを使用して Translator を呼び出す要求の例を次に示します。

// Pass secret key using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

リージョン リソースを使用した認証

リージョンの Translator リソースを使用する場合、Translator を呼び出すために必要なヘッダーが 2 つあります。

ヘッダー 説明
Ocp-Apim-Subscription-Key 値は、Translator へのサブスクリプションの Azure 秘密鍵です。
Ocp-Apim-Subscription-Region 値は、Translator リソースのリージョンです。

リージョンの Translator リソースを使用して Translator を呼び出す要求の例を次に示します。

// Pass secret key and region using headers
curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

マルチサービス リソースを使用した認証

マルチサービス リソースを使用すると、1 つの API キーを使用して、複数のサービスの要求を認証できます。

マルチサービス シークレット キーを使用する場合は、要求に 2 つの認証ヘッダーを含める必要があります。 Translator を呼び出すために必要なヘッダーは 2 つあります。

ヘッダー 説明
Ocp-Apim-Subscription-Key 値は、マルチサービス リソースの Azure シークレット キーです。
Ocp-Apim-Subscription-Region 値は、マルチサービス リソースのリージョンです。

マルチサービス Text API サブスクリプションにはリージョンが必要です。 選択したリージョンは、マルチサービス キーを使用するときにテキスト翻訳に使用できる唯一のリージョンです。 これは、Azure portal を使用してマルチサービス サブスクリプションにサインアップしたときに選択したリージョンと同じである必要があります。

パラメーター Subscription-Keyを使用してクエリ文字列に秘密キーを渡す場合は、クエリ パラメーター Subscription-Regionでリージョンを指定する必要があります。

アクセス トークンを使用した認証

または、秘密鍵をアクセス トークンと交換することもできます。 このトークンは、各要求に Authorization ヘッダーとして含まれます。 承認トークンを取得するには、次の URL に POST 要求を行います。

リソースの種類 認証サービスの URL
グローバル https://api.cognitive.microsoft.com/sts/v1.0/issueToken
リージョンまたはマルチサービス https://<your-region>.api.cognitive.microsoft.com/sts/v1.0/issueToken

グローバル リソースの秘密鍵を指定してトークンを取得する要求の例を次に示します。

// Pass secret key using header
curl --header 'Ocp-Apim-Subscription-Key: <your-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=<your-key>'

また、米国中部にあるリージョン リソースの秘密鍵を指定してトークンを取得する要求の例を次に示します。

// Pass secret key using header
curl --header "Ocp-Apim-Subscription-Key: <your-key>" --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken"

// Pass secret key using query string parameter
curl --data "" "https://centralus.api.cognitive.microsoft.com/sts/v1.0/issueToken?Subscription-Key=<your-key>"

要求が成功すると、エンコードされたアクセス トークンが応答本文でプレーン テキストとして返されます。 有効なトークンは、承認のベアラー トークンとして Translator サービスに渡されます。

Authorization: Bearer <Base64-access_token>

認証トークンは 10 分間有効です。 Translator に対して複数の呼び出しを行うときは、トークンを再利用する必要があります。 ただし、プログラムが長期間にわたって Translator に要求を行う場合、プログラムは一定の間隔 (8 分ごとなど) に新しいアクセス トークンを要求する必要があります。

Microsoft Entra IDを使用した認証

Translator v3.0 では、Microsoft のクラウドベースの ID およびアクセス管理ソリューションである Microsoft Entra 認証がサポートされています。 承認ヘッダーを使用すると、Translator サービスは、要求するクライアントがリソースの使用と要求の完了を承認されていることを検証できます。

前提条件

ヘッダー

ヘッダ 価値
認証 値は、Azure AD によって生成されるアクセス ベアラー トークン です。
  • ベアラー トークンは認証の証明を提供し、リソースを使用するためのクライアントの承認を検証します。
  • 認証トークンは 10 分間有効であり、Translator に対して複数の呼び出しを行うときに再利用する必要があります。
  • 要求の例: 2 を参照してください。トークンを取得する
Ocp-Apim-Subscription-Region 値は、 Translator リソースのリージョンです。
  • リソースがグローバルな場合、この値は省略可能です。
Ocp-Apim-ResourceId 値は、Translator リソース インスタンスのリソース ID です。
  • リソース ID は、Azure portal の Translator Resource → Properties にあります
  • リソース ID 形式:
    /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.CognitiveServices/accounts/<resourceName>/
Translator プロパティ ページ - Azure portal

スクリーンショット:Azure portal の [Translator のプロパティ] ページ。

Von Bedeutung

Cognitive Services ユーザー ロールをサービス プリンシパルに割り当てます。 このロールを割り当てることで、Translator リソースへのアクセス権をサービス プリンシパルに付与します。

グローバル エンドポイントの使用

 // Using headers, pass a bearer token generated by Azure AD, resource ID, and the region.

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es" \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

カスタム エンドポイントの使用

// Using headers, pass a bearer token generated by Azure AD.

curl -X POST https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

マネージド ID の使用例

Translator v3.0 では、マネージド ID へのアクセスの承認もサポートされています。 トランスレーター リソースに対してマネージド ID が有効になっている場合は、マネージド ID によって生成されたベアラー トークンを要求ヘッダーに渡すことができます。

グローバル エンドポイントを使用する

// Using headers, pass a bearer token generated either by Azure AD or Managed Identities, resource ID, and the region.

curl -X POST https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Ocp-Apim-ResourceId: <Resource ID>" \
     -H "Ocp-Apim-Subscription-Region: <your-region>" \
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

カスタム エンドポイントを使用する

//Using headers, pass a bearer token generated by Managed Identities.

curl -X POST https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es \
     -H "Authorization: Bearer <Base64-access_token>"\
     -H "Content-Type: application/json" \
     -data-raw "[{'Text':'Hello, friend.'}]"

仮想ネットワークのサポート

Translator サービスは、Azure パブリック クラウドのすべてのリージョンで Virtual Network (VNET) 機能を使用できるようになりました。 仮想ネットワークを有効にするには、「Azure AI サービス仮想ネットワークの構成」を参照してください

この機能を有効にしたら、カスタム エンドポイントを使用して Translator を呼び出す必要があります。 グローバル トランスレーター エンドポイント ("api.cognitive.microsofttranslator.com") を使用することはできません。また、アクセス トークンで認証することはできません。

Translator リソースを作成し、選択したネットワークとプライベート エンドポイントからのアクセスを許可した後で、カスタム エンドポイントを見つけることができます。

  1. Azure portal で、Translator リソースに移動します。

  2. [リソース管理] セクションで [ネットワーク] を選択します。

  3. [ファイアウォールと仮想ネットワーク] タブで、[選択したネットワークとプライベート エンドポイント] を選択します。

    Azure portal の仮想ネットワーク設定のスクリーンショット。

  4. [保存] を選択して変更を保存します。

  5. [リソース管理] セクションから [キーとエンドポイント] を選択します。

  6. [ 仮想ネットワーク ] タブを選択します。

  7. テキスト翻訳とドキュメント翻訳のエンドポイントが一覧表示されます。

    仮想ネットワーク エンドポイントのスクリーンショット。

ヘッダー 説明
Ocp-Apim-Subscription-Key 値は、Translator へのサブスクリプションの Azure 秘密鍵です。
Ocp-Apim-Subscription-Region 値は、Translator リソースのリージョンです。 この値は、リソースが global

カスタム エンドポイントを使用して Translator を呼び出す要求の例を次に示します。

// Pass secret key and region using headers
curl -X POST "https://<your-custom-___domain>.cognitiveservices.azure.com/translator/text/v3.0/translate?api-version=3.0&to=es" \
     -H "Ocp-Apim-Subscription-Key:<your-key>" \
     -H "Ocp-Apim-Subscription-Region:<your-region>" \
     -H "Content-Type: application/json" \
     -d "[{'Text':'Hello, what is your name?'}]"

エラー

標準エラー応答は、 errorという名前の名前と値のペアを持つ JSON オブジェクトです。 値は、プロパティを持つ JSON オブジェクトでもあります。

  • code: サーバー定義のエラー コード。
  • message: エラーを人間が判読できる表現を提供する文字列。

たとえば、無料試用版サブスクリプションをお持ちのお客様は、無料クォータが使い果たされると、次のエラーが発生します。

{
  "error": {
    "code":403001,
    "message":"The operation isn't allowed because the subscription has exceeded its free quota."
    }
}

このエラーコードは 3 桁の HTTP ステータス コードの後に、エラーをさらに分類するための 3 桁の数字を続けた 6 桁の数字です。 一般的なエラー コード:

コード 説明
400000 無効な要求入力があります。
400001 "scope" パラメーターが無効です。
400002 "category" パラメーターが無効です。
400003 言語指定子が見つからないか無効です。
400004 ターゲット スクリプト指定子 ("To script") が見つからないか無効です。
400005 入力テキストが見つからないか無効です。
400006 言語とスクリプトの組み合わせが無効です。
400018 ソース スクリプト指定子 ("From script") が見つからないか無効です。
400019 サポートされていない言語の 1 つが指定されています。
400020 一連の入力テキストに無効な要素があります。
400021 API バージョン パラメーターが見つからないか無効です。
400023 無効な言語ペアが指定されています。
400035 ソース言語 ("From" フィールド) が無効です。
400036 ターゲット言語 ("To" フィールド) が見つからないか無効です。
400042 無効なオプション ("Options" フィールド) が指定されています。
400043 クライアント トレース ID (ClientTraceId フィールドまたは X-ClientTraceId ヘッダー) が見つからないか、無効です。
400050 入力テキストが長すぎます。 「要求の制限」を参照してください。
400064 "translation" パラメーターが見つからないか無効です。
400070 ターゲット スクリプト (ToScript パラメーター) の個数がターゲット言語 (To パラメーター) の個数と一致しません。
400071 TextType に対する値が無効です。
400072 一連の入力テストの要素数が多すぎます。
400073 スクリプト パラメーターが無効です。
400074 要求の本体が有効な JSON ではありません。
400075 言語ペアとカテゴリの組み合わせが無効です。
400077 要求の最大サイズを超えています。 「要求の制限」を参照してください。
400079 from 言語と to 言語間の翻訳に要求されたカスタム システムは存在しません。
400080 音訳は言語またはスクリプトに対してサポートされていません。
401000 資格情報が見つからないか無効であるため、要求は承認されていません。
401015 "指定された資格情報は Speech API 用です。 この要求には、Text API の資格情報が必要です。 Translator のサブスクリプションを使用してください。"
403000 操作は許可されていません。
403001 サブスクリプションが空きクォータを超えたため、操作は許可されません。
405000 要求メソッドは、要求されたリソースではサポートされていません。
408001 要求された翻訳システムを準備しています。 少し待ってから再試行してください。
408002 受信ストリームの待機中に要求がタイムアウトになりました。 サーバーが待機するように設定された時間以内に、クライアントは要求を生成しませんでした。 クライアントは、それ以降いつでも変更せずに要求を繰り返すことができます。
415000 Content-Type ヘッダーが見つからないか無効です。
429000, 429001, 429002 クライアントが要求の制限を超えたため、サーバーは要求を拒否しました。
500000 予期しないエラーが発生しました。 エラーが解決しない場合は、エラーの日付/時刻、応答ヘッダー X-RequestId からの要求識別子、および要求ヘッダー X-ClientTraceId からのクライアント識別子を使用して報告します。
503000 サービスが一時的に利用できません。 再試行します。 エラーが解決しない場合は、エラーの日付/時刻、応答ヘッダー X-RequestId からの要求識別子、および要求ヘッダー X-ClientTraceId からのクライアント識別子を使用して報告します。

メトリック

メトリックを使用すると、Azure portal で Translator の使用状況と可用性の情報を表示できます。 詳細については、「 データとプラットフォームのメトリック」を参照してください。

Translator メトリック

次の表は、利用可能なメトリックと、翻訳 API 呼び出しを監視するために使用される方法の説明を示しています。

メトリック 説明
TotalCalls API 呼び出しの合計数。
TotalTokenCalls 認証トークンを使用したトークン サービス経由の API 呼び出しの合計数。
SuccessfulCalls 成功した呼び出しの数。
TotalErrors エラー応答を含む呼び出しの数。
BlockedCalls レートまたはクォータの制限を超えた呼び出しの回数。
ServerErrors サーバー内部エラー (5XX) を含む呼び出しの数。
ClientErrors クライアント側エラー (4XX) を含む呼び出しの数。
遅延 要求を完了するまでの時間 (ミリ秒単位)。
CharactersTranslated 受信テキスト要求の合計文字数。