AIP-133 标准方法：Create

编号	133
原文链接	AIP-133: Standard methods: Create
状态	批准
创建日期	2019-01-23
更新日期	2019-01-23

在REST API中，通常向集合URI（如 /v1/publishers/{publisher}/books ）发出POST请求，在集合中创建新资源。

面向资源设计（AIP-121）提供Create方法，遵循这一模式。这些接口接受上级集合和欲创建资源（可能还有其他参数），返回新建的资源。

指南

API通常 应当 为资源提供Create方法，除非这个操作对用户没有意义。Create方法的目的是在现有集合中创建新资源。

Create方法使用以下模式指定：

rpc CreateBook(CreateBookRequest) returns (Book) {option (google.api.http) = {post: "/v1/{parent=publishers/*}/books"body: "book"};option (google.api.method_signature) = "parent,book";
}

• 接口的名字 必须 以单词Create开头，其余部分 应当 是目标资源的单数形式。
• 请求消息 必须 与接口名字一致，并带有 Request 后缀。
• 应答消息 必须 是资源本身。不存在 CreateBookResponse 。
  • 应答 应当 包括完整资源数据， 必须 包括所有支持的域，仅输入域除外（参考AIP-203）。
  • 如果Create接口是长运行创建，应答消息 必须 是解析为资源本身的 google.longrunning.Operation 。
• HTTP动词必须是 POST 。
• 添加新资源的集合 应当 映射到URI路径。
  • 集合的上级资源 应当 称为 parent ， 应当 是URI路径中唯一的变量。
  • 集合标识符（例子中的 books ） 必须 是字面值字符串。
• google.api.http 注解中 必须 包含 body 键， 必须 映射到请求消息中的资源域。
  • 所有其他域 应当 映射到URI查询参数。
• 应当 存在一个 google.api.method_signature 注解，值为 "parent,{resource},{resource}_id" 。如果不需要资源I标识，值为 "parent,{resource}" 。
• 如果API在[BROKEN LINK: 管理平面]上运行，则操作应具有[BROKEN LINK: 强一致性]：创建操作的完成必须意味着所有用户可设置的值和资源的存在已达到稳定状态，并且读取资源状态返回一致的应答。

请求消息

创建方法实现了一个常见的请求消息模式：

```proto message CreateBookRequest { / 将在其中创建此书籍的上级资源。 / 格式：publishers/{publisher} string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { child_type: “library.googleapis.com/Book” }];

/ 用于书籍的ID，将成为书籍资源名字的最终组成部分。 / / 此值应为4-63个字符，有效字符为[a-z][0-9]-/。 string book_id = 2 [(google.api.field_behavior) = REQUIRED];

// 要创建的书籍。 Book book = 3 [(google.api.field_behavior) = REQUIRED]; } ```

• 必须包含一个parent域，除非正在创建的资源是顶级资源。它应称为parent。
  • 该域应被注释为必需（[BROKEN LINK: AIP-203]）。
  • 该域必须标识正在创建的资源的[BROKEN LINK: 资源类型]（[BROKEN LINK: AIP-123]）。
• 对于管理平面资源，必须包含{resource}_id域，对于数据平面资源，应包含该域。
• 必须包含资源域，并且必须映射到POST主体。
• 请求消息不得包含任何其他必需域，并且不应包含其他可选域，除非在此或另一个AIP中描述。

长运行创建

某些资源创建资源所需的时间比常规API请求合理的时间长。在这种情况下，API应使用长运行操作（[BROKEN LINK: AIP-151]）：

```proto rpc CreateBook(CreateBookRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: “/v1/{parent=publishers/*}/books” body: “book” }; option (google.longrunning.operation_info) = { response_type: “Book” metadata_type: “OperationMetadata” }; } ```

• 应答类型必须设置为资源（如果接口不是长运行，则返回类型将是该资源）。
• 必须指定response_type和metadata_type域。

重要提示： 声明友好资源（[BROKEN LINK: AIP-128]）应使用长运行操作。如果请求实际上是立即的，则服务可以返回已设置为完成的LRO。

用户指定的ID

如果API在[BROKEN LINK: 管理平面]上运行，则API必须允许用户在创建时指定资源的ID组件（资源名字的最后一段）。

在[BROKEN LINK: 数据平面]上，API应允许用户指定ID。特殊情况应具有以下行为：

• 数据平面资源允许相同的记录，无需区分两者（例如，没有主键的表中的行）。
• 数据平面资源不会在[BROKEN LINK: 声明客户端]中公开。

API可以允许{resource}_id域具有[BROKEN LINK: field_behavior] OPTIONAL，并在未指定时生成系统生成的ID。

例如：

``` // 使用用户指定的ID。 publishers/lacroix/books/les-miserables

// 使用系统生成的ID。 publishers/012345678-abcd-cdef/books/12341234-5678-abcd ```

• {resource}_id域必须存在于请求消息上，而不是资源本身。
  • 该域可以是必需的或可选的。如果它是必需的，则应包括相应的注释。
• 必须忽略资源上的name域。
• 接口上应恰好有一个google.api.method_signature注释，如果正在创建的资源不是顶级资源，则其值为"parent,{resource},{resource}_id"，如果正在创建的资源是顶级资源，则其值为"{resource},{resource}_id"。
• 文档应解释可接受的格式是什么，并且格式应遵循[BROKEN LINK: AIP-122]中资源名字格式的指南。
• 如果用户尝试创建具有会导致重复资源名字的ID的资源，则服务必须返回ALREADY_EXISTS错误。
  • 但是，如果进行调用的用户没有权限查看重复资源，则服务必须返回PERMISSION_DENIED错误。

注意： 对于REST API，用户指定的ID域{resource}_id作为请求URI上的查询参数提供。

错误

参考错误，特别是[BROKEN LINK: 何时使用PERMISSION_DENIED和NOT_FOUND错误]。

进一步阅读

• 有关在Create方法中确保幂等性，请参考[BROKEN LINK: AIP-155]。
• 有关涉及Unicode的资源命名，请参考[BROKEN LINK: AIP-210]。

理由

要求用户指定的ID

[BROKEN LINK: 声明客户端]使用资源ID作为应用更新和冲突解决的一种方式。缺少用户指定的ID意味着客户端无法找到资源，除非他们在本地存储标识符，并且可能导致重新创建资源。这反过来又对所有引用它的资源产生下游影响，迫使它们更新到新创建资源的ID。

拥有用户指定的ID还意味着客户端可以预先计算资源名字并在其他资源的引用中使用它。

修订记录

• 2023-10-20 澄清{resource}_id仅对管理平面资源是必需的。
• 2023-08-24 添加一致性要求。
• 2023-05-11 更改关于resource_id的指南为必须。
• 2022-11-04 引用AIP-193中的聚合错误指南，类似于其他CRUDL AIP。
• 2022-06-02 更改后缀描述以消除多余的“-”。
• 2020-10-06 添加声明友好指南。
• 2020-08-14 更新错误指南以使用permission denied而不是forbidden。
• 2020-06-08 添加关于返回完整资源的指南。
• 2019-11-22 添加关于发送重复名字时使用何种错误的澄清。
• 2019-10-18 添加关于注释的指南。
• 2019-08-01 将示例从“shelves”更改为“publishers”，以提供更好的资源所有权示例。
• 2019-06-10 添加长运行创建的指南。
• 2019-05-29 添加对标准方法中任意域的明确禁止。