AIP-124 资源关联

编号	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...
}

注意： 只有在需要为关系提供额外的元数据，或者重复域的使用受到限制的情况下，才建议使用子资源为资源间关联建模。

修订记录

• 2021-04-07 ：明确资源引用域使用与被引用资源的 name 域相同的资源名字格式。

原文地址：https://blog.csdn.net/tq1086/article/details/145289762

免责声明：本站文章内容转载自网络资源，如侵犯了原著者的合法权益，可联系本站删除。更多内容请关注自学内容网（zxcms.com）！