AIP-131 标准方法：Get
·
[tommwq@126.com]
| 编号 | 131 |
|---|---|
| 原文链接 | https://google.aip.dev/131 |
| 状态 | 批准 |
| 创建日期 | 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错误。