AIP-131 标准方法：Get

编号	131
原文链接	AIP-131: Standard methods: Get
状态	批准
创建日期	2019-01-22
更新日期	2022-06-02

在REST API中，通常通过向资源的URI（例如 /v1/publishers/{publisher}/books/{book} ）发出GET请求获取资源。

面向资源设计（AIP-121）提供Get方法，遵循这一模式。这些接口接受表示资源的URI，返回资源。

指南

API 必须 为资源提供Get方法。Get方法的目的是返回单个资源的数据。

Get方法使用以下模式注解：

rpc GetBook(GetBookRequest) returns (Book) {option (google.api.http) = {get: "/v1/{name=publishers/*/books/*}"};option (google.api.method_signature) = "name";
}

• 接口名字 必须 以单词Get开头，其余部分 应当 是资源消息名字的单数形式。
• 请求消息 必须 与接口名字一致，并带有 Request 后缀。
• 响应消息 必须 是资源本身。（没有 GetBookResponse ）
  • 响应 应当 通常包括完整资源内容，除非有充分理由返回部分数据（参考AIP-157）。
• HTTP动词 必须 是 GET 。
• URI 应当 包含与资源名字对应的单个变量域。
  • 域 应当 称为 name 。
  • URI 应当 有一个与这个域对应的变量。
  • name 域 应当 是URI路径中唯一的变量。所有其余参数 应当 映射到URI查询参数。
• google.api.http 注解中 不得 存在 body 键。
• 应当 只有一个google.api.method_signature注解，其值为"name"。

请求消息

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

message GetBookRequest {// The name of the book to retrieve.// Format: publishers/{publisher}/books/{book}string name = 1 [(google.api.field_behavior) = REQUIRED,(google.api.resource_reference) = {type: "library.googleapis.com/Book"}];
}

• 必须 包含一个资源名字域。域 应当 称为 name 。
  • 该域 应当 注解为必需域。
  • 该域 必须 标识其引用的资源类型。
• name 域的注释 应当 记录资源模式。
• 请求消息 不得 包含任何其他必需域， 不应 包含其他可选域（其他AIP要求的除外）。

注意： 请求对象中 name 域对应于接口注解 google.api.http 中的 name 变量。在使用REST/JSON接口时，请求中的 name 域将根据URL中的值进行填充。

错误

参考错误，特别是何时使用PERMISSION_DENIED和NOT_FOUND错误。

修订记录

• 2023-03-17 对齐AIP-122，让Get接口成为 必须 。
• 2022-11-04 将错误指南汇总到AIP-193。
• 2022-06-02 修改关于后缀的描述，消除多余的“-”。
• 2020-06-08 添加关于返回完整资源的指南。
• 2019-10-18 添加关于注释的指南。
• 2019-08-12 添加关于错误情况的指南。
• 2019-08-01 将示例从“shelves”改为“publishers”，提供更好的资源所有权示例。
• 2019-05-29 明确禁止在标准方法中使用任意域。