Package google.longrunning

索引

操作

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

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

CancelOperation

rpc CancelOperation(CancelOperationRequest) returns (Empty)

取消转移。使用 transferOperations.get 方法检查取消操作是否成功，或者操作是否在 cancel 请求后完成。

取消操作后，当前正在运行的传输会中断。对于周期性转移作业，转移作业的下一个实例仍会运行。例如，如果您的作业配置为每天下午 1 点运行，而您在下午 1:05 取消了周一的操作，则周一的转移将停止。不过，系统仍会在周二尝试执行转移作业。

这仅适用于当前正在运行的操作。如果当前没有运行任何操作，cancel 不会执行任何操作。

取消作业后，下一个作业会计算文件的增量，并可能会修复任何不一致的状态。例如，如果您每天运行一个作业，并且今天的作业在您取消作业之前找到了 10 个新文件并转移了 5 个文件，那么明天的传输操作将根据今天未复制的 5 个文件以及明天发现的所有新文件计算出新的增量。

授权范围

需要以下 OAuth 范围：

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

如需了解详情，请参阅 Authentication Overview。
GetOperation

rpc GetOperation(GetOperationRequest) returns (Operation)

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

授权范围

需要以下 OAuth 范围：

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

如需了解详情，请参阅 Authentication Overview。
ListOperations

rpc ListOperations(ListOperationsRequest) returns (ListOperationsResponse)

列出传输操作。操作会按创建时间（从晚到早）排序。

授权范围

需要以下 OAuth 范围：

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

如需了解详情，请参阅 Authentication Overview。

CancelOperationRequest

Operations.CancelOperation 的请求消息。

字段
name

string

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

GetOperationRequest

Operations.GetOperation 的请求消息。

字段
name

string

操作资源的名称。

ListOperationsRequest

Operations.ListOperations 的请求消息。

字段
name

string

必需。要列出的类型的名称；必须为 transferOperations。
filter

string

必需。以 JSON 文本的形式指定的查询参数列表，格式为：{"projectId":"my_project_id", "jobNames":["jobid1","jobid2",...], "jobNamePattern": "job_name_pattern", "operationNames":["opid1","opid2",...], "operationNamePattern": "operation_name_pattern", "minCreationTime": "min_creation_time", "maxCreationTime": "max_creation_time", "transferStatuses":["status1","status2",...]}

由于 jobNames、operationNames 和 transferStatuses 支持多个值，因此必须使用数组表示法指定它们。projectId 是唯一的必需参数。如果指定了 jobNamePattern 和 operationNamePattern，则它们必须分别与完整作业名称或操作名称相匹配。“*”是与零个或多个字符匹配的通配符。minCreationTime 和 maxCreationTime 应为编码为 RFC 3339 格式字符串的时间戳。transferStatuses 的有效值不区分大小写：IN_PROGRESS、PAUSED、SUCCESS、FAILED 和 ABORTED。
page_size

int32

列表页面大小。允许的最大值为 256。
page_token

string

列表页面令牌。

ListOperationsResponse

Operations.ListOperations 的响应消息。

字段
operations[]

Operation

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

string

标准列表下一页令牌。

操作

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

字段
name

string

由服务器分配的唯一名称。name 的格式为 transferOperations/some/unique/name。
metadata

Any

表示转移操作对象。如需请求 TransferOperation 对象，请使用 transferOperations.get。
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。