建立 Cloud Storage 訂閱項目

本文說明如何建立 Cloud Storage 訂閱項目。您可以使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API 建立 Cloud Storage 訂閱項目。

事前準備

閱讀本文前，請先熟悉下列概念：

• Cloud Storage 訂閱方案的運作方式。
• Cloud Storage 的運作方式，以及如何建立和管理 Cloud Storage 值區。
• 如何設定無效信件主題來處理訊息傳送失敗問題。

必要角色和權限

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

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

所需權限

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

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

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

跨專案訂閱

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

將 IAM 角色授予服務帳戶

Pub/Sub 會使用 Identity and Access Management (IAM) 服務帳戶存取 Google Cloud 資源。根據預設，這項服務會使用 Pub/Sub 服務代理程式 ([e-mail])。

如要讓 Pub/Sub 寫入 Cloud Storage，服務帳戶需要下列角色：

• Storage 物件建立者 (roles/storage.objectCreator)
• Storage 舊版值區讀取者 (roles/storage.legacyBucketReader)

您可以為服務帳戶授予專案或 Cloud Storage 值區的權限，方法如下：

專案

1. 前往 Google Cloud 控制台的「Bucket」頁面。

   前往值區

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

3. 找到 Cloud Pub/Sub 服務帳戶的資料列，然後按一下 「編輯主體」。

4. 按一下「新增其他角色」，然後選取「Storage 物件建立者」角色。針對「Storage 舊版 bucket 讀取者」角色重複這個步驟。

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

Cloud Storage bucket

1. 前往 Google Cloud 控制台的「Buckets」(值區)。

   前往值區

2. 按一下要授予權限的 Cloud Storage bucket 名稱。

3. 前往「Bucket details」(值區詳細資料) 頁面，點選「Permissions」(權限) 分頁標籤。

4. 在「權限」窗格中，按一下「按照主體查看」分頁標籤。

5. 按一下「授予存取權」。

6. 在「新增主體」欄位中，輸入服務帳戶 ID，格式如下：

   [e-mail]。

7. 在「指派角色」清單中，選取「Storage 物件建立者」。

8. 按一下「新增其他角色」，然後選取「Storage 舊版 bucket 讀取者」。

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

使用自訂服務帳戶

將「Storage 物件建立者」和「Storage 舊版 bucket 讀取者」角色授予 Cloud Pub/Sub 服務帳戶後，凡是有權在專案中建立訂閱項目的使用者，都能寫入 Cloud Storage bucket。如要提供更精細的權限，請改為設定使用者管理的服務帳戶。

如要設定使用者管理的服務帳戶，使其能寫入 Cloud Storage，必須具備下列權限：

• 使用者管理的服務帳戶必須具備「Storage 物件建立者」和「Storage 舊版 bucket 讀取者」角色。

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

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

建立訂閱項目時，請將使用者代管的服務帳戶指定為訂閱項目服務帳戶。

Cloud Storage 訂閱方案屬性

Cloud Storage 訂閱項目支援所有常見的訂閱項目屬性。以下各節說明 Cloud Storage 訂閱方案專屬的屬性。

值區名稱

建立 Cloud Storage 訂閱項目之前，必須先有 Cloud Storage bucket。

訊息會以批次形式傳送，並儲存在 Cloud Storage bucket 中。 單一批次或檔案會以物件形式儲存在 bucket 中。

Cloud Storage bucket 必須停用「要求者付費」功能。

如要建立 Cloud Storage bucket，請參閱「建立 bucket」。

檔案名稱前置字元、後置字元和日期時間

Cloud Storage 訂閱項目產生的輸出 Cloud Storage 檔案會以物件形式儲存在 Cloud Storage bucket 中。儲存在 Cloud Storage 值區中的物件名稱格式如下：<file-prefix><UTC-date-time>_<uuid><file-suffix>。

以下清單列出檔案格式和可自訂欄位的詳細資料：

• <file-prefix> 是自訂檔案名稱前置字元。此為選填欄位。

• <UTC-date-time> 是可自訂的自動生成字串，會根據物件的建立時間產生。

• <uuid> 是物件的自動產生隨機字串。

• <file-suffix> 是自訂檔案名稱尾碼。此為選填欄位。檔案名稱後置字串不得以「/」結尾。

• 您可以變更檔案名稱前置字串和後綴字串：

  • 舉例來說，如果檔案名稱前置字串的值為 prod_，且檔案名稱後置字串的值為 _archive，則範例物件名稱為 prod_2023-09-25T04:10:00+00:00_uN1QuE_archive。

  • 如未指定檔案名稱前置字串和後置字串，儲存在 Cloud Storage bucket 中的物件名稱格式為：<UTC-date-time>_<uuid>。

  • Cloud Storage 物件命名規定也適用於檔案名稱前置字串和後置字串。詳情請參閱「關於 Cloud Storage 物件」。

• 你可以變更檔案名稱中顯示日期和時間的方式：

  • 您只能使用一次的必要日期時間比對器：年 (YYYY 或 YY)、月 (MM)、日 (DD)、時 (hh)、分 (mm)、秒 (ss)。舉例來說，YY-YYYY 或 MMM 無效。

  • 只能使用一次的選用比對器：日期時間分隔符 (T) 和時區偏移 (Z 或 +00:00)。

  • 可多次使用的選用元素：連字號 (-)、底線 (_)、半形冒號 (:) 和斜線 (/)。

  • 舉例來說，如果檔案名稱日期時間格式的值為 YYYY-MM-DD/hh_mm_ssZ，則範例物件名稱為 prod_2023-09-25/04_10_00Z_uNiQuE_archive。

  • 如果檔案名稱的日期時間格式結尾不是比對器，該字元會取代 <UTC-date-time> 和 <uuid> 之間的分隔符。舉例來說，如果檔案名稱日期時間格式的值為 YYYY-MM-DDThh_mm_ss-，則範例物件名稱為 prod_2023-09-25T04_10_00-uNiQuE_archive。

檔案批次處理

透過 Cloud Storage 訂閱項目，您可以決定何時要建立新的輸出檔案，並以物件形式儲存在 Cloud Storage bucket 中。只要符合其中一項指定的批次處理條件，Pub/Sub 就會寫入輸出檔案。Cloud Storage 批次處理條件如下：

• Storage 批次作業持續時間上限。這是必要設定。 如果超過指定的最大時間值，Pub/Sub 就會寫入新的輸出檔案。這段時間的計算起點是 Pub/Sub 開始寫入新檔案，終點是檔案完成寫入。舉例來說，如果將最長時間設為 5 分鐘，Pub/Sub 最多會在開始寫入檔案後的 5 分鐘內，完成檔案的寫入作業。系統可能會在達到時長上限前建立新檔案。如未指定值，系統會套用 5 分鐘的預設值。最大時長的適用值如下：

  • 最小值 = 1 分鐘
  • 預設值 = 5 分鐘
  • 最大值 = 10 分鐘

• Storage 批次作業位元組數上限。這項設定為選用項目。如果超過指定的最大位元組值，Cloud Storage 訂閱項目就會寫入新的輸出檔案。以下是適用於位元組數上限的值：

  • 最小值 = 1 KB
  • 最大值 = 10 GiB

• Storage 批次作業訊息數上限。這項設定為選用項目。如果超過指定訊息數量上限，Cloud Storage 訂閱項目就會寫入新的輸出檔案。以下是訊息數上限的適用值：

  • 最小值 = 1000

舉例來說，您可以將最長時長設為 6 分鐘，將最大位元組數設為 2 GB。如果輸出檔案在第 4 分鐘達到 2 GB 的檔案大小，Pub/Sub 就會完成前一個檔案，並開始寫入新檔案。

Cloud Storage 訂閱項目可能會同時將資料寫入 Cloud Storage 值區中的多個檔案。如果您已將訂閱項目設定為每 6 分鐘建立一個新檔案，您可能會發現系統每 6 分鐘會建立多個 Cloud Storage 檔案。

在某些情況下，Pub/Sub 可能會比檔案批次處理條件設定的時間更早開始寫入新檔案。如果訂閱項目收到的訊息大於 Max bytes 值，檔案也可能會超過 Max bytes 值。

檔案格式

建立 Cloud Storage 訂閱項目時，您可以指定要儲存在 Cloud Storage bucket 中的輸出檔案格式為「文字」或「Avro」。

• 文字：訊息會以純文字格式儲存。換行字元 會將訊息與檔案中的前一則訊息分開。系統只會儲存訊息酬載，不會儲存屬性或其他中繼資料。

• Avro：訊息會以 Apache Avro 二進位格式儲存。選取 Avro 時，可以啟用下列其他屬性：

  • 寫入中繼資料：這個選項可讓您儲存訊息中繼資料和訊息。subscription_name、message_id、publish_time 和 attributes 欄位等中繼資料會寫入輸出 Avro 物件的頂層欄位，而資料以外的所有其他訊息屬性 (例如 ordering_key，如果存在的話) 則會新增為 attributes 對映中的項目。

    如果停用「寫入中繼資料」，系統只會將訊息有效負載寫入輸出 Avro 物件。以下是輸出訊息的 Avro 結構定義，其中寫入中繼資料已停用：

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    以下是啟用寫入中繼資料時，輸出訊息的 Avro 結構定義：

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • 使用主題結構定義：選取這個選項後，Pub/Sub 寫入 Avro 檔案時，會使用訂閱項目所連結的 Pub/Sub 主題結構定義。

    使用這個選項時，請務必確認是否符合下列額外規定：

    • 主題結構定義必須採用 Apache Avro 格式。

    • 如果同時啟用「使用主題結構定義」和「寫入中繼資料」，主題結構定義的根層級必須有 Record 物件。Pub/Sub 會展開記錄的欄位清單，納入中繼資料欄位。因此，記錄不得包含與中繼資料欄位 (subscription_name、message_id、publish_time 或 attributes) 同名的欄位。

注意： 如要以 Parquet 格式寫入檔案，將 Pub/Sub 資料串流至 Parquet 檔案的最佳方式，是使用適用於 Apache Iceberg 的 BigQuery 資料表搭配 BigQuery 訂閱項目。詳情請參閱「BigQuery 訂閱項目與 Iceberg 資料表」。

服務帳戶

您可以透過下列方式將訊息寫入 Cloud Storage 值區：

• 設定自訂服務帳戶，只有具備服務帳戶 iam.serviceAccounts.actAs 權限的使用者，才能建立可寫入值區的訂閱項目。包含 iam.serviceAccounts.actAs 權限的角色範例為「服務帳戶使用者」 (roles/iam.serviceAccountUser) 角色。

• 使用預設的 Pub/Sub 服務代理，讓專案中任何有權建立訂閱項目的使用者，都能建立寫入 bucket 的訂閱項目。如未指定自訂服務帳戶，系統會預設使用 Pub/Sub 服務代理。

建立 Cloud Storage 訂閱項目

控制台

1. 前往 Google Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。

   前往「訂閱」頁面

2. 按一下「Create Subscription」 (建立訂閱項目)。

3. 在「Subscription ID」(訂閱項目 ID) 欄位中輸入名稱。

   如要瞭解如何命名訂閱項目，請參閱「主題或訂閱項目命名規範」。

4. 從下拉式選單中選擇或建立主題。

   訂閱項目會接收來自主題的訊息。

   如要瞭解如何建立主題，請參閱「建立及管理主題」。

5. 選取「Delivery type」(傳送類型)，然後選取「Write to Cloud Storage」(寫入 Cloud Storage)。

6. 按一下「Cloud Storage bucket」(Cloud Storage 值區) 的「Browse」(瀏覽)。

   • 您可以從任何適當的專案中選取現有值區。

   • 你也可以按一下建立圖示，然後按照畫面上的指示建立新的值區。

     建立 bucket 後，請選取 Cloud Storage 訂閱方案的 bucket。

     如要進一步瞭解如何建立 bucket，請參閱「建立 bucket」一文。

   指定 bucket 時，Pub/Sub 會檢查 Pub/Sub 服務代理是否具備 bucket 的適當權限。如有權限問題，您會看到類似以下的訊息：Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions。

7. 如果遇到權限問題，請按一下「設定權限」，然後按照畫面上的指示操作。

   或者，按照「將 Cloud Storage 角色指派給 Pub/Sub 服務代理」一文中的操作說明進行。

8. 在「File format」(檔案格式) 中，選取「Text」(文字) 或「Avro」。

   如果選取「Avro」Avro，您也可以選擇是否要在輸出內容中儲存訊息中繼資料。

   如要進一步瞭解這兩個選項，包括 Avro 格式的訊息中繼資料選項，請參閱「檔案格式」一文。

9. 選用：您可以為要寫入 Cloud Storage bucket 的所有檔案指定檔案名稱前置字串、後置字串和日期時間。檔案會以物件形式儲存在 bucket 中。

   如要進一步瞭解如何設定檔案前置字串、後置字串和日期時間，請參閱「檔案名稱前置字串、後置字串和日期時間」。

10. 如果是檔案批次處理，請指定建立新檔案前經過的時間上限。

    您也可以選擇設定檔案大小上限或訊息數量上限。

    如要進一步瞭解這兩種檔案批次處理選項，請參閱「檔案批次處理」。

11. 強烈建議您啟用「Dead lettering」，處理訊息傳送失敗的問題。

    詳情請參閱無法傳送訊息的主題。

12. 其他設定可保留預設值，然後按一下「建立」。

gcloud

1. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

2. 如要建立 Cloud Storage 訂閱項目，請執行 gcloud pubsub subscriptions create 指令。

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --cloud-storage-bucket=BUCKET_NAME \
       --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
       --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
       --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
       --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
       --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
       --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
       --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
       --cloud-storage-write-metadata
       --cloud-storage-use-topic-schema

   如要使用自訂服務帳戶，請以額外引數的形式提供該帳戶：

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --cloud-storage-bucket=BUCKET_NAME \
       --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \
       --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \
       --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \
       --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \
       --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \
       --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \
       --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \
       --cloud-storage-write-metadata
       --cloud-storage-use-topic-schema
       --cloud-storage-service-account-email=SERVICE_ACCOUNT_NAME
       

   在這個指令中，只需要 SUBSCRIPTION_ID、--topic 標記和 --cloud-storage-bucket 標記。其餘旗標為選用，可以省略。

   更改下列內容：

   • SUBSCRIPTION_ID：新 Cloud Storage 訂閱方案的名稱或 ID。
   • TOPIC_ID：主題的名稱或 ID。
   • BUCKET_NAME：指定現有 bucket 的名稱。例如，prod_bucket。儲存空間名稱不得包含專案 ID。如要建立 bucket，請參閱「建立 bucket」一文。
   • CLOUD_STORAGE_FILE_PREFIX：指定 Cloud Storage 檔案名稱的前置字元。例如：log_events_。
   • CLOUD_STORAGE_FILE_SUFFIX：指定 Cloud Storage 檔案名稱的後置字元。例如：.txt。
   • CLOUD_STORAGE_FILE_DATETIME_FORMAT： 指定 Cloud Storage 檔案名稱的日期時間格式。 例如：YYYY-MM-DD/hh_mm_ssZ。
   • CLOUD_STORAGE_MAX_DURATION：建立新的 Cloud Storage 檔案前，可經過的最長時間。值必須介於 1 公尺至 10 公尺之間。例如：5m。
   • CLOUD_STORAGE_MAX_BYTES：可寫入 Cloud Storage 檔案的位元組上限，超過這個上限就會建立新檔案。值必須介於 1 KB 至 10 GB 之間。例如：20MB。
   • CLOUD_STORAGE_MAX_MESSAGES：可寫入 Cloud Storage 檔案的訊息數量上限，超過這個數量就會建立新檔案。這個值必須大於或等於 1000。例如：100000。
   • CLOUD_STORAGE_OUTPUT_FORMAT：寫入 Cloud Storage 的資料輸出格式。可能的值如下：
     • text：訊息會以原始文字形式撰寫，並以換行符分隔。
     • avro：訊息會以 Avro 二進位格式寫入。 --cloud-storage-write-metadata 和 --cloud-storage-use-topic-schema 只會影響輸出格式為 avro 的訂閱項目。
   • SERVICE_ACCOUNT_NAME：指定用於寫入 Cloud Storage 的服務帳戶名稱。

C++

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 C++ 設定說明操作。詳情請參閱 Pub/Sub C++ API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& bucket) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_cloud_storage_config()->set_bucket(bucket);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 C# 設定說明操作。詳情請參閱 Pub/Sub C# API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

using Google.Cloud.PubSub.V1;
using Google.Protobuf.WellKnownTypes;
using System;

public class CreateCloudStorageSubscriptionSample
{
    public Subscription CreateCloudStorageSubscription(string projectId, string topicId, string subscriptionId,
        string bucket, string filenamePrefix, string filenameSuffix, TimeSpan maxDuration)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            CloudStorageConfig = new CloudStorageConfig
            {
                Bucket = bucket,
                FilenamePrefix = filenamePrefix,
                FilenameSuffix = filenameSuffix,
                MaxDuration = Duration.FromTimeSpan(maxDuration)
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Pub/Sub Go API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
	"google.golang.org/protobuf/types/known/durationpb"
)

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, topic, subscription, bucket string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// bucket := "my-bucket" // bucket must not have the gs:// prefix
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		CloudStorageConfig: &pubsubpb.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat: &pubsubpb.CloudStorageConfig_AvroConfig_{
				AvroConfig: &pubsubpb.CloudStorageConfig_AvroConfig{
					WriteMetadata: true,
				},
			},
			MaxDuration: durationpb.New(1 * time.Minute),
			MaxBytes:    1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create cloud storage sub: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

Java

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 Java 設定說明操作。詳情請參閱 Pub/Sub Java API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.protobuf.Duration;
import com.google.pubsub.v1.CloudStorageConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateCloudStorageSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setCloudStorageConfig(cloudStorageConfig)
                  .build());

      System.out.println("Created a CloudStorage subscription: " + subscription.getAllFields());
    }
  }
}

Node.js

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 Pub/Sub Node.js API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName,
  subscriptionName,
  bucket,
  filenamePrefix,
  filenameSuffix,
  maxDuration,
) {
  const options = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

Node.js

在嘗試這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 Pub/Sub Node.js API 參考說明文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicName = 'YOUR_TOPIC_NAME';
// const subscriptionName = 'YOUR_SUBSCRIPTION_NAME';
// const bucket = 'YOUR_BUCKET_ID';
// const filenamePrefix = 'YOUR_FILENAME_PREFIX';
// const filenameSuffix = 'YOUR_FILENAME_SUFFIX';
// const maxDuration = 60;

// Imports the Google Cloud client library
import {CreateSubscriptionOptions, PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createCloudStorageSubscription(
  topicName: string,
  subscriptionName: string,
  bucket: string,
  filenamePrefix: string,
  filenameSuffix: string,
  maxDuration: number,
) {
  const options: CreateSubscriptionOptions = {
    cloudStorageConfig: {
      bucket,
      filenamePrefix,
      filenameSuffix,
      maxDuration: {
        seconds: maxDuration,
      },
    },
  };

  await pubSubClient
    .topic(topicName)
    .createSubscription(subscriptionName, options);

  console.log(
    `Created subscription ${subscriptionName} with a cloud storage configuration.`,
  );
}

PHP

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 PHP 設定說明操作。詳情請參閱 Pub/Sub PHP API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub GCS subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $bucket The Cloud Storage bucket name without any prefix like "gs://".
 */
function create_cloud_storage_subscription($projectId, $topicName, $subscriptionName, $bucket)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = ['bucket' => $bucket];
    $subscription->create([
        'cloudStorageConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

在試用這個範例之前，請先按照「使用用戶端程式庫的 Pub/Sub 快速入門導覽課程」中的 Python 設定說明操作。詳情請參閱 Pub/Sub Python API 參考文件。

如要向 Pub/Sub 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證作業」。

from google.cloud import pubsub_v1
from google.protobuf import duration_pb2

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bucket = "my-bucket"

filename_prefix = "log_events_"
filename_suffix = ".avro"
# Either CloudStorageConfig.AvroConfig or CloudStorageConfig.TextConfig
# defaults to TextConfig
avro_config = pubsub_v1.types.CloudStorageConfig.AvroConfig(write_metadata=True)

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)
max_duration = duration_pb2.Duration()
max_duration.FromSeconds(300)

cloudstorage_config = pubsub_v1.types.CloudStorageConfig(
    bucket=bucket,
    filename_prefix=filename_prefix,
    filename_suffix=filename_suffix,
    avro_config=avro_config,
    # Min 1 minutes, max 10 minutes
    max_duration=max_duration,
    # Min 1 KB, max 10 GiB
    max_bytes=10000000,
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "cloud_storage_config": cloudstorage_config,
        }
    )

print(f"CloudStorage subscription created: {subscription}.")
print(f"Bucket for subscription is: {bucket}")
print(f"Prefix is: {filename_prefix}")
print(f"Suffix is: {filename_suffix}")

監控 Cloud Storage 訂閱方案

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

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

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

後續步驟

• 排解 Cloud Storage 訂閱項目問題。

• 請參閱 Cloud Storage 的相關說明。

• 查看 Pub/Sub 的定價，包括 Cloud Storage 訂閱。