AIP-153 导入和导出

编号	153
原文链接	AIP-153: Import and export
状态	批准
创建日期	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 。

请求对象

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

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

源或目标配置应该一起放到一个消息中，保存在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。