認証と承認

Foundry Tool に対する各要求には、認証ヘッダーを含める必要があります。 このヘッダーを使用して、リソース キーまたは認証トークンを渡します。これは、サービスまたはサービスのグループについてお客様のサブスクリプションを検証するために使用されます。 この記事では、要求を認証する方法と、それぞれの要件について説明します。

• 単一サービスのリージョン、単一サービスグローバル、またはマルチサービスのリソース キーを使用して認証します。
• ベアラー トークンを使用して認証します。
• Microsoft Entra ID による認証は、Microsoft のサービス、リソース、アプリケーションのユーザー アクセスとアクセス許可を管理するように設計されたクラウドベースの ID ソリューションです。 Microsoft Entra ID を使用すると、パスワードやキーを必要とせずに、Azure リソースへの要求を認証できます。

ヘッダー

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

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

秘密鍵

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

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

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

グローバル トランスレーター リソースを使用して 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 つあります。

リージョンの 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 つあります。

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

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

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

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

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

// 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>"

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

Authorization: Bearer <Base64-access_token>

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

Microsoft Entra IDを使用した認証

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

前提条件

• Microsoft Entra ID で認証する方法の簡単な理解。

• マネージド ID へのアクセスを承認する方法の簡単な理解。

Microsoft Entra ID ヘッダー

Translator プロパティ ページ - Azure portal

例

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

// 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) 機能を使用できるようになりました。 仮想ネットワークを有効にするには、「Foundry Tools 仮想ネットワークの構成」を参照してください。

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

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

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

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

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

   

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

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

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

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

   

カスタム エンドポイントを使用して 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?'}]"