Package google.longrunning

索引

运维

使用 API 服务管理长时间运行的操作。

如果某个 API 方法通常需要很长时间才能完成，您可以将其设计为向客户端返回 Operation，而客户端可以使用此接口通过轮询操作资源来异步接收实际响应，或者将操作资源传递给另一个 API（例如 Pub/Sub API）来接收响应。任何返回长时间运行操作的 API 服务都应实现 Operations 接口，以便为开发者提供一致的客户端体验。

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty)

对长时间运行的操作启动异步取消。服务器会尽全力取消操作，但不能保证一定成功。如果服务器不支持此方法，则会返回 google.rpc.Code.UNIMPLEMENTED。客户端可以使用 Operations.GetOperation 或其他方法来检查操作是已成功取消还是仍然完成了。成功取消后，操作不会被删除，而会变成一个具有 Operation.error 值且 google.rpc.Status.code 为 1（对应于 Code.CANCELLED）的操作。

授权范围

需要以下 OAuth 作用域：

  • https://www.googleapis.com/auth/cloud-platform
DeleteOperation

rpc DeleteOperation(DeleteOperationRequest) returns (Empty)

删除长时间运行的操作。此方法只是表明客户端不再关注操作结果，而不会取消操作。如果服务器不支持此方法，则会返回 google.rpc.Code.UNIMPLEMENTED。

授权范围

需要以下 OAuth 作用域：

  • https://www.googleapis.com/auth/cloud-platform
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

获取长时间运行的操作的最新状态。客户端可以使用此方法，按 API 服务建议的时间间隔来轮询操作结果。

授权范围

需要以下 OAuth 作用域：

  • https://www.googleapis.com/auth/cloud-platform
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

列出与请求中指定的过滤条件匹配的操作。如果服务器不支持此方法，则会返回 UNIMPLEMENTED。

授权范围

需要以下 OAuth 作用域：

  • https://www.googleapis.com/auth/cloud-platform
WaitOperation

rpc WaitOperation(WaitOperationRequest) returns (Operation)

等待指定的长时间运行的操作完成或最多达到指定的超时时间，返回最新状态。如果操作已完成，则立即返回最新状态。如果指定的超时大于默认的 HTTP/RPC 超时，则使用 HTTP/RPC 超时。如果服务器不支持此方法，则会返回 google.rpc.Code.UNIMPLEMENTED。请注意，此方法会尽力执行命令。它可能会在未达到指定的超时之前返回最新状态（包括立即返回），也就是说，即使立即收到响应，也并不保证操作已完成。

授权范围

需要以下 OAuth 作用域：

  • https://www.googleapis.com/auth/cloud-platform

CancelOperationRequest

Operations.CancelOperation 的请求消息。

字段
name

string

要取消的操作资源的名称。

DeleteOperationRequest

Operations.DeleteOperation 的请求消息。

字段
name

string

要删除的操作资源的名称。

GetOperationRequest

Operations.GetOperation 的请求消息。

字段
name

string

操作资源的名称。

ListOperationsRequest

Operations.ListOperations 的请求消息。

字段
name

string

操作的父级资源名称。
filter

string

标准列表过滤条件。
page_size

int32

标准列表页面大小。
page_token

string

标准列表页面令牌。

ListOperationsResponse

Operations.ListOperations 的响应消息。

字段
operations[]

Operation

与请求中指定的过滤条件匹配的操作列表。
next_page_token

string

标准列表下一页令牌。

操作

此资源表示由网络 API 调用引发的长时间运行的操作。

字段
name

string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 应是以 operations/{unique_id} 结尾的资源名称。
metadata

Any

与操作关联的服务专属元数据。它通常包含进度信息和常见元数据（如创建时间）。一些服务可能不会提供此类元数据。任何返回长时间运行操作的方法都应记录元数据类型（如果有的话）。
done

bool

如果值为 false，则表示操作仍在进行中。如果为 true，则表示操作已完成，其结果不是 error 就是 response。
联合字段 result。操作结果，可以是 error，也可以是有效的 response。如果 done == false，则既不会设置 error，也不会设置 response。如果 done == true，则可以设置 error 或 response 中的一个。某些服务可能不会提供结果。result 只能是下列其中一项：
error

Status

操作失败或被取消时表示有错误发生的结果。
response

Any

操作的正常成功响应。如果原始方法在成功时不返回任何数据（如 Delete），则响应为 google.protobuf.Empty。如果原始方法为标准 Get/Create/Update 方法，则响应应该为资源。对于其他方法，响应类型应为 XxxResponse，其中 Xxx 是原始方法的名称。例如，如果原始方法名称为 TakeSnapshot()，则推断的响应类型为 TakeSnapshotResponse。

WaitOperationRequest

Operations.WaitOperation 的请求消息。

字段
name

string

要等待的操作资源的名称。
timeout

Duration

超时之前等待的最长时间。如果将此字段留空，则等待时间最长为底层 HTTP/RPC 协议允许的时间。如果还指定了 RPC 上下文截止时间，则以二者中较短者为准。