AIP-124 资源关联

devtools/2025/1/22 13:38:45/

编号	124
原文链接	AIP-124: Resource association
状态	批准
创建日期	2020-03-20
更新日期	2020-03-20

有时无法用常规的树结构清晰表达API资源的层次结构。例如，一个资源可能与两个另外的资源类型之间存在多对一关系。或者一个资源可能与另一个资源类型存在多对多关系。

指南

资源必须至多有一个规范上级，并且 List 请求不得要求使用两个不同的“上级”才能工作。

数个多对一关联

如果资源与多个资源类型存在多对一关系，必须从中选择至多一个作为规范上级。资源可以通过其他域关联另外的资源。

message Book {// The resource name pattern for Book indicates that Publisher is the// canonical parent.option (google.api.resource) = {type: "library.googleapis.com/Book"pattern: "publishers/{publisher}/books/{book}"};// The resource name for the book.string name = 1 [(google.api.field_behavior) = IDENTIFIER];// The resource name for the book's author.string author = 2 [(google.api.resource_reference) = {type: "library.googleapis.com/Author"}];
}

在以这种方式列出具有多重关联的资源时，RPC 必须按照AIP-132要求，将 string parent 域作为必需域，并且不得添加其他的必需参数。RPC 应当按照AIP-160要求，包含 string filter 域，允许用户按其他资源关联进行过滤。

注意： 资源引用域必须与被引用资源的 name 域具有相同的资源名字格式。

多对多关联

相比数据库领域，多对多关联在API中较为少见，部分原因是它们难以在网络接口层面建模和表现。

API 可以包含多对多关系，应当使用包含资源名字列表的重复域，遵守AIP-144中描述的重复域原则。

message Book {option (google.api.resource) = {type: "library.googleapis.com/Book"pattern: "publishers/{publisher}/books/{book}"};string name = 1 [(google.api.field_behavior) = IDENTIFIER];// The resource names for the book's authors.repeated string authors = 2 [(google.api.resource_reference) = {type: "library.googleapis.com/Author"}];
}

注意： 有关重复域的更多信息，包括如何处理常见问题（如原子变更），请参考AIP-144。

如果重复域的使用受到限制，或者需要为关联提供更多元数据，API 可以使用子资源为多对多关系建模，子资源可以具有两个一对多关联。

message BookAuthor {// The resource pattern for BookAuthor indicates that Book is the// canonical parent.option (google.api.resource) = {type: "library.googleapis.com/BookAuthor"pattern: "publishers/{publisher}/books/{book}/authors/{book_author}"};// The resource name for the book-author association.string name = 1 [(google.api.field_behavior) = IDENTIFIER];// The resource name for the author.string author = 2 [(google.api.resource_reference) = {type: "library.googleapis.com/Author"}];// Other fields...
}