AIP-155 请求标识

有时，由用户提供的唯一请求标识对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。

过时的成功应答

少数情况下，可能无法返回完全相同的成功应答。例如，创建资源的重发请求可能在资源创建和更新之后到达；由于服务往往不保留历史数据，因此不可能返回和之前完全相同的成功应答。

此时，方法 可以 返回资源的当前状态。即允许用反映最新数据的应答代替之前的成功应答。

进一步阅读

• 关于哪些代码需要重试，请参考AIP-194。
• 关于客户端库如何在失败时重试，请参考AIP-4221。

理由

使用UUID作为请求标识

在需要唯一值的时候，使用开放格式可能导致API消费者错误的发出重复的标识符。因此，为全局唯一标识符设置规范，可以大大减少程序正常执行时发生冲突的机会。

修订记录

• 2024-01-08 在请求消息中添加 book_id 。
• 2023-10-02 添加UUID格式扩展指南。
• 2019-08-01 将示例从 “shelves” 改为 “publishers”，提供更好的资源所有权示例。