建立 Bigtable 訂閱項目

預覽

這項產品或功能適用《服務專屬條款》中「一般服務條款」一節的《正式發布前產品條款》。正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

本文說明如何在 Pub/Sub 中建立 Bigtable 訂閱項目。透過 Bigtable 訂閱項目，您可以將 Pub/Sub 訊息直接寫入 Bigtable 資料表。

如要進一步瞭解這類訂閱項目，請參閱「Bigtable 訂閱項目」。

事前準備

• 您要寫入 Pub/Sub 訊息的 Bigtable 資料表必須已存在。詳情請參閱「建立及管理資料表」。

• 資料表必須有名為 data 的資料欄系列。建立資料表時，您可以新增資料欄系列。

• 如要將訊息中繼資料寫入資料表，資料表也必須有名為 pubsub_metadata 的資料欄系列。

必要角色和權限

如要取得建立 Bigtable 訂閱項目所需的權限，請要求系統管理員授予您專案的「Pub/Sub 編輯者 」(roles/pubsub.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備建立 Bigtable 訂閱項目所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立 Bigtable 訂閱項目，必須具備下列權限：

• 專案的 pubsub.subscriptions.create
• pubsub.topics.attachSubscription 主題

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

跨專案訂閱

如果您在一個專案中建立訂閱項目，訂閱另一個專案中的主題，則必須在建立訂閱項目的專案中具備 pubsub.subscriptions.create 權限，並在主題中具備 pubsub.topics.attachSubscription 權限。

將 IAM 角色授予服務帳戶

Pub/Sub 會使用 Identity and Access Management (IAM) 服務帳戶存取 Google Cloud 資源。如要讓 Pub/Sub 寫入 Bigtable，請務必為這個服務帳戶授予「Bigtable 使用者」(roles/bigtable.user) 角色。

根據預設，Pub/Sub 會使用 Pub/Sub 服務代理程式
([e-mail])。您也可以在建立 Bigtable 訂閱時，指定使用者管理的服務帳戶。

使用 Pub/Sub 服務代理

如要將必要角色授予 Pub/Sub 服務代理，請按照下列步驟操作。您可以授予專案或包含資料表的 Bigtable 執行個體角色。

專案

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「身分與存取權管理」頁面

2. 選取「包含 Google 提供的角色授予項目」。

3. 找到「Cloud Pub/Sub Service Account」(Cloud Pub/Sub 服務帳戶) 列，然後按一下 「Edit principal」(編輯主體)。

4. 按一下「新增其他角色」，然後選取「Bigtable 使用者」角色。

詳情請參閱「使用控制台授予 IAM 角色」一文。

執行個體

1. 在 Google Cloud 控制台，依序前往「Bigtable」>「Instances」(執行個體) 頁面。

   前往「Instances」(執行個體)

2. 在「Instances」(執行個體) 頁面中，選取執行個體名稱旁的核取方塊。

3. 如果畫面上未顯示資訊面板，請按一下「Show info panel」(顯示資訊面板)。

4. 按一下「新增主體」，然後輸入服務帳戶 ID，格式如下：

   [e-mail]。

5. 在「指派角色」清單中，選取「Bigtable 使用者」。

6. 按一下 [儲存]。主體就會取得指定資源的角色。

使用自訂服務帳戶

如果將 Bigtable 使用者角色授予 Pub/Sub 服務代理，則有權在專案中建立訂閱項目的任何使用者，都能寫入 Bigtable 資料表。如要提供更精細的權限，請改為設定使用者管理的服務帳戶。

如要設定使用者管理的服務帳戶，以便寫入 Bigtable，必須具備下列權限：

• 使用者管理的服務帳戶必須具備 Bigtable 使用者角色。

• Cloud Pub/Sub 服務帳戶必須具備使用者自行管理的服務帳戶的 iam.serviceAccounts.getAccessToken 權限。

• 建立訂閱項目時，使用者必須具備使用者自行管理的服務帳戶 iam.serviceAccounts.actAs 權限。

建立訂閱項目時，請指定使用者代管的服務帳戶。 詳情請參閱「建立 Bigtable 訂閱項目」。

Bigtable 資料表寫入作業

本節說明 Bigtable 訂閱項目如何將 Pub/Sub 訊息寫入資料表。

訊息資料

Bigtable 訂閱項目會將 Pub/Sub 訊息資料寫入名為 data 的資料欄系列。

• 每個資料列都包含一個訊息中的資料。

• 資料列索引鍵會串連訂閱 ID、訊息 ID 鹽前置字元和訊息 ID，格式如下：

  "projects/PROJECT_NUMBER/subscriptions/SUBSCRIPTION_ID#SALT_PREFIX#MESSAGE_ID"

• 訊息資料會寫入 data 資料欄系列中的單一資料欄。 該資料欄含有空字串 ("") 資料欄限定詞。

• 資料會以 BYTES 型別寫入。

• 儲存格的時間戳記是訊息的發布時間。

訊息中繼資料

根據預設，訂閱項目不會將訊息中繼資料寫入資料表。 您也可以在建立 Bigtable 訂閱項目時，選擇啟用中繼資料寫入功能。

如果啟用寫入中繼資料功能，訂閱項目會將訊息中繼資料寫入名為 pubsub_metadata 的資料欄系列。建立訂閱項目之前，請確認資料表是否有名為這個名稱的資料欄系列。

訂閱項目會為每則訊息寫入新資料列，並在 pubsub_metadata 資料欄系列下加入下列資料欄。

欄	值	資料類型
subscription_name	訂閱方案名稱	字串
message_id	郵件 ID	字串
attributes	內含訊息屬性的 JSON 物件	字串

建立 Bigtable 訂閱項目

如要建立 Bigtable 訂閱項目，請使用 gcloud beta pubsub subscriptions create 指令：

gcloud beta pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --bigtable-table=projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_ID

更改下列內容：

• SUBSCRIPTION_ID：訂閱方案名稱。
• TOPIC_ID：要讀取的主題名稱或 ID。
• PROJECT_ID：專案 ID。
• INSTANCE_ID：包含資料表的 Bigtable 執行個體 ID。
• TABLE_ID：要寫入的資料表 ID。資料表必須有名為 data 的資料欄系列。

以下旗標為選用項目：

• --bigtable-write-metadata：指定是否要寫入訊息中繼資料。如果省略這個旗標，訂閱項目就不會寫入中繼資料。詳情請參閱「訊息中繼資料」。

• --bigtable-app-profile-id=APP_PROFILE：指定用於 Bigtable 寫入作業的應用程式設定檔。應用程式設定檔必須使用單叢集轉送。如果未指定這個旗標，訂閱項目會使用預設的應用程式設定檔。

• --bigtable-service-account-email：指定寫入 Bigtable 時要使用的服務帳戶。如未指定，訂閱項目會使用 Pub/Sub 服務代理程式。詳情請參閱「使用自訂服務帳戶」。

範例：從 Pub/Sub 寫入 Bigtable

下列範例說明如何建立 Bigtable 訂閱項目、使用該訂閱項目將 Pub/Sub 訊息寫入 Bigtable 資料表，然後查詢該資料表。

1. 建立名為 my-instance 的新 Bigtable 執行個體。

   gcloud bigtable instances create my-instance --display-name="My instance" \
     --cluster-config=id=my-cluster-1,zone=ZONE,nodes=1
   

   將 ZONE 替換為叢集執行的區域。範例：us-central1-b

2. 建立名為 table-1 的 Bigtable 資料表，並將資料欄系列命名為 data。

   gcloud bigtable instances tables create table-1 \
     --instance=my-instance \
     --column-families=data
   

3. 建立名為 topic-1 的 Pub/Sub 主題。

   gcloud pubsub topics create topic-1
   

4. 建立從主題讀取資料的 Bigtable 訂閱項目。

   gcloud beta pubsub subscriptions create bigtable-sub \
     --topic=topic-1 \
     --bigtable-table=projects/PROJECT_ID/instances/my-instance/tables/table-1
   

   將 PROJECT_ID 替換為 Google Cloud專案 ID。

5. 將訊息發佈到主題。

   gcloud pubsub topics publish topic-1 --message='{"name":"Alice"}'
   

   如果訊息發布成功，輸出內容會是訊息 ID：

   messageIds:
   - 'MESSAGE_ID'
   

Bigtable 訂閱項目會將訊息資料寫入 data 資料欄系列。如要查詢資料，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的 Bigtable「Instances」(執行個體) 頁面。

   前往「Instances」(執行個體)

2. 按一下名為 my-cluster-1 的執行個體。

3. 在導覽選單中，按一下「Bigtable Studio」。

4. 在查詢編輯器中，執行下列 SQL 查詢。

   SELECT _key, JSON_VALUE(CAST(data[''] AS STRING), '$.name') AS name FROM table-1;
   

   查詢結果如下所示：

   +-------------------+
   | _key      | name  |
   +-----------|-------+
   | "ROW_KEY" | Alice |
   +-------------------+
   

   訊息資料會以 BYTES 型別儲存。在本例中，資料是 JSON 字串，因此查詢可以使用 GoogleSQL JSON 函式剖析資料。

監控 Bigtable 訂閱項目

Cloud Monitoring 提供多項指標，可監控訂閱項目。

如要查看所有可用的 Pub/Sub 相關指標及其說明，請參閱 Pub/Sub 的監控說明文件。

您也可以在 Pub/Sub 中監控訂閱項目。

後續步驟

• 進一步瞭解 Bigtable 訂閱項目。
• 選擇訂閱方案類型。
• 排解 Bigtable 訂閱問題