使用 Microsoft Web IQ 驗證

有兩種方式可以驗證並取得 Microsoft Web IQ API 的存取權限。 使用 API 金鑰以最快啟動，並使用 Microsoft Entra ID 來處理生產工作負載。

API 金鑰

在 Microsoft Web IQ 入口網站建立 API 金鑰，以向 Microsoft Web IQ API 驗證身分。 在每個請求中於標頭傳遞它：x-apikey

x-apikey: <YOUR_API_KEY>

Warning

API 金鑰會授予你帳戶的完整存取權限。 把它們存在秘密管理器裡，不要儲存在用戶端程式碼中，也不要放在版本控制中。

Microsoft Entra ID

使用 Microsoft Entra ID OAuth 2.0 用戶端憑證（僅限應用程式權杖）來驗證 Microsoft Web IQ API。

Note

Microsoft Entra ID 是身分平台。 應用程式註冊有一個 應用程式（用戶端）ID，用來識別你租戶中的應用程式，且這是你綁定到 Web IQ 帳號的值。 執行時，你的應用程式會以其憑證換取 Microsoft Entra 存取權杖，並隨每個 API 要求一併傳送該權杖。

Prerequisites

  1. 設立租戶：要註冊你的應用程式，需要一個 Azure 租戶。 Azure 訂閱並非必須，但如果您的組織已有一個或多個 Azure 訂閱，或是 Microsoft 365 組織，那麼您已經擁有 Azure 租戶。 否則，請佈建新的租用戶。

  2. 建立應用程式註冊：應用程式註冊建立了您的應用程式與 Microsoft 身分識別平台 之間的信任關係，使您的應用程式能夠安全驗證並存取資源。

    當你註冊應用程式時，會建立客戶端 ID、物件 ID 和目錄 ID。 要建立應用程式註冊的認證，請參閱《使用 Microsoft 身分識別平台註冊應用程式》。

Entra ID 設定步驟

  1. 應用程式註冊 - 使用現有的 Microsoft Entra ID 應用程式註冊或建立一個。 記錄其 應用程式（用戶端）ID。 在 Azure 入口網站中，在 Microsoft Entra ID>應用程式註冊>your app>Overview 下方找到它。

  2. 綁定您的應用程式註冊 - 前往 設定檔管理，選擇 應用程式（客戶端）ID 標籤， 然後選擇 綁定應用程式（客戶端）ID。 輸入你的應用程式（客戶）ID。 個人檔案更新同步可能需要長達一分鐘。

    Note

    如果應用程式（客戶端）ID標籤無法使用，您的試用版可能未啟用 Microsoft Entra ID 認證。 請聯絡您的 Microsoft 代表申請專屬存取權限。

  3. 取得權杖 - 使用您偏好的 Microsoft 驗證資源庫（MSAL）用戶端認證授與：

    • 授權單位：https://login.microsoftonline.com/{your-tenant-id}
    • 範圍：https://api.microsoft.ai/.default

接著在每個 Web IQ 請求中傳遞存取權杖：

Authorization: Bearer <access-token>

呼叫一個以上的 AppID

一個應用程式（用戶端）ID 可以綁定到多個 Web IQ AppID，例如每個 Web IQ 資源或每個工作負載一個 AppID。 在這種情況下，請在每個請求中加入 APPID 查詢參數，以選擇呼叫所使用的 AppID。 速率限制會占用該 AppID 的額度。

POST https://api.microsoft.ai/v3/search/web?APPID=<your-web-iq-appid>
Authorization: Bearer <access-token>
Content-Type: application/json

APPID 它會取得你的 Web IQ AppID，而不是應用程式（用戶端）ID。 您的 Microsoft 聯絡人提供您的 Web IQ AppID。

您的應用程式（客戶端）ID 綁定到 APPID 根據該請求 Result
One AppID 缺少或 AppID 請求會成功
One AppID 不同的 AppID HTTP 403 AuthUnauthorizedAppId
多個 AppID 缺失或空值 HTTP 400 AuthAppIdSelectionRequired
多個 AppID 你綁定的 AppID 之一 請求已成功
多個 AppID 任何其他 AppID HTTP 403 AuthUnauthorizedAppId
沒有 AppID 任意 HTTP 401 AuthUnauthorizedEntryId

Warning

API 金鑰不接受APPID。 每個 API 金鑰都屬於一個 AppID。 包含 APPID 參數（即使為空）的金鑰認證請求，也會回傳 HTTP 401 AuthUnauthorizedEntryId。

請求標頭

Header Value Description
x-apikey 或 Authorization <your-api-key> 或 Bearer <access-token> 你的 API 金鑰或 Microsoft Entra ID 存取權杖用於認證
Content-Type application/json 要求本文格式

下一步

支援和意見反應

如有技術問題或回饋，請將技術問題或回饋寄給 Web IQ 支援。

  • 上次更新時間：