快速入手冊：進行經過驗證的 API 呼叫

發行項
10/07/2024

本文協助您了解如何建構對智慧建議服務提出的已驗證要求，並查看結果。

概觀

若要建立成功的 API 要求，您必須準備下列資訊：

Microsoft Entra ID 租用戶識別碼
呼叫端的應用程式用戶端識別碼
應用程式的祕密值
HTTP 查詢，使用由有效的查詢路徑/參數組成的智慧建議帳戶服務端點 URL，如智慧建議 API 中所述。

如需有關尋找此資訊的協助，請繼續閱讀。

如果已準備好此資訊，就可以跳至本快速入門手冊的建構 API 要求一節。

先決條件

開始之前，請確定您已有：

已佈建的智慧建議帳戶。使用還沒有建立智慧建議帳戶，請移至建立新的智慧建議帳戶。您也可以依照快速入門手冊：使用範例資料設定並執行智慧建議中的指示進行。
用於呼叫智慧建議服務的應用程式 (Microsoft Entra ID 身分識別)。

注意

成功佈建服務後，AI-ML 模型訓練最多可能需要一天的時間，處理輸入資料並產生排名清單。如果剛剛佈建智慧建議帳戶，您可能需要等待才能繼續。

步驟 1：建立端點 URL

每個智慧建議帳戶都至少需要一個服務端點來為要求提供服務。服務端點提供用來呼叫服務的唯一 URL。

若要建立正確的 API 要求，請使用您的 Azure 入口網站帳戶尋找服務端點 URL：

登入 Azure 入口網站。
瀏覽至建立新的智慧建議帳戶。
選取您要查詢的帳戶。
從功能表的元件區段選取服務端點。
選取您要使用的服務端點。
在端點資源的屬性中找出 URL，如下所示：

URL 的結構如下：

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

步驟 2：設定用戶端應用程式

智慧建議需要 OAuth2 驗證。判斷 (或建立) 要從中使用驗證呼叫服務終點的 Microsoft Entra ID 應用程式。任何未經驗證的呼叫都會失敗，並發生錯誤。

登入 Azure 入口網站。
移至 Microsoft Entra ID。
移至應用程式註冊。
選取現有應用程式，或建立新的應用程式。
應用程式就緒後，就在應用程式屬性中找出用戶端識別碼和租用戶識別碼：
記下用戶端識別碼和租用戶識別碼。這些值用於建立 API 要求。

將允許的身分識別新增至智慧建議帳戶

繼續之前，您必須將身分識別新增至您的智慧建議帳戶中的已驗證清單。

登入 Azure 入口網站。
瀏覽至建立新的智慧建議帳戶。
選取您要查詢的帳戶。
從功能表選取端點驗證。
加入新的應用程式主體識別碼 (主體識別碼與先前找到的用戶端識別碼相同)。
將主體類型變更為 [應用程式]。

注意

更新這些設定可能需要 15 分鐘的時間。

步驟 3：設定驗證

最後一個步驟是設定驗證機制。您可以使用祕密或憑證。在本快速入門手冊中，您將了解如何建立祕密。

在左側瀏覽窗格中，選取憑證及祕密。
選取用戶端密碼。此祕密值是私人的，因為在下一個步驟中還需要此值，您必須將其儲存在安全的地方。

注意

您只能在建立後立即複製密碼值，如下所示：複製應用程式祕密。

現在已準備好必要的資訊，即可開始建立 API 要求並呼叫智慧建議服務。

建構 API 要求

下一節會提供兩種透過 REST API 工具呼叫智慧建議 API 的方式。若要使用不同的應用程式來呼叫智慧建議端點，請確定您使用的是支援 OAuth2 驗證的 REST API 工具。

本快速入門手冊逐步解說如何設定 API 要求，使用 Insomnia 以及 C# 程式碼來擷取熱門項目清單。

繼續之前，請確定您已有下列每一個先決條件：

Microsoft Entra ID 租用戶識別碼
呼叫端應用程式用戶端識別碼
應用程式祕密值
HTTP 查詢，使用由有效的查詢路徑/參數組成的智慧建議帳戶服務端點 URL，如智慧建議 API 中所述

注意

在下列範例要求中，我們使用帳戶名稱 irtest 和服務端點 serving01。

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

使用結果總管呼叫端點

重要自 2023 年 4 月起，IR 入口網站和結果總管工具已被取代，不再使用。若要查看結果，請使用下列各節中的其中一個選項：

使用 Insomnia 呼叫端點

您可以使用 Insomnia 或其他支援 OAuth2 驗證的類似 REST API 工具，將測試要求傳送至智慧建議端點。

如需詳細資訊，請參閱將 Insomnia 與 Dataverse Web API 搭配使用

驗證程序

在 [開始使用] 區段下方，選取建立要求。
瀏覽至要求編輯器的授權索引標籤，然後使用下列值進行設定：
- 將類型設定為 OAuth 2.0
- 將 [新增授權標頭] 設定為要求標頭
- 使用一些權杖名稱建立新的權杖。
- 授與類型 = 用戶端認證
- 存取權杖 URL = https://login.microsoftonline.com/<callerTenantID>/oauth2/v2.0/token
- 用戶端識別碼 = <yourAppClientID>
- 用戶端密碼 = <yourAppSecretValue>
- 範圍 = <YOUR ENDPOINT URL>/.default
- 讓用戶端驗證保持設定為傳送為基本驗證標頭
以下是產生權杖之前的樣子：
向下捲動頁面，直到找到取得新存取權杖按鈕。如果設定正確，選取按鈕就會開啟包含可用權杖的新視窗。
選取使用權杖。

張貼要求

現在您已通過驗證，您可以張貼實際的要求。

張貼您的要求，然後選取傳送。請參閱範例要求指南，以取得您可試用的其他預先設定 API 要求清單。
JSON 回應會出現在畫面底端：

注意

成功的回覆會在 JSON 回覆的項目區段中傳回項目的排名清單。在此案例中，最熱門項目的識別碼是 712。您可以在這裡檢視完整的 API 狀態碼清單。

使用 C# 程式碼呼叫端點

若要使用 C# 成功呼叫智慧建議端點，請準備下列資訊：

Microsoft Entra ID 租用戶識別碼
呼叫端應用程式用戶端識別碼
應用程式祕密值
HTTP 查詢，使用由有效的查詢路徑/參數組成的智慧建議帳戶服務端點 URL，如智慧建議 API 規格中所述

接下來，複製提供的範例程式碼、更新相關欄位，然後執行。

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); }
}

成功的回應會包含根據項目區段底下案例所建議項目的排名清單。在此案例中，最熱門項目的識別碼是 712。您可以在這裡檢視完整的 API 狀態碼清單。

透過 Azure Machine Learning 呼叫端點

若要使用 Azure Machine Learning 對智慧建議服務發出 API 要求，您可以使用此零售推薦系統 Jupyter Notebook。另有好處，此 Notebook 還包含將智慧建議與 Azure 個人化工具相結合的步驟！查看更多：零售推薦系統 Jupyter Notebook

另請參閱

智慧建議 API 參考
 API 狀態碼
 快速入門手冊：使用範例資料設定並執行智慧建議
 部署概觀
 使用資料合約來共用資料

共用方式為