创建和管理 Avro 架构

借助 Bigtable 中的 Apache Avro 架构，您可以查询 Bigtable 在列中存储为序列化字节的 Avro 记录中的各个字段。如需查询这些字段，请在架构包（包含一个或多个 Avro 记录架构的表级资源）中上传 JSON 格式的 Avro 架构。如需详细了解 Apache Avro 架构，请参阅 Apache Avro 文档。

上传 Avro 架构包不会改变您向 Bigtable 写入数据的方式。您继续以序列化字节的形式写入 Avro 记录。 单元格载荷必须仅包含原始字节，不包含嵌入式架构或架构指纹。

将架构包上传到 Bigtable 后，您可以使用 GoogleSQL for Bigtable、连续物化视图或逻辑视图查询 Avro 数据。

准备工作

在创建和管理 Avro 架构包之前，请执行以下操作：

  1. 安装 Google Cloud CLI。

  2. 初始化 gcloud CLI：

    gcloud init

  3. 确保您有一个 Bigtable 实例和表。

  4. 启用 Cloud Bigtable API 和 Cloud Bigtable Admin API：

    gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com

所需的角色

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

如需获得对架构包的只读权限并使用 GoogleSQL for Bigtable 查询 Avro 记录，请让管理员为您授予表的 Bigtable Reader (roles/bigtable.reader) 或 Bigtable User (roles/bigtable.user) 角色。

这些预定义角色包含处理架构包和查询 Avro 数据所需的权限。如需查看所需权限，请展开所需权限部分：

所需权限

如需创建和管理架构包，您需要具备表级或架构包级权限，具体取决于操作：

  • bigtable.schemaBundles.create：为表创建架构包
  • bigtable.schemaBundles.update：更新架构包定义
  • bigtable.schemaBundles.delete：删除架构包
  • bigtable.schemaBundles.get：获取有关架构包的信息
  • bigtable.schemaBundles.list：列出表中的架构包
  • bigtable.schemaBundles.getIamPolicy：获取架构软件包的 IAM 政策
  • bigtable.schemaBundles.setIamPolicy：为架构包设置 IAM 政策

如需使用 GoogleSQL for Bigtable 读取或过滤 Avro 记录，您需要拥有以下权限：

  • bigtable.tables.readRows
  • bigtable.instances.executeQuery

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

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

准备 Avro 架构文件

在创建 Avro 架构包之前，请准备一个或多个 AVSC 或 JSON 文件格式的 JSON 格式 Avro 架构文件。每个文件都必须在顶层包含一个有效的、自包含的 Avro record 架构，其中所有依赖项都内嵌。如果一个 bundle 中的多个文件在同一命名空间中内嵌相同的 record 或 enum，则定义必须匹配，包括 doc 和 aliases。

创建 Avro 架构包

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

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

替换以下内容：

  • SCHEMA_BUNDLE_ID：架构包的唯一 ID。ID 的长度必须为 1 到 50 个字符，只能包含字母、数字、下划线和连字符，不能以连字符开头，也不能包含英文句点 (.) 字符。
  • INSTANCE_ID：包含该表的实例的 ID。
  • TABLE_ID：要在其中创建架构包的表的 ID。
  • AVRO_SCHEMA_PATH：JSON 格式的 Avro 架构文件的路径，或包含一个或多个 Avro 架构文件的目录的路径。每个文件都必须是一个自包含的 JSON 对象，其中包含所有内嵌依赖项。

查看有关架构包的信息

您可以通过检索单个架构包的定义或列出表中的所有架构包，来查看表中架构包的相关信息。

获取 Avro 架构包定义

如需检索架构包的 JSON 格式 Avro 架构定义，请使用 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

列出表中的架构包

如需列出表中所有架构包（包括 Avro 和 protobuf 架构包）的 ID，请使用 gcloud bigtable schema-bundles list 命令：

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

替换以下内容：

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

如需检查列表中特定架构包的基础架构定义，请运行 gcloud bigtable schema-bundles describe 命令。

更新 Avro 架构包

如需更新 Avro 架构包，请使用 gcloud bigtable schema-bundles update 命令。您只能向现有 Avro 架构包添加新的 Avro 记录或枚举定义，并且无法在 Avro 和 protobuf 之间更改架构包的类型。更新软件包时，您必须传递一个包含新架构和所有现有架构的文件或目录。

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

替换以下内容：

  • SCHEMA_BUNDLE_ID：要更新的架构包的 ID
  • INSTANCE_ID：包含架构包的实例的 ID
  • TABLE_ID：包含架构包的表的 ID
  • AVRO_SCHEMA_PATH：JSON 格式的 Avro 架构文件的路径，或包含一个或多个 Avro 架构文件的目录的路径

删除 Avro 架构包

如果持续具体化视图或逻辑视图引用了架构包，则您无法删除该包。在删除该 bundle 之前，请先删除引用该 bundle 的所有连续物化视图。对于引用该 bundle 的任何逻辑视图，请更新这些视图以移除引用，或删除这些视图。如需了解详情，请参阅创建和管理持续物化视图或创建和管理逻辑视图。

如需删除 Avro 架构包，请使用 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

价格

创建或管理 Avro 架构包无需支付额外费用。请求和响应会产生标准网络带宽费用。如果您使用 Data Boost 无服务器计算从 Bigtable 读取数据，则需要为查询使用的计算资源付费。如需了解详情，请参阅 Bigtable 价格。

限制

Avro 架构包具有以下限制：

  • 您可以使用 GoogleSQL for Bigtable、连续物化视图和逻辑视图，以 Avro 记录的形式读取和查询列。Bigtable ReadRows API 和 BigQuery 外部表不支持服务器端 Avro 解析。
  • 每个表最多可以创建 10 个架构包。此限制适用于 Avro 和 protobuf 架构包。
  • 单个架构包中 JSON 格式的 Avro 架构的总大小不能超过 4 MB。Bigtable 还会将软件包转换为内部 protobuf 描述符集，该描述符集不能超过 4 MB。
  • Bigtable 不支持以下 Avro 架构类型、结构和命名模式：
    • fixed 类型和逻辑类型，例如 date、duration、time-micros 和 uuid。
    • 具有多个非 null 类型的多分支联合。仅支持可为 null 的联合，例如 ["null", "string"]。
    • 嵌套集合，例如包含其他数组或映射的数组或映射。
    • 包含可为 null 的元素的数组。支持具有可为 null 的值的映射，例如 {"type": "map", "values": ["null", "string"]}。
    • 包含空、零字段记录元素的数组。
    • 循环或递归记录定义，或记录引用和复杂 JSON 对象（例如内嵌记录、数组、映射和枚举），嵌套深度超过 32 级。
    • Avro namespace 值中的下划线 (_)。
    • 同一命名空间内不同 enum 类型之间的 enum 符号名称重复。
    • 同一记录中的多个 map 字段，其名称转换为相同的大驼峰式大小写字符串，例如 my_map、myMap 和 my__map。
  • 查询数据时，Bigtable 会忽略某些 Avro 架构属性，例如字段默认值 (default)、aliases、doc 和排列顺序 (order)。但是，如果一个 bundle 中的多个文件在同一命名空间中定义了相同的 record 或 enum，则它们的定义必须匹配，包括 doc 和 aliases。

后续步骤