AIP-153 导入和导出

2025年2月26日 · [tommwq@126.com]

编号	153
原文链接	https://google.aip.dev/153
状态	批准
创建日期	2019-12-16
更新日期	2019-12-16

许多用户希望能将数据导入API中，或者从API中导出现有数据。这对于企业用户尤为重要，他们时常担心出现供应商锁定。

指南

API 可以支持导入和导出操作。这类操作可以创建多个新资源，也可以将数据填充到单个资源中。

多个资源

服务可以支持API导入或导出多个资源，此时应当实现下列通用模式：

rpc ImportBooks(ImportBooksRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:import"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "ImportBooksResponse"
    metadata_type: "ImportBooksMetadata"
  };
}

rpc ExportBooks(ExportBooksRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:export"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "ExportBooksResponse"
    metadata_type: "ExportBooksMetadata"
  };
}

方法必须返回耗时操作（参见AIP-151），除非服务可以保证完成时间永远不会超过几秒钟。
HTTP动词必须使用 POST ，并且 body 必须是 "*" 。
URI中应当包含 parent 域。
- 如果需要导入或导出多个资源，API 应当保留 parent 域，允许用户使用 - 字符来表示相应的多个上级资源（参见AIP-159）。
- 在导入时，如果用户提供了特定上级资源，API 必须拒绝任何可能被添加到其他上级资源的待导入资源。
URI后缀应当是 :import 或 :export 。

单个资源的数据

服务可以支持单个资源的数据导入或导出，应当实现下列的通用模式：

rpc ImportPages(ImportPagesRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{book=publishers/*/books/*}:importPages"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "ImportPagesResponse"
    metadata_type: "ImportPagesMetadata"
  };
}

rpc ExportPages(ExportPagesRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{book=publishers/*/books/*}:exportPages"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "ExportPagesResponse"
    metadata_type: "ExportPagesMetadata"
  };
}

方法必须返回耗时操作（参见AIP-151），除非服务可以保证完成时间永远不会超过几秒钟。
HTTP动词必须使用 POST ，并且 body 必须是 "*" 。
URI 应当包含一个表示待导入数据的资源的域。域应当以资源命名（不应称为 name ）。
URI后缀应该同时包括动词和表示数据自身的名词，例如 :importPages 或 :exportPages 。

请求对象

导入和导出操作往往需要两种不同类型的配置：

指定源或目标的配置。
关于导入或导出数据自身的配置。

源或目标配置应该一起放到一个消息中，保存在oneof里：

message ImportBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];
  oneof source {
    AuthorSource author_source = 2;
    TranslatorSource translator_source = 3;
  }
  string isbn_prefix = 4;
}

message ExportBooksRequest {
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];
  oneof destination {
    PrinterDestination printer_destination = 2;
    TranslatorDestination translator_destination = 3;
  }
  string filter = 4;
}

源配置消息必须保存在 oneof source （导入）或 oneof destination （导出）中，即使只有一项配置。（可以保持将来添加更多配置的灵活性。）
与数据自身相关的配置（对所有源都是一样的）必须保存在请求消息的顶层域中。

注意导入和导出的配置可以互不不同。（例如，可能从文件导入数据，再导出到目录。）

内联源

API 可以支持“内联”导入和导出，待导入或导出的内容在请求或应答中提供。

message InlineSource {
  repeated Book books = 1;
}

源或目标应当命名为 InlineSource 或 InlineDestination 。
消息应当包括一个表示资源的重复域。如果资源结构复杂，API 可以使用单独的内联表示。此时导入和导出必须使用相同的格式。

部分失败

虽然通常不建议使用部分失败模式，但导入和导出接口应当在元数据对象中包含部分失败信息。每个错误应当封装成描述错误的 google.rpc.Status 对象。关于错误处理，参考AIP-193。