tommwq.work/aip

AIP-152 作业

· [tommwq@126.com]
编号 152
原文链接 https://google.aip.dev/152
状态 批准
创建日期 2020-04-27
更新日期 2020-04-27

偶尔API会发布需要很长时间才能完成的任务，但一次性的耗时操作并不适用。例如，一个任务可能需要反复运行，或者配置任务和运行任务需要不同的权限。

指南

API 可以 定义 Job 资源，表示一个特定的任务，具有独立的设置、配置和执行：

message WriteBookJob {
  option (google.api.resource) = {
    type: "library.googleapis.com/WriteBookJob"
    pattern: "publishers/{publisher}/writeBookJobs/{write_book_job}"
  };

  // Name and other fields...
}
  • 资源名字 必须 以“Job”结尾。
    • 前缀 应当 是有效的接口名字，包含动词和名词。
  • 服务 应当 定义所有五个标准方法（AIP-131、AIP-132、AIP-133、AIP-134、AIP-135），并作为配置作业的主要方法。

Run方法

服务 应当 定义 Run 自定义方法，立即执行作业：

rpc RunWriteBookJob(RunWriteBookJobRequest)
    returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{name=publishers/*/writeBookJobs/*}:run"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "RunWriteBookJobResponse"
    metadata_type: "RunWriteBookJobMetadata"
  };
}
  • 接口名字 必须 以 Run 开头，其余部分 应当 是待运行作业资源的单数形式。
  • 请求消息 必须 与接口名字一致，带有 Request 后缀。
  • 方法 应当 返回一个耗时操作， 必须 解析为包含作业结果的应答消息。
    • 应答消息名字必须与接口名字一致，带有 Response 后缀。
    • 方法 可以 使用任何需要的元数据消息。
  • HTTP动词 必须 是 POST ，如同自定义方法。
  • google.api.http 注解中的 body 子句 应当 是 "*" 。
  • URI路径 应当 包含与运行中作业资源名字对应的唯一 name 变量。
  • URI路径 必须 以 :run 结尾。
  • 如果作业 启动 失败， 必须 返回错误应答（AIP-193），如同其他方法。作业过程中发生的错误 可以 保存在元数据消息中。错误对象 必须 仍然用google.rpc.Status表示。

Run请求消息

Run 方法实现了一个常见的请求消息模式：

message RunWriteBookJobRequest {
  // The name of the job to run.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "library.googleapis.com/WriteBookJob"
    }];
}

执行和结果

通常，API 应当 将结果作为 Run 方法最终应答提供给用户。但有时这还不够。例如在后台按计划反复执行的作业，不能以这种方式向用户提供结果。

服务 可以 将作业单次执行过程和结果封装成资源，作为作业的下级资源子集合存储。这样的服务 应当 为作业单次执行过程定义 Get 、 List 和 Delete 方法：

message WriteBookJobExecution {
  option (google.api.resource) = {
    type: "library.googleapis.com/WriteBookJobExecution"
    pattern: "publishers/{publisher}/writeBookJobs/{write_book_job}/executions/{execution}"
  };

  // Name and other information about the execution, such as metadata, the
  // result, error information, etc.
}

此时，作业的 Run 方法返回的操作对象 应当 引用单次执行过程子资源。

修订记录

  • 2022-06-02 修改后缀描述，消除多余的“-”。
  • 2020-11-02 补充关于HTTP、域行为、资源引用注释和请求格式的指南。