范围管理 REST API 参考

Microsoft Web IQ 客户管理 API 创建、读取、更新和删除 Web IQ 计费帐户的命名搜索范围。 有关端到端门户或 API 演练,请参阅 “使用范围筛选结果”。

基 URL:https://api.microsoft.ai

收集路由:/v1/customer/billing-accounts/{billingAccountId}/scopes

身份验证和标头

工作负荷需要有效的Microsoft Entra标识,并且CustomerApiAccess需要目标计费帐户。 使用 https://api.microsoft.ai/.default.. 请求仅限应用的令牌。 使用授权资源发现进行选择billingAccountId;不要替换客户 ID、Azure订阅 ID、Web IQ AppID 或 Entra 应用程序(客户端)ID。

Header Use
Authorization: Bearer <access-token> 每个管理请求都是必需的。 这些调用不支持搜索 API 密钥。
Content-Type: application/json 发送 JSON 正文时是必需的。
Accept: application/json 请求 JSON 响应。
If-Match: "<current-etag>" 替换、增量编辑和删除所必需的。 从范围读取或写入中复制完整的强 ETag(包括引号)。

Operations

下面的路径相对于集合路由。

Method 路径 成功 Description
POST 集合路由 201、定义、 ETag、、 Location 创建命名范围。
GET 集合路由 200,元数据页 列出范围名称、计数和时间戳,不带选择器数组。
GET /{name} 200、定义、 ETag 读取完整的选择器数组和元数据。
GET /{name}/summary 200、元数据、 ETag 在没有选择器数组的情况下读取计数和时间戳。
GET /{name}/includeSites 或 /{name}/excludeSites 200、网站页、 ETag 第一页选择器列表。
PUT /{name} 200、定义、 ETag 替换这两个数组;要求 If-Match。
POST /{name}/includeSites:add 或 /{name}/excludeSites:add 204、ETag 将选择器添加到一个列表;要求 If-Match。
POST /{name}/includeSites:remove 或 /{name}/excludeSites:remove 204、ETag 从一个列表中删除选择器;要求 If-Match。
DELETE /{name} 204 永久删除范围;要求 If-Match。

范围名称标识帐户分配的范围集合中的资源。 帐户中的 Web IQ AppID 使用该集合。 分配给同一集合共享名称、定义和更改的帐户。

创建范围

POST /v1/customer/billing-accounts/<billingAccountId>/scopes HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}
请求字段 Required 类型 Description
name Yes 字符串 剪裁后的 1-128 个字符;ASCII 字母、数字、.和 _-。 集合中不区分大小写的唯一性。
includeSites Yes 字符串数组 包含的选择器。 用于 [] 有意为空包含,该包含允许所有非排除源。
excludeSites Yes 字符串数组 排除的选择器。 排除优先于包含,而不考虑具体性。

这两个数组必须存在。 省略属性或发送 null 不等效 []。

HTTP 201 Created 返回规范化定义和下面的响应标头。 创建不是更新或重命名:返回重复的不区分大小写的名称 409 Conflict。

响应标头 Description
ETag 强引用的创作并发令牌。 保留将来 If-Match 请求的确切值。 不是服务就绪或服务版本令牌。
Location 所请求计费帐户路由上已创建范围的根相对 URI。

响应字段

完整定义包含以下所有字段。 元数据响应省略 includeSites 和 excludeSites。

领域 类型 Description
billingAccountId string (UUID) 请求中使用的计费帐户。
name 字符串 作用域名称,保留显示大小写。 查找不区分大小写。
includeSites 字符串数组 完整、规范化的包含选择器。
excludeSites 字符串数组 完成规范化的排除选择器。
includedSiteCount 整数 规范化唯一选择器的数量。
excludedSiteCount 整数 规范化唯一排除的选择器数。
createdAt string (date-time) 以 UTC 为单位的创建时间。
updatedAt string (date-time) UTC 的上次更新时间。

列出和读取范围

用于 GET /v1/customer/billing-accounts/{billingAccountId}/scopes/{name} 完整定义及其当前 ETag。 追加 /summary 到只读元数据和计数。

用于 GET /v1/customer/billing-accounts/{billingAccountId}/scopes?pageSize=50 列出范围。 响应包含元数据 items 对象和可选 nextContinuationToken对象。

查询参数 适用对象 Values
pageSize 范围列表 1-100;默认值 50。
pageSize 包含或排除的选择器列表 1-1,000;默认值 100。
continuationToken 任一列表类型 该列表上一页中的不透明令牌。 将其传递不变,并允许 HTTP 客户端 URL 对其进行编码。

继续,直到 nextContinuationToken 不存在或 null。 范围元数据按规范化名称顺序列出,而不是在并发编辑期间作为保证的快照。

若要页面选择器,请调用 GET .../scopes/{name}/includeSites 或 GET .../scopes/{name}/excludeSites。 每个响应都包含 sites、 totalCountETag nextContinuationToken标头和 ETag 标头。 选择器页面遵循规范选择器顺序。 保留具有相同作用域和列表的令牌。 如果编辑使选择器令牌过时,请求将 412返回;放弃部分枚举并从第一页重启。

更新或删除范围

PUT 替换完整的数组,并且不重命名范围:

PUT /v1/customer/billing-accounts/<billingAccountId>/scopes/ProductDocs HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: "<current-etag>"

{
  "includeSites": ["example.com"],
  "excludeSites": ["ads.example.com", "example.com/archive"]
}

若要更改一个列表而不替换另一个列表,请将相应的 :add 或 :remove 路由与数组一 sites 起使用:

POST /v1/customer/billing-accounts/<billingAccountId>/scopes/ProductDocs/excludeSites:add HTTP/1.1
Host: api.microsoft.ai
Authorization: Bearer <access-token>
Content-Type: application/json
If-Match: "<current-etag>"

{
  "sites": ["example.com/archive"]
}

提供 1-10,000 个提交的条目。 生成的列表仍必须满足其唯一选择器和定义大小限制。 添加已存在的规范选择器或删除缺席选择器是 no-op。 完全 no-op 请求会保留 ETag。 成功的增量突变使用当前 ETag 和无 JSON 正文返回 204 。

用于DELETE .../scopes/{name}If-Match永久删除范围。 首先从调用方中删除依赖项。 没有软删除或还原终结点,删除会异步传播。 对于共享集合,删除会影响所有分配的帐户。

并发和不确定结果

替换、增量编辑和删除需要当前的强 ETag。 请勿删除其引号、从时间戳构造它,或使用弱、通配符或多个标记。

打开 412 Precondition Failed,阅读最新定义,将预期更改与其他编写器的更改协调,并使用最新的 ETag 重试。 不要盲目覆盖最新定义。 428 Precondition Required means If-Match 缺失。

如果写入超时或连接断开,请在重试之前读取资源。 创建可能在超时前成功,使重试返回 409;编辑可能已更改 ETag,从而返回 412重试。 检查删除时,请将真正的缺席与授权失败区分开来。

限制和选择器验证

约束 限制或行为
Name 剪裁后的 1-128 个字符;ASCII 字母、数字、.和 _-。
每个选择器列表 最多 10,000 个规范化的唯一选择器。 每个数组最多发送 10,000 个非重复条目。
每个选择器 剪裁前和规范化后最多 2,048 个字符。
路径深度 没有单独的子目录或段计数限制,受选择器长度和组合定义大小的约束。
组合定义 默认 3,670,016 字节(3.5 MiB),从序列化的服务定义(包括列表和元数据)估计。 不是原始 HTTP 请求正文大小。
增量添加/删除正文 1-10,000 个提交的条目 sites。

该集合还具有范围计数限制。 409 可以指示已用尽的容量以及重复名称;检查错误和现有清单。 请联系 Web IQ 支持 部门,了解帐户的有效容量。

支持的选择器包括 DNS 域(example.com以及所有后代子域)、IPv4 主机()、路径前缀(192.0.2.10example.com/products/guides在该主机的路径段边界上),以及确切的 HTTPS URL(https://example.com/products/guide)。 添加方案会将路径前缀更改为确切的 URL。

将拒绝通配符、显式端口、查询字符串、片段、用户信息、IPv6、点段和编码路径分隔符。 原始非 ASCII 路径字符必须经过 UTF-8% 编码。

规范化剪裁周围的空格、小写主机、保留路径大小写、排序规范选择器,并单独删除每个列表。 条目可以出现在这两个列表中;排除始终获胜。 空包含允许所有非排除源。 这两个数组为空意味着范围本身不会施加站点限制。

状态代码和错误

管理错误使用 与 v3 搜索错误响应不同的协定。

Status Meaning Action
400 名称、正文、选择器、分页、定义大小或 If-Match 格式无效。 更正输入;不要更改重试。
401 身份验证缺失或无效。 检查令牌过期和 https://api.microsoft.ai/.default 令牌请求范围。
403 主体或帐户授权被拒绝。 验证工作负荷的活动标识和 CustomerApiAccess 帐户。
404 找不到请求的范围或计费帐户。 检查帐户和名称。 授权可以在披露存在之前拒绝请求。
409 重复的名称或耗尽的收集容量。 读取现有清单和错误详细信息;不要盲目重试创建。
412 过时的 ETag 或过时的选择器页令牌。 重新读取和协调编辑,或重启选择器分页。
428 缺少必需 If-Match 项。 读取资源并发送其当前引用的强 ETag。
500 服务或依赖项失败。 对读取使用有限重试;协调不确定的写入首先。

作用域验证、未找到、冲突和并发错误使用此 JSON 形状:

{
  "code": "NotFound",
  "message": "The requested scope was not found."
}

稳定code值包括InvalidRequest、NotFound、Conflict和PreconditionFailedPreconditionRequired。 也可以存在 A subCode 。 对 HTTP 状态 code进行分支,而不是诊断分支 message,接受未知代码和字段。 格式不正确或无效的请求正文可以改为返回 application/problem+json 验证详细信息。 401 没有 403 正文;依赖项失败可以使用其他形状。

搜索传播

成功的管理写入或读取并不能证明最新定义在搜索中处于活动状态。 传播是异步进行的。 完全全局传播通常需要大约 10 分钟,但在某些情况下最多可能需要 30 分钟。 目前没有传播 SLA,无法保证这些计时。 目前还没有就绪性终结点或范围版本控制。 创作 ETag 和运行时 scopeApplied: true 不会标识当前提供的版本。

有关就绪情况检查和新名称替换策略,请参阅 使用范围之前验证范围。