使用 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>应用注册>你的应用>概述下找到它。

  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
一个AppID 缺少，或该 AppID 无效 请求成功
一个AppID 另一个 AppID HTTP 403 AuthUnauthorizedAppId
多个 AppID 缺失或为空 HTTP 400 AuthAppIdSelectionRequired
多个 AppID 绑定的 AppID 之一 请求成功
多个 AppID 任何其他 AppID HTTP 403 AuthUnauthorizedAppId
无 AppID Any 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 支持发送技术问题或反馈。

  • 上次更新时间为