REST 资源：projects.locations.operations

资源：Operation

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

JSON 表示法 

{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object(Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
字段
name

string

由服务器分配的名称，该名称仅在最初返回它的那项服务中是唯一的。如果您使用默认 HTTP 映射，则 name 的格式应为 operations/some/unique/name。

metadata

object

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

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标识相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。
done

boolean

如果值为 false，则表示操作仍在进行中。如果值为 true，则表示操作已完成，其结果不是 error 就是 response。

联合字段 result。操作结果，可以是 error，也可以是有效的 response。如果 done 为 false，则系统不会设置 error 和 response。如果 done 为 true，则系统会设置 error 和 response 中的一项。result 只能为以下项之一：
error

object(Status)

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

response

object

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

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标识相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

Status

Status 类型定义了适用于不同编程环境（包括 REST API 和 RPC API）的逻辑错误模型。此类型供 gRPC 使用。此错误模型的设计宗旨如下：

  • 方便大多数用户使用和理解
  • 足够灵活地应对意外需求

概览

Status 消息包含三部分数据：错误代码、错误消息和错误详细信息。错误代码应为 google.rpc.Code 的枚举值，但如果需要，也可以接受其他错误代码。错误消息应为向开发者显示的英语版消息，旨在帮助开发者理解并解决相关错误。如果需要提供向用户显示的本地化版错误消息，可以将本地化后的消息放入错误详细信息中，也可以在客户端中将该消息本地化。错误详细信息是可选项，其中可包含错误的任意相关信息。google.rpc 软件包中包含一组预定义的错误详细信息类型，可用于常见的错误情况。

语言映射

Status 消息是错误模型的逻辑表示形式，但它不一定是实际的传输格式。如果 Status 消息在不同的客户端库和不同的传输协议中公开，那么此消息的映射方式可能会有所不同。例如，此消息可能映射到 Java 中的某些异常，但更可能映射到 C 中的某些错误代码。

其他用途

此错误模型和 Status 消息可用于各种环境（无论是否使用 API），从而为处于不同环境的开发者提供一致的体验。

下面是此错误模型的一些示例运用：

  • 部分错误。如果服务需要将部分错误返回到客户端，则可以将 Status 嵌入正常响应中，以指示部分错误。

  • 工作流程错误。一个典型的工作流程包含多个步骤。每个步骤都有一条用于报告错误的 Status 消息。

  • 批量操作。如果客户端使用批量请求和批量响应，则应直接在批量响应中使用 Status 消息，使每个错误子响应与一条消息对应。

  • 异步操作。如果 API 调用将异步操作结果嵌入其响应中，则应直接使用 Status 消息表示这些操作的状态。

  • 日志记录。如果某些 API 错误存储在日志中，则在为确保安全/隐私而执行任何必要的删除操作之后，可以直接使用 Status 消息。

JSON 表示法 

{
  "code": number,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
字段
code

number

状态代码，应是 google.rpc.Code 的枚举值。

message

string

向开发者显示的错误消息（应采用英语）。任何向用户显示的错误消息都应进行本地化并通过 google.rpc.Status.details 字段发送，或者由客户端进行本地化。

details[]

object

包含错误详细信息的消息列表。有一组通用的消息类型可供 API 使用。

此对象可以包含任意类型的字段。附加字段 "@type" 包含用于标识相应类型的 URI。示例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

方法

cancel

 对长时间运行的操作启动异步取消。

delete

 删除长时间运行的操作。

get

 获取长时间运行的操作的最新状态。

list

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