创建和管理 protobuf 架构

本文档介绍了如何创建架构包以及如何对架构包执行操作。

在 Bigtable 中，您可以使用协议缓冲区 (protobuf) 架构来查询存储在列中作为字节的 protobuf 消息中的各个字段。为此，您需要将架构上传到架构包中，架构包是包含一个或多个 protobuf 架构的表级资源。

使用架构包具有以下优势：

• 节省时间和精力：使用协议缓冲区，您只需在 proto 文件中定义一次数据结构，然后使用生成的源代码来写入和读取数据。
• 提高数据一致性：通过将 proto 文件用作单一事实来源，您可以确保所有应用和服务都使用相同的数据模型。
• 消除数据重复：您可以通过在特定项目代码库之外的 proto 文件中定义消息类型，在多个项目中使用协议缓冲区。

在 Bigtable 中使用架构的过程从 proto 文件开始。proto 文件是一个文本文件，您可以在其中定义数据的结构。您可以使用 protobuf 编译器工具（也称为 protoc）生成 protobuf 文件描述符集，这是 proto 文件的机器可读架构。然后，您可以使用此描述符集创建架构软件包。

如需查看 proto 文件及其对应描述符集的示例，请参阅示例数据。

下图展示了在 Bigtable 中使用架构的过程：

图 1. 在 Bigtable 中使用 Protobuf 架构的过程（点击可放大）。

您可以使用 Google Cloud 控制台或 Google Cloud CLI 创建架构包。将架构软件包上传到 Bigtable 后，您可以使用 Bigtable Studio 查询构建器、GoogleSQL for Bigtable 或 BigQuery 中的 Bigtable 外部表来查询数据。

准备工作

如果您计划使用 gcloud CLI，请执行以下步骤：

1. 安装 Google Cloud CLI。

2. 初始化 gcloud CLI：

   gcloud init
   

所需的角色

如需获得创建和管理架构包所需的权限，请让管理员向您授予表的 Bigtable Admin (roles/bigtable.admin) Identity and Access Management (IAM) 角色。

此预定义角色包含 Bigtable 处理架构包所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

• bigtable.schemaBundles.create
• bigtable.schemaBundles.update
• bigtable.schemaBundles.delete
• bigtable.schemaBundles.get
• bigtable.schemaBundles.list

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解 Bigtable 角色和权限，请参阅使用 IAM 进行访问权限控制。

生成 protobuf 文件描述符集

您需要先使用 protobuf 编译器工具从 proto 文件生成描述符集，然后才能创建架构包。

1. 如需安装编译器，请下载软件包，然后按照自述文件中的说明操作。

2. 运行编译器：

   protoc --proto_path=IMPORT_PATH --include_imports \
      --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO
   

   替换以下内容：

   • IMPORT_PATH：protoc 编译器在其中搜索 proto 文件的目录。
   • DESCRIPTOR_OUTPUT_LOCATION：protoc 编译器保存生成的描述符集的目录。
   • PATH_TO_PROTO：proto 文件的路径。

例如，如需为当前目录中的 library.proto 文件创建名为 library.pb 的描述符集，您可以使用以下命令：

protoc --include_imports --descriptor_set_out=library.pb
library.proto

创建架构包

控制台

1. 在 Google Cloud 控制台中，打开 Bigtable 实例列表。

   打开实例列表

2. 从列表中选择一个实例。

3. 在导航窗格中，点击 Bigtable Studio。

4. 在探索器窗格中，点击要在其中创建架构包的表旁边的 more_vert 操作菜单，然后点击创建架构包。

5. 在创建架构软件包对话框的架构软件包 ID 字段中，输入架构软件包的唯一标识符。

   ID 的长度必须介于 1 到 50 个字符之间，只能包含字母、数字、下划线和连字符，不能以连字符开头，也不能包含英文句点字符 (.)。

6. 在文件描述符集（.pb 文件）字段中，点击浏览以选择您在本文档的生成 protobuf 文件描述符集部分中创建的 protobuf 文件描述符集。文件大小不能超过 4 MB。

7. 点击创建。

   架构软件包会在新标签页中打开。

gcloud

如需创建架构包，请使用 gcloud bigtable schema-bundles create 命令：

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

替换以下内容：

• SCHEMA_BUNDLE_ID：新架构包的唯一 ID，不能包含任何英文句点 ('.') 字符。
• INSTANCE_ID：您在其中创建架构包的实例的 ID。
• TABLE_ID：您在其中创建架构包的表的 ID。
• PROTO_DESCRIPTORS_FILE：您在本文档的生成 protobuf 文件描述符集部分中创建的描述符集的路径。

Java

如需创建架构包，请使用 createSchemaBundle 方法：

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .setSchemaBundleId(schemaBundleId)
          .setSchemaBundle(schemaBundleObj)
          .build();
  SchemaBundle schemaBundle = adminClient.createSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to create a schema bundle: " + e.getMessage());
}

查看有关架构包的信息

您需要有一个至少包含一个架构包的 Bigtable 表，然后才能查看架构包的相关信息。您可以通过检索单个架构包的定义或列出表中的所有架构包，来获取表中架构包的相关信息。

获取架构包定义

控制台

1. 在 Google Cloud 控制台中，打开 Bigtable 实例列表。

   打开实例列表

2. 从列表中选择一个实例。

3. 在导航窗格中，点击 Bigtable Studio。

4. 在探索器窗格中，展开包含架构包的表，然后展开架构包。

5. 点击要查看的架构包，或点击架构包旁边的 more_vert 操作菜单，然后点击查看详情。

   系统会打开一个标签页，其中显示了架构包定义。

6. 可选：如需打开 SQL 查询编辑器标签页，其中包含使用架构包的示例查询，请点击架构包旁边的 more_vert 操作菜单，然后点击示例查询。

gcloud

如需获取架构包的详细信息，请使用 gcloud bigtable schema-bundles describe 命令：

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

替换以下内容：

• SCHEMA_BUNDLE_ID：架构包的 ID。
• INSTANCE_ID：实例的 ID。
• TABLE_ID：表的 ID。

Java

如需获取架构包的定义，请使用 getSchemaBundle 方法。此方法会返回一个包含架构定义的 SchemaBundle 对象。

以下示例展示了如何获取架构包并反序列化描述符集，以输出架构的内容：

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

SchemaBundle schemaBundle = null;
try {
  schemaBundle =
      adminClient.getSchemaBundle(
          "projects/"
              + projectId
              + "/instances/"
              + instanceId
              + "/tables/"
              + tableId
              + "/schemaBundles/"
              + schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(
          schemaBundle.getProtoSchema().getProtoDescriptors());

  System.out.println("--------- Deserialized FileDescriptorSet ---------");
  for (DescriptorProtos.FileDescriptorProto fileDescriptorProto :
      fileDescriptorSet.getFileList()) {
    System.out.println("File: " + fileDescriptorProto.getName());
    System.out.println("  Package: " + fileDescriptorProto.getPackage());
    for (DescriptorProtos.DescriptorProto messageType :
        fileDescriptorProto.getMessageTypeList()) {
      System.out.println("  Message: " + messageType.getName());
    }
  }
  System.out.println("--------------------------------------------------");
} catch (InvalidProtocolBufferException e) {
  System.err.println("Failed to parse FileDescriptorSet: " + e.getMessage());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent schema bundle: " + e.getMessage());
}

输出类似于以下内容：

--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------

列出表中的架构包

控制台

1. 在 Google Cloud 控制台中，打开 Bigtable 实例列表。

   打开实例列表

2. 从列表中选择一个实例。

3. 在导航窗格中，点击 Bigtable Studio。

4. 在探索器窗格中，展开包含要查看的架构包的表。

5. 展开架构软件包。

   系统会显示表中的架构包列表。如果表没有任何架构包，则不会显示架构包列表。

gcloud

如需查看表的架构包列表，请使用 gcloud bigtable schema-bundles list 命令：

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

替换以下内容：

• INSTANCE_ID：实例的 ID。
• TABLE_ID：表的 ID。

Java

如需查看表中所有架构包的列表，请使用 listSchemaBundles 方法。此方法会返回架构软件包 ID 的列表。

以下示例展示了如何列出表中的架构包：

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

List<String> schemaBundleIds = new ArrayList<>();
try {
  ListSchemaBundlesRequest request =
      ListSchemaBundlesRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .build();
  for (SchemaBundle bundle : adminClient.listSchemaBundles(request).iterateAll()) {
    String id = SchemaBundleName.parse(bundle.getName()).getSchemaBundle();
    System.out.println(id);
    schemaBundleIds.add(id);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list schema bundles from a non-existent table: " + e.getMessage());
}

输出类似于以下内容：

my-schema-bundle-1
my-schema-bundle-2

更新架构包

更新架构包时，Bigtable 会检查新的描述符集是否与现有描述符集向后兼容。如果 Bigtable 检测到不兼容，更新将失败并显示 FailedPrecondition 错误。我们建议您保留已删除的字段编号，以防止重复使用。如需了解详情，请参阅 protobuf 文档中的 Proto 最佳实践。

如果您确定不兼容的更改是安全的，并且想要强制更新，则可以将 --ignore-warnings 标志与 gcloud CLI 搭配使用。不过，如果架构包正由持续物化视图或逻辑视图使用，则无法强制执行不兼容的更改。视图依赖于架构包的消息定义来解析和查询数据，因此不兼容的更改会破坏对逻辑视图的查询，并导致持续物化视图在数据处理期间失败。如需对视图引用的架构包进行向后不兼容的更改，您必须先更新或删除引用视图。

控制台

1. 在 Google Cloud 控制台中，打开 Bigtable 实例列表。

   打开实例列表

2. 从列表中选择一个实例。

3. 在导航窗格中，点击 Bigtable Studio。

4. 在探索器窗格中，展开包含架构包的表，然后展开架构包。

5. 在要更新的架构包旁边，点击 more_vert 操作菜单，然后点击更新。

6. 在更新架构软件包对话框的文件描述符集（.pb 文件）字段中，选择新的 protobuf 文件描述符集。文件大小不能超过 4 MB。

7. 点击保存。

gcloud

如需更新架构包以使用其他描述符集，请使用 gcloud bigtable schema-bundles update 命令：

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

替换以下内容：

• SCHEMA_BUNDLE_ID：要更新的架构包的 ID。
• INSTANCE_ID：包含架构包的实例的 ID。
• TABLE_ID：包含架构包的表的 ID。
• PROTO_DESCRIPTORS_FILE：新描述符集文件的路径。

可选：如需强制执行更新（即使存在不兼容的更改），请在命令中附加 --ignore-warnings 标志。如果架构包正由持续具体化视图或逻辑视图使用，则无法强制执行不兼容的更改。

Java

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

try (InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setName(
              "projects/"
                  + projectId
                  + "/instances/"
                  + instanceId
                  + "/tables/"
                  + tableId
                  + "/schemaBundles/"
                  + schemaBundleId)
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.newBuilder()
          .setSchemaBundle(schemaBundleObj)
          .setUpdateMask(FieldMask.newBuilder().addPaths("proto_schema").build())
          .build();
  SchemaBundle schemaBundle = adminClient.updateSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to modify schema bundle: " + e.getMessage());
}

删除架构包

警告： 此操作无法撤消。

如果架构包正由持续物化视图或逻辑视图使用，则无法删除该架构包。删除该软件包会导致对逻辑视图的查询失败，并阻止连续物化视图处理传入数据。如需删除架构包，您必须先删除引用该架构包的所有视图，或更新这些视图以移除引用。

控制台

1. 在 Google Cloud 控制台中，打开 Bigtable 实例列表。

   打开实例列表

2. 从列表中选择一个实例。

3. 在导航窗格中，点击 Bigtable Studio。

4. 在探索器窗格中，展开包含架构包的表，然后展开架构包。

5. 在要删除的架构软件包旁边，点击 more_vert 操作菜单，然后点击删除。

6. 在确认对话框中点击删除。

gcloud

如需删除架构包，请使用 gcloud bigtable schema-bundles delete 命令：

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

替换以下内容：

• SCHEMA_BUNDLE_ID：要删除的架构包的 ID。
• INSTANCE_ID：包含架构包的实例的 ID。
• TABLE_ID：包含架构包的表的 ID。

Java

如需了解如何安装和使用 Bigtable 的客户端库，请参阅 Bigtable 客户端库。

如需向 Bigtable 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

try {
  adminClient.deleteSchemaBundle(
      "projects/"
          + projectId
          + "/instances/"
          + instanceId
          + "/tables/"
          + tableId
          + "/schemaBundles/"
          + schemaBundleId);
  System.out.printf("SchemaBundle: %s deleted successfully%n", schemaBundleId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent schema bundle: " + e.getMessage());
}

限制

架构包具有以下限制：

• 每个表最多可以创建 10 个架构包。此限制适用于 protobuf 和 Avro 架构包。
• 架构包中序列化协议缓冲区描述符的总大小不能超过 4 MB。只要软件包的总大小不超过此限制，您可以包含在软件包中的单个架构数量就没有直接限制。

后续步骤

• 了解如何查询 protobuf 数据。
• 了解如何创建和管理 Avro 架构。
• 了解变化或不确定的查询。
• 请参阅 GoogleSQL for Bigtable 概览。