使用 Microsoft Web IQ 驗證

使用 Microsoft Web IQ 執行時 API 有兩種認證方式。 使用 API 金鑰以最快啟動,並使用 Microsoft Entra ID 來處理生產工作負載。

Important

範圍管理使用客戶管理 API,該 API 需要應用程式專用的 Entra Bearer 權杖,並在預定帳單帳戶上另行授與 CustomerApiAccess 權限。 執行時設定檔綁定和搜尋 API 金鑰不會授予管理權限。 請參閱 使用 Scopes 篩選結果 以了解帳號管理員的存取授權步驟及範圍建立。

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 AppID 的數值。 執行時,你的應用程式會以其憑證換取 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。 輸入你的 Entra Application (Client) ID。 個人檔案更新同步可能需要長達一分鐘。

  3. 取得權杖 - 使用您偏好的 Microsoft 驗證資源庫(MSAL)用戶端認證授權流程:

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

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

Authorization: Bearer <access-token>

呼叫一個以上的 AppID

一個 Entra 應用程式(用戶端)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,而不是你的 Entra 應用程式(用戶端)ID。 當你連接 Web IQ 資源時,開發者入口網站會建立一個 AppID; 從設定檔管理複製。

你的 Entra 應用程式(用戶端)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 支援。