AIP-159 跨集合读

编号	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”，提供更好的资源所有权示例。