Foundry Tools に対する要求を認証する

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

単一サービスまたは Foundry マルチサービスリソースキーを使用して認証します。
トークンで認証する。
Microsoft Entra ID で認証する。

前提条件

要求を行う前に、Azure サブスクリプションと Foundry リソースが必要です。 Foundry リソースが必要な場合は、 Foundry リソースの作成ガイドを参照してください。

認証ヘッダー

Foundry Tools で使用できる認証ヘッダーを簡単に確認しましょう。

ヘッダー	説明
Ocp-Apim-Subscription-Key	このヘッダーを使用して、特定のサービスまたは Foundry リソースキーのリソースキーで認証します。
Ocp-Apim-Subscription-Region	このヘッダーは、 Azure Translator で Foundry リソースキーを使用する場合にのみ必要です。このヘッダーを使用して、リソースリージョンを指定します。
承認	アクセストークンを使用する場合、このヘッダーを使用します。トークンの交換を実行する手順については、以降のセクションで詳しく説明されています。値は `Bearer <TOKEN>` 形式で指定します。

単一サービスのリソースキーを使用した認証

最初のオプションは、Azure Translator などの特定のサービスのリソースキーを使用して要求を認証することです。お客様が作成したそれぞれのリソースについて、Azure portal でキーを取得できます。 Azure portal でリソースに移動します。 [キーとエンドポイント] セクションは、[リソース管理] セクションにあります。エンドポイントとアクセスキーをコピーします。これらは、API 呼び出しを認証するために両方とも必要です。 KEY1 または KEY2 を使用できます。常に 2 つのキーを用意しておくと、サービスを中断させることなく、キーのローテーションと再生成を安全に行うことができます。

リソースキーを使用して要求を認証するには、それを Ocp-Apim-Subscription-Key ヘッダーとして渡す必要があります。これは、Azure Translator サービスのサンプル呼び出しです。

これは、Translator サービスの呼び出しの例です。

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Foundry リソースキーを使用して認証する

Foundry リソースキーを使用して、複数の Foundry Tools の要求を認証できます。認証資格情報は、特定のサービスに関連付けられません。リージョンの可用性、サポートされている機能、価格については、「 Foundry Tools の価格」を参照してください。

リソースキーは、各要求内で Ocp-Apim-Subscription-Key ヘッダーとして指定されます。

サポートされているリージョン

Foundry リソースキーを使用してapi.cognitive.microsoft.com要求を行う場合は、URL にリージョンを含める必要があります。例: westus.api.cognitive.microsoft.com。

Azure Translator で Foundry リソースキーを使用する場合は、Ocp-Apim-Subscription-Region ヘッダーを使用してリソースリージョンを指定する必要があります。

Foundry リソース認証は、次のリージョンでサポートされています。

australiaeast
brazilsouth
canadacentral
centralindia
eastasia
eastus
japaneast
northeurope
southcentralus
southeastasia
uksouth
westcentralus
westeurope
westus
westus2
francecentral
koreacentral
northcentralus
southafricanorth
uaenorth
switzerlandnorth

サンプルの要求

これは、Azure Translator サービスのサンプル呼び出しです。

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

アクセストークンを使用して認証する

Foundry ツールの中には、アクセストークンを受け入れるものもあります。場合によっては、アクセストークンが必要な場合もあります。現在、以下のサービスでアクセストークンがサポートされています。

Text Translation API
音声: 音声テキスト変換 API
音声: Text to Speech API

警告

アクセストークンをサポートするサービスは時間の経過と同時に変更される可能性があるため、この認証方法を使用する前に、サービスの API リファレンスを確認してください。

Foundry と AI サービスのリソースキーは、認証トークンと交換できます。認証トークンは 10 分間有効です。これらは JSON Web Token (JWT) 形式で格納され、JWT ライブラリを使用してプログラムで照会することができます。

アクセストークンは、Authorization ヘッダーとして要求に組み込まれます。指定されるトークンの値の前には Bearer が付いている必要があります (例: Bearer YOUR_AUTH_TOKEN)。

サンプルの要求

リソースキーをアクセストークンと交換するには、以下の URL を使用します: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken。

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

これらのリージョンでは、Foundry リソースのトークン交換がサポートされています。

australiaeast
brazilsouth
canadacentral
centralindia
eastasia
eastus
japaneast
northeurope
southcentralus
southeastasia
uksouth
westcentralus
westeurope
westus
westus2

アクセストークンを取得したら、各要求内でそれを Authorization ヘッダーとして渡す必要があります。これは、Azure Translator サービスのサンプル呼び出しです。

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Microsoft Entra ID で認証する

重要

Microsoft Entra 認証は常に、Azure リソースのカスタムサブドメイン名と共に使用される必要があります。リージョンエンドポイントでは、Microsoft Entra 認証がサポートされていません。

前のセクションでは、API キーを使用して認証する方法について説明しました。これらのキーは、開発を開始するための迅速かつ簡単なパスを提供しますが、Azure ロールベースのアクセス制御 (Azure RBAC) を必要とするシナリオでは不足しています。 Microsoft Entra ID を使用してより安全に認証するために必要なものを見てみましょう。

以降のセクションでは、Azure Cloud Shell 環境または Azure CLI を使用してサブドメインを作成し、ロールを割り当て、Foundry Tools を呼び出すベアラートークンを取得します。問題が発生した場合は、各セクションに、Azure Cloud Shell/Azure CLI の各コマンドで使用可能なすべてのオプションへのリンクが提供されています。

重要

組織で Microsoft Entra ID を介した認証を行っている場合は、組織内のユーザーが常に Microsoft Entra ID を使う必要があるように、ローカル認証 (キーによる認証) を無効にすることをお勧めします。

カスタムサブドメインを使用してリソースを作成する

最初の手順で、カスタムサブドメインを作成します。カスタムサブドメイン名を持たない既存の Foundry リソースを使用する場合は、 Foundry Tools カスタムサブドメインの手順に従って、リソースのカスタムサブドメインを有効にします。

まず、Azure Cloud Shell を開きます。サブスクリプションを選択します。
```
Set-AzContext -SubscriptionName <SubscriptionName>
```
次に、カスタムサブドメインを使用して Foundry リソースを作成します。サブドメイン名は、グローバルに一意である必要があり、"."、"!"、"," などの特殊文字を含めることはできません。
```
$account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
```
成功すると、エンドポイントにリソースに固有のサブドメイン名が表示されます。

サービスプリンシパルにロールを割り当てる

これで、カスタムサブドメインがリソースに関連付けられたので、ロールをサービスプリンシパルに割り当てる必要があります。

Note

Azure ロールの割り当ての反映には最大で 5 分かかる場合があることに注意してください。

まず、 Microsoft Entra アプリケーションを登録しましょう。

$SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force

$app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword

次の手順では、ApplicationId が必要になります。

次に、Microsoft Entra アプリケーションのサービスプリンシパルを作成する必要があります。
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Note

Azure portal でアプリケーションを登録したら、この手順は完了です。
最後の手順では、(リソースにスコープが設定された) サービスプリンシパルに "Cognitive Services ユーザー" ロールを割り当てます。ロールを割り当てて、このリソースにサービスプリンシパルアクセス権を付与します。同じサービスプリンシパルアクセスをサブスクリプション内の複数のリソースに対して許可できます。

Note

アプリケーションの ObjectId ではなく、サービスプリンシパルの ObjectId が使用されます。 ACCOUNT_IDは、作成した Foundry リソースの Azure リソース ID になります。 Azure portal でリソースの "プロパティ" から Azure リソース ID を見つけることができます。
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

要求のサンプル

このサンプルでは、サービスプリンシパルの認証にパスワードが使用されています。指定されたトークンは、Azure Vision API の呼び出しに使用されます。

TenantId を取得します。

$context=Get-AzContext
$context.Tenant.Id

トークンを取得します。

$tenantId = $context.Tenant.Id
$clientId = $app.ApplicationId
$clientSecret = "<YOUR_PASSWORD>"
$resourceUrl = "https://cognitiveservices.azure.com/"

$tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    resource      = $resourceUrl
}

$responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
$accessToken = $responseToken.access_token

Note

スクリプトでパスワードを使う場合、最も安全なオプションは、PowerShell のシークレット管理モジュールを使い、Azure Key Vault などのソリューションと統合することです。

Azure Vision API を呼び出します。

$url = $account.Endpoint+"vision/v1.0/models"
$result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
$result | ConvertTo-Json

または、証明書を使用してサービスプリンシパルを認証することもできます。サービスプリンシパルの他に、別の Microsoft Entra アプリケーションから委任されたアクセス許可を持つことで、ユーザープリンシパルもサポートされます。この場合、パスワードまたは証明書の代わりに、ユーザーはトークンを取得するときに 2 要素認証が求められます。

マネージド ID へのアクセスを認証する

Foundry Tools では、 Azure リソースのマネージド ID を使用した Microsoft Entra 認証がサポートされます。 Azure リソースのマネージド ID は、Azure 仮想マシン (VM)、関数アプリ、仮想マシンスケールセット、およびその他のサービスで実行されているアプリケーションからの Microsoft Entra 資格情報を使用して、Foundry リソースへのアクセスを承認できます。 Azure リソースのマネージド ID と Microsoft Entra 認証を併用すると、クラウドで実行されるアプリケーションに資格情報を保存することを避けることができます。

仮想マシン (VM) でマネージド ID を有効にする

Azure リソースのマネージド ID を使用して VM から Foundry リソースへのアクセスを承認するには、VM 上の Azure リソースのマネージド ID を有効にする必要があります。 Azure リソースのマネージド ID を有効にする方法については、次を参照してください。

マネージド ID の詳細については、Azure リソースのマネージド ID に関するページを参照してください。

Azure Key Vault を使用して資格情報に安全にアクセスする

Azure Key Vault を使用して、Microsoft Foundry アプリケーションを安全に開発できます。 Key Vault を使用すると、認証資格情報をクラウドに格納でき、アプリケーションにセキュリティ情報を格納しないため、シークレットが誤って漏洩する可能性が低くなります。

認証は Microsoft Entra ID によって行われます。認可は、Azure ロールベースのアクセス制御 (Azure RBAC) または Key Vault のアクセスポリシーを使用して行うことができます。 Azure RBAC は、コンテナーの管理と、コンテナーに格納されているデータへのアクセスの両方に使用できます。一方、Key Vault のアクセスポリシーは、コンテナーに格納されているデータにアクセスしようとするときにのみ使用できます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-11-18

次の方法で共有

Foundry Tools に対する要求を認証する

前提条件

認証ヘッダー

単一サービスのリソース キーを使用した認証

Foundry リソース キーを使用して認証する

サポートされているリージョン

サンプルの要求

アクセス トークンを使用して認証する

サンプルの要求

Microsoft Entra ID で認証する

カスタム サブドメインを使用してリソースを作成する

サービス プリンシパルにロールを割り当てる

要求のサンプル

マネージド ID へのアクセスを認証する

仮想マシン (VM) でマネージド ID を有効にする

Azure Key Vault を使用して資格情報に安全にアクセスする

関連コンテンツ

フィードバック

その他のリソース

単一サービスのリソースキーを使用した認証

Foundry リソースキーを使用して認証する

アクセストークンを使用して認証する

カスタムサブドメインを使用してリソースを作成する

サービスプリンシパルにロールを割り当てる