クイックスタートガイド: 認証済み API 呼び出しを行う

[アーティクル]
10/07/2024

この記事では、Intelligent Recommendations サービスの認証済み要求を作成して結果を確認する方法を説明します。

概要

適切な API 要求を作成するためには、次の情報を準備する必要があります。

Microsoft Entra ID のテナント ID
呼び出し元のアプリケーションクライアント ID
アプリケーションのシークレット値
Intelligent Recommendations API で概説したように、有効なクエリパス/パラメーターで構成したエンドポイント URL を提供する、Intelligent Recommendations アカウントを使用した HTTP クエリ。

この情報を見つけるためのヘルプは後述します。

この情報を準備している場合は、このクイックスタートガイドの API 要求の作成セクションにジャンプできます。

前提条件

開始する前に、以下の項目があることを確認します:

プロビジョニングした Intelligent Recommendations アカウント。 Intelligent Recommendations アカウントをまだ作成していない場合は、intelligent Recommendations アカウントの新規作成に移動します。また、クイックスタートガイド: サンプルデータで Intelligent Recommendations を設定して実行するの手順に従うこともできます。
Intelligent Recommendations サービスを呼び出すためのアプリケーション (Microsoft Entra ID の ID)。

注意

サービスを正常にプロビジョニングしてから、AI-ML モデルトレーニングが入力データを処理してランク付けしたリストを作成するまでに、最大 1 日かかる場合があります。最初の Intelligent Recommendations アカウントをプロビジョニングしたばかりの場合は、続行する前に待機する必要があります。

手順 1: エンドポイント URL を作成します

要求を処理するためには、すべての Intelligent Recommendations アカウントに少なくとも 1 つのサービスエンドポイントが必要です。サービスエンドポイントは、サービスを呼び出すための一意の URL を提供します。

適切な API 要求を作成するためには、Azure ポータルアカウントを使用してサービスエンドポイント URL を見つけます。

Azure ポータルにサインインします。
Intelligent Recommendations アカウントに移動します。
クエリする対象のアカウントを選択します。
メニューの コンポーネント セクションから サービスエンドポイント を選択します。
使用するサービスエンドポイントを選択します。
次のように、エンドポイントリソースのプロパティから URL を見つけます。

URL の構成を次に示します。

https://{ir-account-name}-{service-endpoint-name}.mir.prod.reco.microsoft.com/

手順 2: クライアントアプリケーションを設定する

Intelligent Recommendations には OAuth2 認証が必要です。認証でサービスエンドポイントを呼び出す元の Microsoft Entra ID アプリケーションを決定 (または作成) します。認証していない呼び出しは失敗し、エラーが発生します。

Azure ポータルにサインインします。
Microsoft Entra ID に移動します。
アプリの登録 に移動します。
既存のアプリケーションを選択するか、新規作成します。
アプリケーションの準備ができたら、アプリケーションプロパティからクライアント ID とテナント ID を見つけます。
そのクライアント ID とテナント ID をメモします。これらの値は API 要求の作成に使用します。

許可済みの ID を Intelligent Recommendations アカウントに追加します

続行する前に、Intelligent Recommendations アカウントの認証済みリストに ID を追加する必要があります。

Azure ポータルにサインインします。
Intelligent Recommendations アカウントに移動します。
クエリする対象のアカウントを選択します。
メニューから エンドポイント認証 を選択します。
新しいアプリケーションプリンシパル ID を追加します (プリンシパル ID は以前見つけたクライアント ID と同じです)。
プリンシパルタイプを「アプリケーション」に変更します。

注意

これらの設定の更新には最大 15 分かかります。

手順 3: 認証の構成

最後の手順は認証メカニズムの構成です。シークレットまたは証明書のいずれかを使用できます。このクイックスタートガイドではシークレットを作成します。

左側のナビゲーションペインで 証明書とシークレット を選択します。
新しいクライアントシークレット を選択します。このシークレット値は非公開であり、次の手順で必要になるため、安全な場所に保存する必要があります。

注意

アプリケーションシークレットをコピーします。自分のアプリケーションシークレットをコピーします。で示されているように、シークレット値をコピーできるのは作成直後のみです

これで必要な情報が揃ったので、API 要求を作成して Intelligent Recommendations サービスを呼び出す準備ができました。

API 要求を作成します

この次のセクションでは、REST API ツールで Intelligent Recommendations API を呼び出す方法を 2 つ示します。別のアプリケーションを使用して Intelligent Recommendations エンドポイントを呼び出す場合は、OAuth2 認証をサポートする REST API ツールを必ず使用してください。

このクイックスタートガイドでは、Insomnia と C# コードの両方で一般的な品目リストを取得するように、API 要求の構成方法を説明します。

続行する前に、次の前提条件をすべて満たすことを確認してください。

Microsoft Entra ID のテナント ID
呼び出し元のアプリケーションクライアント ID
アプリケーションシークレット値
Intelligent Recommendations API で概説したように、有効なクエリパス/パラメーターで構成したエンドポイント URL を提供する、Intelligent Recommendations アカウントを使用した HTTP クエリ

注意

次の要求の例では、アカウント名 irtest とサービスエンドポイント serving01 を使用しています。

https://irtest-serving01.mir.prod.reco.microsoft.com/Reco/V1.0/Popular

結果エクスプローラーでエンドポイントを呼び出す

重要 2023 年 4 月の時点で、IR ポータル Web サイトと結果エクスプローラーツールは非推奨となり、使用されなくなりました。結果を確認するには、次のセクションのオプションのいずれかを使用します:

Insomnia でエンドポイントを呼び出す

Insomnia または OAuth2 認証をサポートする同様の REST API ツールを使用して、Intelligent Recommendations エンドポイントにテスト要求を送信できます。

詳細については、Dataverse Web API に Insomnia を使用するを参照してください

認証プロセス

はじめにセクションで、要求を作成する を選択します。
要求コンポーザーの承認タブに移動して、次の値を使用して構成します。
- タイプを OAuth 2.0 に設定します
- Authorization ヘッダーの追加を要求ヘッダーに設定します
- 何らかのトークン名を使用して新しいトークンを作成します。
- 付与タイプ = クライアント資格情報
- アクセストークン URL = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
- クライアント ID = <yourAppClientID>
- クライアントシークレット = <yourAppSecretValue>
- スコープ = <ご利用のエンドポイント URL>/.default
- クライアント認証を基本認証ヘッダーとして送信に設定したままにする
トークン生成前の外観は次のとおりです。
新しいアクセストークンの取得 ボタンが見つかるまでページを下にスクロールします。正しく構成されている場合、ボタンを選択すると有効なトークンで新しいウィンドウが開きます。
トークンの使用 を選択します。

要求を投稿します

これで認証されたので、実際の要求を投稿できます。

要求を投稿して送信を選択します。試してみることができる追加の事前構成された API リクエストのリストについては、サンプルリクエストガイドを参照してください。
画面の下部に JSON 応答が表示されます:

注意

応答が成功すると、JSON 応答の品目セクションにある品目の、ランク付けされたリストが返されます。このシナリオで最も一般的な品目 ID は 712 です。ここで API ステータスコードの完全なリストを表示できます。

C# コードでエンドポイントを呼び出す

C# を使用して Intelligent Recommendations エンドポイントを正常に呼び出す場合は、次の情報を準備します。

Microsoft Entra ID のテナント ID
呼び出し元のアプリケーションクライアント ID
アプリケーションシークレット値
Intelligent Recommendations API の仕様で概説したように、有効なクエリパス/パラメーターで構成したエンドポイント URL を提供する、Intelligent Recommendations アカウントを使用した HTTP クエリ

次に、提供されたサンプルコードをコピーして関連するフィールドを更新し、実行します。

public static async Task CallIRApiAsync()
{
    // *************************************************************************
    // The code depends on the Microsoft.Identity.Client library
    // Please note the code sections that have to be modified below  
    // *************************************************************************

    // Recommendations AAD app ID
    var scope = "<YOUR ENDPOINT URL>";

    // Your client AAD app ID
    var callerAadAppId = "<YOUR AAD APP ID>";

    // AAD Tenant ID
    var callerAadTenantId = "<YOUR AAD TENANT ID>";

    var token = await AcquireTokenWithSecret(callerAadAppId, callerAadTenantId, scope);
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Authorization  = AuthenticationHeaderValue.Parse(token.CreateAuthorizationHeader());

    // **************************************************
    // and now, use httpClient to execute IR requests..
    // **************************************************
}

public static Task<AuthenticationResult> AcquireTokenWithSecret ( 
               string callerAadAppId, string callerTenantId, string scope )
{   
    // The below example uses a secret to authenticate to AAD
    // An alternative certificate-based method can be used instead:
    // replace: "WithClientCert(string secret)" ==> "WithCertificate(X509Certificate certificate)"

    var secret = "<YOUR AAD APP SECRET>";
    var app = ConfidentialClientApplicationBuilder.Create(callerAadAppId).WithAuthority($"https://login.microsoftonline.com/{callerTenantId}").WithClientSecret(secret).Build();
    var scopes = new[] { $"{scope}/.default" }; 
    return app.AcquireTokenForClient(scopes).ExecuteAsync(CancellationToken.None); }
}

成功した応答は、品目セクションのシナリオに基づくおすすめ品目の、ランク付けされたリストを含みます。このシナリオで最も一般的な品目 ID は 712 です。ここで API ステータスコードの完全なリストを表示できます。

Azure Machine Learning でエンドポイントを呼び出す

Azure Machine Learning を使用して Intelligent Recommendations サービスに API 要求を行うには、この Retail Recommender Jupyter notebook を使用できます。追加のボーナスとして、このノートブックには、Intelligent Recommendations と Azure Personalizer を組み合わせるステップも含まれています。詳細: Retail Recommender Jupyter Notebook

参照

Intelligent Recommendations API リファレンス
 API ステータスコード
 クイックスタートガイド: サンプルデータを使用した Intelligent Recommendations の設定と実行
 展開の概要
 データコントラクトの活用によるデータの共有化

次の方法で共有

クイックスタートガイド: 認証済み API 呼び出しを行う

概要

前提条件

手順 1: エンドポイント URL を作成します

手順 2: クライアントアプリケーションを設定する

許可済みの ID を Intelligent Recommendations アカウントに追加します

手順 3: 認証の構成

API 要求を作成します

結果エクスプローラーでエンドポイントを呼び出す

Insomnia でエンドポイントを呼び出す

認証プロセス

要求を投稿します

C# コードでエンドポイントを呼び出す

Azure Machine Learning でエンドポイントを呼び出す

参照

その他のリソース

次の方法で共有

クイック スタート ガイド: 認証済み API 呼び出しを行う

概要

前提条件

手順 1: エンドポイント URL を作成します

手順 2: クライアント アプリケーションを設定する

許可済みの ID を Intelligent Recommendations アカウントに追加します

手順 3: 認証の構成

API 要求を作成します

結果エクスプローラーでエンドポイントを呼び出す

Insomnia でエンドポイントを呼び出す

認証プロセス

要求を投稿します

C# コードでエンドポイントを呼び出す

Azure Machine Learning で エンドポイント を呼び出す

参照

その他のリソース

クイックスタートガイド: 認証済み API 呼び出しを行う

手順 2: クライアントアプリケーションを設定する

Azure Machine Learning でエンドポイントを呼び出す