怎样在华为云服务器里建设网站短网址工具
| 编号 | 155 |
|---|---|
| 原文链接 | AIP-155: Request identification |
| 状态 | 批准 |
| 创建日期 | 2019-05-06 |
| 更新日期 | 2019-05-06 |
有时，由用户提供的唯一请求标识对API是有用的。在很多场景下，例如并行处理时排除重复请求、提供安全的重试、或进行审计时都很有用。
请求标识的最重要的目标是提供幂等性保证：允许多次发出同一个请求，而后续调用不会产生任何实际影响。在网络故障时，客户端可以重发请求，服务器可以检测重复的请求，保证请求只被处理一次。
指南
API 可以 在请求消息（包括标准方法请求消息）中添加 string request_id 参数，唯一标识请求。
message CreateBookRequest {// The parent resource where this book will be created.// Format: publishers/{publisher}string parent = 1 [(google.api.field_behavior) = REQUIRED,(google.api.resource_reference) = {child_type: "library.googleapis.com/Book"}];// The ID to use for the book, which will become the final component of// the book's resource name.//// This value should be 4-63 characters, and valid characters// are /[a-z][0-9]-/.string book_id = 2 [(google.api.field_behavior) = REQUIRED];// The book to create.Book book = 3 [(google.api.field_behavior) = REQUIRED];// A unique identifier for this request. Restricted to 36 ASCII characters.// A random UUID is recommended.// This request is only idempotent if a `request_id` is provided.string request_id = 4 [(google.api.field_info).format = UUID4];
}
- 如果提供请求标识， 必须 保证幂等性。
- 如果检测到重发的请求，服务器 应当 返回之前成功请求的应答，因为客户端很可能没有收到之前的应答。
- API 可以 可以选择任意合理时长作为请求标识的有效期。
request_id域 必须 包含在适用的请求消息中（ 不得 作为资源自身域）。- 请求标识 应当 是可选的。
- 请求标识 应当 支持 UUID，也 可以 要求 UUID 是唯一有效格式。请求标识的格式限制 必须 记录在文档中。
- 如果以UUID作为请求标识， 必须 添加扩展注解
(google.api.field_info).format = UUID4。更多信息参考AIP-202。
- 如果以UUID作为请求标识， 必须 添加扩展注解
过时的成功应答
少数情况下，可能无法返回完全相同的成功应答。例如，创建资源的重发请求可能在资源创建和更新之后到达；由于服务往往不保留历史数据，因此不可能返回和之前完全相同的成功应答。
此时，方法 可以 返回资源的当前状态。即允许用反映最新数据的应答代替之前的成功应答。
进一步阅读
- 关于哪些代码需要重试，请参考AIP-194。
- 关于客户端库如何在失败时重试，请参考AIP-4221。
理由
使用UUID作为请求标识
在需要唯一值的时候，使用开放格式可能导致API消费者错误的发出重复的标识符。因此，为全局唯一标识符设置规范，可以大大减少程序正常执行时发生冲突的机会。
修订记录
- 2024-01-08 在请求消息中添加
book_id。 - 2023-10-02 添加UUID格式扩展指南。
- 2019-08-01 将示例从 “shelves” 改为 “publishers”，提供更好的资源所有权示例。