临沭县建设局官方网站百度地图人工电话
| 编号 | 159 |
|---|---|
| 原文链接 | AIP-159: Reading across collections |
| 状态 | 批准 |
| 创建日期 | 2019-07-26 |
| 更新日期 | 2019-07-26 |
有时，用户需要跨集合检索资源，或者在不知道资源所在集合的情况下检索单个资源。
指南
API 可以 在标准 List 方法中允许用户使用 - （连字符或破折号）作为通配符，支持跨集合读资源：
GET v1/publishers-/books?filter=…
- URI模式 必须 使用
*，可以表示集合。URI 模式 不得 使用-字符硬编码。 - 方法 必须 在文档中明确记录支持此行为。
- 应答中提供的资源 必须 使用资源的规范名字，带有实际的上级集合标识符（而非
-）。 - 服务 可以 在
List请求中支持跨集合读，无论下级资源标识符是否保证唯一。但是，如果下级资源可能冲突，服务 不得 在Get请求中支持跨集合读。 - 跨上级资源请求 不应 支持
order_by。如果要这么做， 必须 在域文档中说明这是不得已之举。因为跨上级资源请求让排序规则产生了歧义，特别在难以访问上级资源时（参考 AIP-217）。
重要 如果跨集合
List方法资源由于无法访问的上级资源（例如跨位置List）而导致部分失败，方法 必须 按照 AIP-217 指南表明这一点。
唯一资源查找
有时，下级集合中的资源具有跨上级集合唯一的标识符。此时，让 Get 方法在不知道所属上级集合的情况下检索资源，是有用的。API 可以 允许用户指定通配符集合标识 - （连字符或破折号）表示任何上级集合：
GET https://example.googleapis.com/v1/publishers/-/books/{book}
- URI模式 必须 使用
*，可以表示集合。URI 模式 不得 使用-字符硬编码。 - 方法 必须 在文档中明确记录支持此行为。
- 应答中提供的资源 必须 使用资源的规范名字，带有实际的上级集合标识符（而非
-）。例如，上述请求返回的资源名字类似于publishers/123/books/456，而非publishers/-/books/456。 - 资源标识 必须 在上级集合中唯一。
进一步阅读
- 关于由于无法访问资源而导致的部分失败，请参考 AIP-217。
修订记录
- 2019-08-26 添加对无法访问资源指南的引用。
- 2019-08-01 将示例从“shelves”改为“publishers”，提供更好的资源所有权示例。