创建和管理 Avro 架构

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

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

您可以使用 Google Cloud 控制台或 Google Cloud CLI 创建和管理 Avro 架构包。将架构包上传到 Bigtable 后，您可以使用 GoogleSQL for Bigtable、持续物化视图或逻辑视图查询 Avro 数据。

准备工作

在创建和管理 Avro 架构包之前，请确保您有 Bigtable 实例和表。

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

  1. 安装 gcloud CLI。

  2. 初始化 gcloud CLI：

    gcloud init

  3. 启用 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 架构，其中所有依赖项都内嵌。在 Google Cloud 控制台中，您可以上传单个 AVSC 或 JSON 文件。借助 gcloud CLI，您可以指定单个文件或包含多个 Avro 架构文件的目录。如果一个 bundle 中的多个文件在同一命名空间中内嵌相同的 record 或 enum，则定义必须匹配，包括 doc 和 aliases。

创建 Avro 架构包

控制台

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

    打开实例列表

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

  3. 在导航菜单中，点击 Bigtable Studio。

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

  5. 在创建架构包对话框的架构文件（.pb、.avsc 或 .json）字段中，点击浏览，然后选择 AVSC 或 JSON Avro 架构文件。文件大小不能超过 4 MB。

  6. 在架构软件包 ID 字段中，保留根据文件名自动填充的 ID，或输入架构软件包的唯一 ID。

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

  7. 点击创建。

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

gcloud

如需在表中创建 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 架构包定义

控制台

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

    打开实例列表

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

  3. 在导航菜单中，点击 Bigtable Studio。

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

  5. 点击要查看的架构包，或点击架构包旁边的  查看操作，然后点击查看详细信息。

    系统会打开一个标签页，其中显示架构包详细信息和 JSON 格式的架构定义。

  6. 可选：如需打开预填充了使用架构包的示例 SQL 查询的查询编辑器标签页，请点击架构包旁边的  查看操作，然后点击示例查询。

gcloud

如需检索架构包的 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

列出表中的架构包

控制台

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

    打开实例列表

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

  3. 在导航菜单中，点击 Bigtable Studio。

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

  5. 展开架构软件包。

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

gcloud

如需列出表中所有架构包（包括 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 架构包添加 Avro 记录或枚举定义，并且无法在 Avro 和 protobuf 之间更改架构包的类型。更新软件包时，您必须同时提供新架构和所有现有架构。

控制台

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

    打开实例列表

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

  3. 在导航菜单中，点击 Bigtable Studio。

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

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

  6. 在更新架构包对话框的架构文件（.pb、.avsc 或 .json）字段中，点击浏览，然后选择更新后的 AVSC 或 JSON Avro 架构文件。文件大小不能超过 4 MB。

  7. 点击保存。

gcloud

如需更新 Avro 架构包，请使用 gcloud bigtable schema-bundles update 命令：

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 的任何逻辑视图，请更新这些视图以移除引用，或直接删除这些视图。如需了解详情，请参阅创建和管理持续物化视图或创建和管理逻辑视图。

控制台

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

    打开实例列表

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

  3. 在导航菜单中，点击 Bigtable Studio。

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

  5. 在要删除的架构包旁边，点击  查看操作，然后点击删除。

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

gcloud

如需删除 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。

后续步骤