建立及管理 protobuf 結構定義

本文說明如何建立結構定義套件，以及如何對結構定義套件執行作業。

在 Bigtable 中，您可以使用通訊協定緩衝區 (protobuf) 結構定義，查詢儲存在資料欄中以位元組形式表示的 protobuf 訊息內的個別欄位。方法是上傳結構定義套件，也就是含有您一或多個 protobuf 結構定義的資料表層級資源。

使用結構定義組合可享有下列好處：

  • 節省時間和精力：使用通訊協定緩衝區時，您只需在 proto 檔案中定義一次資料結構，然後使用產生的原始碼來寫入及讀取資料。
  • 提升資料一致性：使用 proto 檔案做為單一事實來源，確保所有應用程式和服務都使用相同的資料模型。
  • 消除資料重複：您可以在特定專案程式碼集以外的 proto 檔案中定義訊息型別，以便在各個專案中使用通訊協定緩衝區。

在 Bigtable 中使用結構定義的程序，從 Proto 檔案開始。proto 檔案是文字檔，用於定義資料結構。您可以使用 protobuf 編譯器工具 (也稱為 protoc)，產生 protobuf 檔案描述元集，這是 proto 檔案的機器可讀取結構定義。接著，您可以使用這組描述元建立結構定義套裝組合。

如需 proto 檔案和對應描述元集的範例，請參閱「範例資料」。

下圖顯示在 Bigtable 中使用結構定義的程序：

在 Bigtable 中使用 protobuf 結構定義的程序。
圖 1. 在 Bigtable 中使用 protobuf 結構定義的程序 (按一下可放大)。

您可以使用 Google Cloud 控制台或 Google Cloud CLI 建立結構定義套裝組合。將結構定義套件上傳至 Bigtable 後，您可以使用 Bigtable Studio 查詢建構工具、Bigtable 適用的 GoogleSQL，或 BigQuery 中的 Bigtable 外部資料表，查詢資料。

事前準備

如果您打算使用 gcloud CLI，請按照下列步驟操作：

  1. 安裝 Google Cloud CLI。

  2. 初始化 gcloud CLI：

    gcloud init

必要的角色

如要取得建立及管理結構定義套裝組合所需的權限，請要求管理員授予您資料表的「Bigtable 管理員」(roles/bigtable.admin) 身分與存取權管理 (IAM) 角色。

這個預先定義的角色具備 Bigtable 使用結構定義套件所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

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

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

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

產生 protobuf 檔案描述元集

您必須先使用 protobuf 編譯器工具，從 proto 檔案產生描述元集，才能建立結構定義套件。

  1. 如要安裝編譯器，請下載套件，然後按照 README 檔案中的操作說明進行。

  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. 在「Explorer」窗格中，找到要建立結構定義套裝組合的資料表，然後點選旁邊的 more_vert 動作選單，並按一下「建立結構定義套裝組合」。

  5. 在「建立結構定義軟體包」對話方塊的「結構定義軟體包 ID」欄位中，輸入結構定義軟體包的專屬 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. 在「Explorer」窗格中，展開包含結構定義套件的資料表，然後展開「結構定義套件」。

  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. 在「Explorer」窗格中，展開包含要查看結構定義套裝組合的資料表。

  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 Best Practices」。

如果確定不相容的變更安全無虞，並想強制更新，可以使用 gcloud CLI 的 --ignore-warnings 旗標。不過，如果結構定義套裝組合正由持續具體化檢視表或邏輯檢視表使用，您就無法強制進行不相容的變更。檢視區塊會依據結構定義組合的訊息定義來剖析及查詢資料，因此不相容的變更會導致針對邏輯檢視區塊的查詢中斷，並導致持續實體化檢視區塊在資料處理期間失敗。如要對檢視區塊參照的結構定義套件進行不相容的變更，請先更新或刪除參照的檢視區塊。

控制台

  1. 在 Google Cloud 控制台中，開啟 Bigtable 執行個體清單。

    開啟執行個體清單

  2. 從清單中選取執行個體。

  3. 在導覽窗格中，按一下「Bigtable Studio」。

  4. 在「Explorer」窗格中，展開包含結構定義套件的資料表，然後展開「結構定義套件」。

  5. 找出要更新的結構化資料組合，然後按一下旁邊的「更多」more_vert動作選單，再按一下「更新」。

  6. 在「Update schema bundle」對話方塊的「File Descriptor Set (.pb file)」欄位中，選取新的 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. 在「Explorer」窗格中，展開包含結構定義套裝組合的資料表，然後展開「結構定義套裝組合」。

  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 個結構定義組合。
  • 架構套件中序列化通訊協定緩衝區描述元的總大小不得超過 4 MB。只要套件總大小不超過這個限制，您可加入的個別結構化資料數量就沒有直接限制。

後續步驟