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 不会标识当前提供的版本。
有关就绪情况检查和新名称替换策略,请参阅 使用范围之前验证范围。