当前位置：首页 > news >正文

AIP-155 请求标识

news 来源：原创 2025/6/14 16:07:09

编号	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。