建立及管理 Avro 結構定義

Bigtable 中的 Apache Avro 結構定義可讓您查詢 Avro 記錄中的個別欄位，Bigtable 會將這些記錄儲存為資料欄中的序列化位元組。如要查詢這些欄位，請在結構定義套件中上傳 JSON 格式的 Avro 結構定義，這是一種資料表層級資源，包含一或多個 Avro 記錄結構定義。如要進一步瞭解 Apache Avro 結構定義，請參閱 Apache Avro 說明文件。

上傳 Avro 結構定義套件不會改變將資料寫入 Bigtable 的方式。您仍會以序列化位元組的形式寫入 Avro 記錄。儲存格酬載只能包含原始位元組，不得嵌入結構定義或結構定義指紋。

將結構定義套件上傳至 Bigtable 後，您可以使用 Bigtable 適用的 GoogleSQL、持續性 materialized view 或邏輯檢視表查詢 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 系統管理員 (roles/bigtable.admin) Identity and Access Management (IAM) 角色。

如要取得結構定義套件的唯讀存取權，並使用 Bigtable 適用的 GoogleSQL 查詢 Avro 記錄，請要求管理員授予您資料表的 Bigtable 讀取者 (roles/bigtable.reader) 或 Bigtable 使用者 (roles/bigtable.user) 角色。

這些預先定義的角色具備處理結構定義套件和查詢 Avro 資料所需的權限。如要查看必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及管理結構定義套件，您必須具備下列權限，具體取決於作業：

  • bigtable.schemaBundles.create：為資料表建立結構定義套件
  • bigtable.schemaBundles.update：更新結構定義組合定義
  • bigtable.schemaBundles.delete：刪除結構定義組合
  • bigtable.schemaBundles.get：取得結構定義組合的相關資訊
  • bigtable.schemaBundles.list：在表格中列出結構定義套件
  • bigtable.schemaBundles.getIamPolicy：取得結構定義套件的 IAM 政策
  • bigtable.schemaBundles.setIamPolicy：設定結構定義組合的身分與存取權管理政策

如要使用 GoogleSQL for Bigtable 讀取或篩選 Avro 記錄，您必須具備下列權限：

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

您也可以透過自訂角色或其他預先定義的角色取得這些權限。

如要進一步瞭解 Bigtable 角色和權限，請參閱「使用 IAM 控管存取權」。

準備 Avro 結構定義檔案

建立 Avro 結構定義套件前，請先準備一或多個 JSON 格式的 Avro 結構定義檔案，格式為 AVSC 或 JSON。每個檔案都必須在頂層包含有效、獨立的 Avro record 結構定義，且所有依附元件都必須內嵌。如果套裝組合中的多個檔案在同一個命名空間中內嵌相同的 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

以表格列出結構定義套件

如要列出資料表中所有結構定義套件的 ID (包括 Avro 和 protobuf 結構定義套件)，請使用 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 結構定義組合

如果連續 materialized view 或邏輯檢視表參照結構定義組合，則無法刪除該組合。刪除套件前，請先刪除參照該套件的所有連續 materialized view。如果任何邏輯檢視表參照了該套件，請更新檢視表以移除參照，或刪除檢視表。詳情請參閱「建立及管理連續 materialized view」或「建立及管理邏輯檢視表」。

如要刪除 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 結構定義套件有下列限制：

  • 您可以使用 Bigtable 專用 GoogleSQL、持續性 materialized view 和邏輯檢視，以 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", "string"]。
    • 巢狀集合，例如包含其他陣列或對應的陣列或對應。
    • 含有可為空值元素的陣列。系統支援具有可為空值的值 (例如 {"type": "map", "values": ["null", "string"]}) 的對應。
    • 陣列含有空白、零欄位的記錄元素。
    • 循環或遞迴記錄定義，或記錄參照和複雜 JSON 物件，例如內嵌記錄、陣列、對應和列舉，巢狀結構超過 32 層。
    • Avro namespace 值中的底線 (_)。
    • 在同一個命名空間中，不同 enum 類型有重複的 enum 符號名稱。
    • 同一記錄中有多個 map 欄位，其名稱轉換為相同的大駝峰式大小寫字串，例如 my_map、myMap 和 my__map。
  • 查詢資料時，Bigtable 會忽略特定 Avro 結構定義屬性，例如欄位預設值 (default)、aliases、doc 和排列順序 (order)。不過，如果套件中的多個檔案在同一個命名空間中定義相同的 record 或 enum，則其定義必須相符，包括 doc 和 aliases。

後續步驟