Azure Cognitive Services に対する要求の認証

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

前提条件

要求を実行する前に、Azure アカウントと Azure Cognitive Services サブスクリプションが必要です。 既にアカウントをお持ちの場合は、次のセクションまでスキップして進んでください。 アカウントをお持ちでない場合は、数分で設定を行えるガイドをご覧ください。Azure の Cognitive Services アカウントの作成に関するページを参照してください。

アカウントの作成後に、Azure portal からサブスクリプション キーを取得できます。

認証ヘッダー

Azure Cognitive Services で使用できる認証ヘッダーについて簡単に確認しましょう。

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

単一サービスのサブスクリプション キーによる認証

1 つ目の方法では、Translator などの特定のサービスに対してサブスクリプション キーを使用して要求を認証します。 お客様が作成したそれぞれのリソースについて、Azure portal でキーを取得できます。 サブスクリプション キーを使用して要求を認証するには、それを Ocp-Apim-Subscription-Key ヘッダーとして渡す必要があります。

以下のサンプル要求は、Ocp-Apim-Subscription-Key ヘッダーの使用方法を示しています。 このサンプルを使用する際は有効なサブスクリプション キーを含める必要があることに注意してください。

これは、Bing Web Search API 呼び出しのサンプルです。

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

これは、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

次のビデオでは、Cognitive Services キーを使用するデモンストレーションを行っています。

マルチサービスのサブスクリプション キーによる認証

警告

現在のところ、以下のサービスではマルチサービス キーがサポートされて いません。QnA Maker、Speech Services、Custom Vision、および Anomaly Detector。

この方法も、サブスクリプション キーを使用して要求を認証します。 主な違いは、サブスクリプション キーが特定のサービスに関連付けられておらず、単一のキーを使用して複数の Cognitive Services に対する要求を認証できることです。 リージョン別の提供状況、サポートされている機能、および価格については、「Cognitive Services の価格」を参照してください。

サブスクリプション キーは、各要求内で Ocp-Apim-Subscription-Key ヘッダーとして指定されます。

Cognitive Services のマルチサービスのサブスクリプション キーのデモ

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

マルチサービスのサブスクリプション キーを使用して api.cognitive.microsoft.com に対する要求を実行するときは、URL にリージョンを含める必要があります。 (例: westus.api.cognitive.microsoft.com)。

Translator サービスと共にマルチサービスのサブスクリプション キーを使用する場合は、Ocp-Apim-Subscription-Region ヘッダーを使用してサブスクリプション リージョンを指定する必要があります。

マルチサービス認証は、以下のリージョンでサポートされています。

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

サンプルの要求

これは、Bing Web Search API 呼び出しのサンプルです。

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

これは、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

認証トークンによる認証

Azure Cognitive Services の中には、認証トークンを受け入れるものや、場合によっては認証トークンを必要とするものがあります。 現在、以下のサービスで認証トークンがサポートされています。

  • Text Translation API
  • Speech Services: Speech to Text REST API
  • Speech Services: Text to Speech REST API

注意

QnA Maker でも Authorization ヘッダーが使用されますが、エンドポイント キーが必要です。 詳細については、QnA Maker でナレッジ ベースから回答を取得する方法に関するページを参照してください。

警告

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

単一サービスのサブスクリプション キーとマルチサービスのサブスクリプション キーは、どちらも認証トークンと交換できます。 認証トークンは 10 分間有効です。

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

サンプルの要求

サブスクリプション キーを認証トークンと交換するには、https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken という URL を使用します。

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"

以下のマルチサービスのリージョンで、トークンの交換がサポートされています。

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

認証トークンを取得したら、各要求内でそれを Authorization ヘッダーとして渡す必要があります。 これは、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

Azure Active Directory を使用して認証する

重要

  1. 現時点では、Computer Vision API、Face API、Text Analytics API、Immersive Reader、Form Recognizer、Anomaly Detector、QnA Maker、および Bing Custom Search を除くすべての Bing サービスにおいて のみ、Azure Active Directory (AAD) を使用した認証がサポートされています。
  2. AAD 認証は常に、Azure リソースのカスタム サブドメイン名と共に使用される必要があります。 リージョン エンドポイントでは、AAD 認証はサポートされません。

前のセクションでは、Azure Cognitive Services に対して単一サービスまたはマルチサービスのサブスクリプション キーを使用して認証する方法を説明しました。 これらのキーを使用すると、開発を迅速かつ簡単に開始できますが、Azure ロールベースのアクセス制御 (Azure RBAC) を必要とするより複雑なシナリオでは不十分です。 Azure Active Directory (AAD) を使用して認証を行うために何が必要なのかを確認しましょう。

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

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

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

  1. まず、Azure Cloud Shell を開きます。 サブスクリプションを選択します。

    Set-AzContext -SubscriptionName <SubscriptionName>
    
  2. 次に、カスタム サブドメインを使用して Cognitive Services リソースを作成します。 サブドメイン名は、グローバルに一意である必要があり、"."、"!"、"," などの特殊文字を含めることはできません。

    $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
    
  3. 成功すると、エンドポイント にリソースに固有のサブドメイン名が表示されます。

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

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

注意

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

  1. まず、AAD アプリケーションを登録してみましょう。

    $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
    
    $app = New-AzADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -Password $SecureStringPassword
    

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

  2. 次に、AAD アプリケーションのサービス プリンシパルを作成する必要があります。

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
    

    注意

    Azure portal でアプリケーションを登録したら、この手順は完了です。

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

    注意

    アプリケーションの ObjectId ではなく、サービス プリンシパルの ObjectId が使用されます。 ACCOUNT_ID は、作成した Cognitive Services アカウントの Azure リソース ID になります。 Azure portal でリソースの "プロパティ" から Azure リソース ID を検索できます。

    New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
    

要求のサンプル

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

  1. TenantId を取得します。

    $context=Get-AzContext
    $context.Tenant.Id
    
  2. トークンを取得します。

    注意

    Azure Cloud Shell を使用している場合、SecureClientSecret クラスは使用できません。

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
    $secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
    $clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
    $token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
    $token
    

  1. Computer Vision API を呼び出します。
    $url = $account.Endpoint+"vision/v1.0/models"
    $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -Verbose
    $result | ConvertTo-Json
    

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

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

Cognitive Services では、Azure リソースのマネージド ID を使用した Azure Active Directory (Azure AD) 認証がサポートされています。 Azure リソースのマネージド ID では、Azure Virtual Machines (VMs)、Function Apps、Virtual Machine Scale Sets などのサービスで実行されているアプリケーションから Cognitive Services リソースへのアクセスを、Azure AD 資格情報を使用して承認することができます。 Azure リソースのマネージド ID を Azure AD 認証と一緒に使用することで、クラウドで動作するアプリケーションに資格情報を保存することを避けることができます。

VM 上のマネージド ID を有効にする

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

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

関連項目