您可以使用 Cloud Storage 匯入主題,持續將資料從 Cloud Storage 擷取至 Pub/Sub。接著,您可以將資料串流至 Pub/Sub 支援的任何目的地。Pub/Sub 會自動偵測新增至 Cloud Storage 值區的新物件,並擷取這些物件。
Cloud Storage 是在Google Cloud中儲存物件的服務。物件是不可變更的資料片段,由任何格式的檔案組成。物件會存放在名為值區的容器中。桶子也可以包含代管資料夾,讓您為共用名稱前置字元的物件群組提供更廣泛的存取權。
如要進一步瞭解 Cloud Storage,請參閱 Cloud Storage 說明文件。
如要進一步瞭解匯入主題,請參閱「關於匯入主題」。
事前準備
您必須先建立 Cloud Storage 值區,才能建立 Cloud Storage 匯入主題。如果您使用主控台建立匯入主題,工作流程會讓您建立 Cloud Storage 值區。如要瞭解其他設定方法,請參閱「建立值區」。
如適用,請確認 Pub/Sub 主題的訊息儲存政策與 Cloud Storage 值區所在的區域重疊。詳情請參閱「郵件儲存空間政策符合值區位置」。
部分 Google Cloud 服務有 Google Cloud代管的服務帳戶,可讓服務存取您的資源。這些服務帳戶稱為服務代理。Pub/Sub 會為每個專案建立服務帳戶,並以
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
格式維護這些帳戶。在 Pub/Sub 服務帳戶上設定必要的角色和權限,以便管理 Cloud Storage 匯入主題,包括:將 Pub/Sub 發布者角色 (
roles/pubsub.publisher
) 授予 Pub/Sub 服務帳戶。這個服務帳戶將發布至匯入主題。如要授予這個角色,您需要具備 Pub/Sub 管理員角色 (roles/pubsub.admin
) 的使用者帳戶。如需更多資訊,請參閱「將 Pub/Sub 發布者角色新增至 Pub/Sub 服務帳戶」。將 Cloud Storage 權限授予 Pub/Sub 服務帳戶。如要授予這些權限,您必須使用具有儲存空間管理員角色 (
roles/storage.admin
)的使用者帳戶。如需更多資訊,請參閱「將 Cloud Storage 角色指派給 Pub/Sub 服務帳戶」。
必要角色和權限
如要取得建立及管理 Cloud Storage 匯入主題所需的權限,請要求管理員為您的主題或專案授予 Pub/Sub 編輯者 (roles/pubsub.editor
) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。
這個預先定義的角色包含建立及管理 Cloud Storage 匯入主題所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:
所需權限
您必須具備下列權限,才能建立及管理 Cloud Storage 匯入主題:
-
建立匯入主題:
pubsub.topics.create
-
刪除匯入主題:
pubsub.topics.delete
-
取得匯入主題:
pubsub.topics.get
-
列出匯入主題:
pubsub.topics.list
-
發布至匯入主題:
pubsub.topics.publish
-
更新匯入主題:
pubsub.topics.update
-
取得匯入主題的身分與存取權管理政策:
pubsub.topics.getIamPolicy
-
為匯入主題設定 IAM 政策:
pubsub.topics.setIamPolicy
您可以在專案層級和個別資源層級設定存取權控管。
訊息儲存政策符合值區位置
Pub/Sub 主題的訊息儲存政策必須與 Cloud Storage bucket 所在的區域重疊。這項政策會決定 Pub/Sub 可儲存訊息資料的位置。
如果值區的位置類型為地區:政策必須包含該特定地區。舉例來說,如果您的值區位於
us-central1
區域,訊息儲存空間政策也必須包含us-central1
。如果值區的位置類型為雙地區或多地區:政策中必須至少包含一個雙地區或多地區位置。舉例來說,如果您的值區位於
US multi-region
,訊息儲存空間政策可以包含us-central1
、us-east1
或US multi-region
內的任何其他區域。如果政策未納入值區,就無法建立主題。舉例來說,如果您的儲存桶位於
europe-west1
,而訊息儲存政策只包含asia-east1
,您就會收到錯誤訊息。如果訊息儲存空間政策只包含一個與值區位置重疊的區域,多地區備援功能可能會受到影響。這是因為如果該區域無法使用,您可能無法存取資料。為確保完整的備援機制,建議您在訊息儲存空間政策中加入至少兩個區域,這些區域必須是值區的多地區或雙地區位置。
如要進一步瞭解值區位置,請參閱說明文件。
啟用發布功能
如要啟用發布功能,您必須將 Pub/Sub 發布者角色指派給 Pub/Sub 服務帳戶,讓 Pub/Sub 能夠發布至 Cloud Storage 匯入主題。
啟用發布至所有 Cloud Storage 匯入主題的功能
如果專案中沒有可用的 Cloud Storage 匯入主題,請選擇這個選項。
前往 Google Cloud 控制台的「IAM」頁面。
選取「包含 Google提供的角色授予項目」核取方塊。
尋找格式如下的 Pub/Sub 服務帳戶:
service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
針對這個服務帳戶,按一下「Edit Principal」(編輯主體) 按鈕。
如有需要,請按一下「新增其他角色」。
搜尋並選取「Pub/Sub 發布者角色」 (
roles/pubsub.publisher
)。按一下 [儲存]。
啟用發布至單一 Cloud Storage 匯入主題的功能
如要授予 Pub/Sub 權限,讓它能夠發布至現有的特定 Cloud Storage 匯入主題,請按照下列步驟操作:
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
執行
gcloud pubsub topics add-iam-policy-binding
指令:gcloud pubsub topics add-iam-policy-binding TOPIC_ID\ --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com"\ --role="roles/pubsub.publisher"
更改下列內容:
TOPIC_ID 是 Cloud Storage 匯入主題的 ID 或名稱。
PROJECT_NUMBER 是專案編號。如要查看專案編號,請參閱「識別專案」。
將 Cloud Storage 角色指派給 Pub/Sub 服務帳戶
如要建立 Cloud Storage 匯入主題,Pub/Sub 服務帳戶必須具備從特定 Cloud Storage 值區讀取的權限。必須具備下列權限:
storage.objects.list
storage.objects.get
storage.buckets.get
如要將這些權限指派給 Pub/Sub 服務帳戶,請選擇下列任一程序:
在值區層級授予權限。針對特定 Cloud Storage 值區,將 Storage 舊版物件讀取者 (
roles/storage.legacyObjectReader
) 角色和 Storage 舊版值區讀取者 (roles/storage.legacyBucketReader
) 角色授予 Pub/Sub 服務帳戶。如果您必須在專案層級授予角色,建議您改為在包含 Cloud Storage 值區的專案中授予「儲存空間管理員」(
roles/storage.admin
) 角色。將這個角色授予 Pub/Sub 服務帳戶。
值區權限
請按照下列步驟,將 Storage 舊版物件讀取者 (roles/storage.legacyObjectReader
) 角色和 Storage 舊版值區讀取者 (roles/storage.legacyBucketReader
) 角色授予 Pub/Sub 服務帳戶,層級為值區:
前往 Google Cloud 控制台的「Cloud Storage」頁面。
按一下要讀取訊息的 Cloud Storage 值區,然後匯入至 Cloud Storage 匯入主題。
「Bucket details」(值區詳細資料) 頁面隨即開啟。
在「Bucket details」(值區詳細資料) 頁面中,按一下「Permissions」(權限) 分頁標籤。
在「Permissions」 >「View by Principals」分頁中,按一下「Grant access」。
系統隨即會開啟「授予存取權」頁面。
在「Add Principals」(新增主體) 部分中,輸入 Pub/Sub 服務帳戶的名稱。
服務帳戶的格式為
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
。舉例來說,如果專案的 PROJECT_NUMBER 為112233445566
,服務帳戶的格式為service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
。在「指派角色」 >「請選擇角色」下拉式選單中,輸入
Object Reader
,然後選取「Storage Legacy Object Reader」角色。按一下 [Add another role] (新增其他角色)。
在「Select a role」(請選擇角色) 下拉式選單中,輸入
Bucket Reader
,然後選取「Storage Legacy Bucket Reader」(Storage 舊版 Bucket Reader) 角色。按一下 [儲存]。
專案權限
如要在專案層級授予「儲存空間管理員」(roles/storage.admin
) 角色,請執行下列步驟:
前往 Google Cloud 控制台的「IAM」頁面。
在「Permissions」 >「View by Principals」分頁中,按一下「Grant access」。
系統隨即會開啟「授予存取權」頁面。
在「Add Principals」(新增主體) 部分中,輸入 Pub/Sub 服務帳戶的名稱。
服務帳戶的格式為
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
。舉例來說,如果專案的 PROJECT_NUMBER 為112233445566
,服務帳戶的格式為service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
。在「Assign roles」 >「Select a role」下拉式選單中,輸入
Storage Admin
,然後選取「Storage Admin」角色。按一下 [儲存]。
如要進一步瞭解 Cloud Storage IAM,請參閱「Cloud Storage 身分與存取權管理」。
Cloud Storage 匯入主題的屬性
如要進一步瞭解所有主題的共同屬性,請參閱「主題的屬性」。
值區名稱
這是 Cloud Storage 值區的名稱,Pub/Sub 會從這個值區讀取發布至 Cloud Storage 匯入主題的資料。
輸入格式
建立 Cloud Storage 匯入主題時,您可以指定要擷取的物件格式,例如 Text、Avro 或 Pub/Sub Avro。
文字。系統會假設物件會儲存純文字資料。只要物件符合物件建立時間下限,且符合glob 模式條件,這個輸入格式就會嘗試擷取 bucket 中的所有物件。
分隔符。您也可以指定分隔符,藉此將物件拆分為訊息。如果未設定,則預設為換行字元 (
\n
)。分隔符號只能是單一字元。Avro。物件採用 Apache Avro 二進位格式。系統不會擷取任何非有效 Apache Avro 格式的物件。以下是 Avro 的限制:
- 不支援 Avro 1.1.0 和 1.2.0 版。
- Avro 區塊的大小上限為 16 MB。
Pub/Sub Avro。物件採用 Apache Avro 二進位檔格式,且結構定義與使用 Pub/Sub Cloud Storage 訂閱的 Avro 檔案格式寫入 Cloud Storage 的物件相符。以下是 Pub/Sub Avro 的重要規範:
Avro 記錄的資料欄位會用來填入產生 Pub/Sub 訊息的資料欄位。
如果為 Cloud Storage 訂閱指定 write_metadata 選項,屬性欄位中的任何值都會填入為產生 Pub/Sub 訊息的屬性。
如果在寫入 Cloud Storage 的原始訊息中指定排序鍵,系統會在產生的 Pub/Sub 訊息中,將這個欄位填入名為
original_message_ordering_key
的屬性。
物件建立時間下限
建立 Cloud Storage 匯入主題時,您可以選擇指定物件建立時間下限。系統只會擷取在這個時間戳記當天或之後建立的物件。這個時間戳記必須以 YYYY-MM-DDThh:mm:ssZ
的格式提供。從 0001-01-01T00:00:00Z
到 9999-12-31T23:59:59Z
的任何日期 (包括兩者之間的日期) 皆有效。
比對 glob 模式
建立 Cloud Storage 匯入主題時,您可以選擇指定相符的 glob 模式。系統只會擷取名稱符合此模式的物件。舉例來說,如要擷取所有附有 .txt
字尾的物件,您可以將 glob 模式指定為 **.txt
。
如要進一步瞭解支援的 glob 模式語法,請參閱 Cloud Storage 說明文件。
使用 Cloud Storage 匯入主題
您可以建立新的匯入主題,或編輯現有主題。
注意事項
- 即使快速依序建立主題和訂閱項目,也可能導致資料遺失。在訂閱前,您可以短暫地查看該主題。如果在這個時間內有任何資料傳送至主題,就會遺失。請先建立主題、建立訂閱項目,然後再將主題轉換為匯入主題,這樣就能確保在匯入程序中不會遺漏任何訊息。
建立 Cloud Storage 匯入主題
如要建立 Cloud Storage 匯入主題,請按照下列步驟操作:
控制台
-
前往 Google Cloud 控制台的「Topics」頁面。
-
按一下「建立主題」。
主題詳細資料頁面隨即開啟。
-
在「Topic ID」欄位中,輸入 Cloud Storage 匯入主題的 ID。
如要進一步瞭解主題命名方式,請參閱命名規範。
-
選取「Add a default subscription」。
-
選取「啟用擷取」。
-
在「擷取來源」中,選取「Google Cloud Storage」。
-
在 Cloud Storage bucket 中,按一下「Browse」。
「Select bucket」(選取值區) 頁面隨即開啟。選取下列選項之一:
-
從任何適當的專案中選取現有值區。
-
按一下建立圖示,然後按照畫面上的指示建立新的值區。建立值區後,請選取 Cloud Storage 匯入主題的值區。
-
-
指定值區時,Pub/Sub 會檢查 Pub/Sub 服務帳戶的值區是否具備適當權限。如果發生權限問題,您會看到類似以下的訊息:
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.
如果發生權限問題,請按一下「設定權限」。詳情請參閱「為 Pub/Sub 服務帳戶授予 Cloud Storage 權限」。
-
在「Object format」(物件格式) 中,選取「Text」、「Avro」或「Pub/Sub Avro」。
如果您選取「文字」,可以選擇指定分隔符,用來將物件分割成訊息。
如要進一步瞭解這些選項,請參閱「輸入格式」。
- (非必要) 您可以為主題指定物件建立時間下限。如果已設定,系統只會擷取在物件建立時間下限後建立的物件。
詳情請參閱「物件建立時間下限」。
- 您必須指定 Glob 模式。如要擷取 bucket 中的所有物件,請使用
**
做為 glob 模式。如果已設定,系統只會擷取符合指定模式的物件。詳情請參閱「比對 glob 模式」。
- 保留其他預設設定。
- 按一下「建立主題」。
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
執行
gcloud pubsub topics create
指令:gcloud pubsub topics create TOPIC_ID\ --cloud-storage-ingestion-bucket=BUCKET_NAME\ --cloud-storage-ingestion-input-format=INPUT_FORMAT\ --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\ --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\ --cloud-storage-ingestion-match-glob=MATCH_GLOB
在指令中,只有
TOPIC_ID
、--cloud-storage-ingestion-bucket
標記和--cloud-storage-ingestion-input-format
標記是必要的。其餘的旗標為選用,可以省略。更改下列內容:
-
TOPIC_ID:主題的名稱或 ID。
-
BUCKET_NAME:指定現有值區的名稱。例如:
prod_bucket
。值區名稱不得包含專案 ID。如要建立值區,請參閱「建立值區」。 -
INPUT_FORMAT:指定攝入物件的格式。這可以是
text
、avro
或pubsub_avro
。如要進一步瞭解這些選項,請參閱「輸入格式」。 -
TEXT_DELIMITER:指定用於將文字物件拆分為 Pub/Sub 訊息的分隔符。這應該是單一字元,且只應在
INPUT_FORMAT
為text
時設定。預設為換行字元 (\n
)。使用 gcloud CLI 指定分隔符時,請特別留意如何處理特殊字元,例如換行符號
\n
。請使用'\n'
格式,確保系統能正確解讀分隔符。只要使用\n
而不加上引號或轉義,就會產生"n"
分隔符。 -
MINIMUM_OBJECT_CREATE_TIME:指定物件建立後,可供攝入的最低時間。格式應為
YYYY-MM-DDThh:mm:ssZ
,以世界標準時間為準。例如:2024-10-14T08:30:30Z
。從
0001-01-01T00:00:00Z
到9999-12-31T23:59:59Z
之間的任何日期 (包括兩者) 皆有效。 -
MATCH_GLOB:指定要比對的 glob 模式,以便擷取物件。使用 gcloud CLI 時,如果比對萬用字元含有
*
字元,則*
字元必須以\*\*.txt
的形式加上反斜線轉義,或是整個比對萬用字元必須以"**.txt"
或'**.txt'
加上引號。如要進一步瞭解支援的 glob 模式語法,請參閱 Cloud Storage 說明文件。
-
Go
在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Go。詳情請參閱 Pub/Sub Go API 參考說明文件。
如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Java
在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Pub/Sub Java API 參考說明文件。
如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Node.js。詳情請參閱 Pub/Sub Node.js API 參考說明文件。
如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Python
在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 Pub/Sub Python API 參考說明文件。
如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
C++
在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 C++。詳情請參閱 Pub/Sub C++ API 參考說明文件。
如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
Node.js (TypeScript)
在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Node.js 環境。 詳情請參閱 Pub/Sub Node.js API 參考說明文件。
如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。
如果發生問題,請參閱「排解 Cloud Storage 匯入問題」一文。
編輯 Cloud Storage 匯入主題
您可以編輯 Cloud Storage 匯入主題,更新其屬性。
舉例來說,如要重新開始擷取,您可以變更桶或更新最短物件建立時間。
如要編輯 Cloud Storage 匯入主題,請按照下列步驟操作:
控制台
-
前往 Google Cloud 控制台的「Topics」頁面。
-
按一下 Cloud Storage 匯入主題。
-
在主題詳細資料頁面中,按一下「編輯」。
-
更新要變更的欄位。
-
按一下「更新」。
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
為避免遺失匯入主題的設定,請務必每次更新主題時都納入所有設定。如果您略過某些項目,Pub/Sub 會將設定重設為原始預設值。
使用下列範例中提到的所有標記,執行
gcloud pubsub topics update
指令:gcloud pubsub topics update TOPIC_ID \ --cloud-storage-ingestion-bucket=BUCKET_NAME\ --cloud-storage-ingestion-input-format=INPUT_FORMAT\ --cloud-storage-ingestion-text-delimiter=TEXT_DELIMITER\ --cloud-storage-ingestion-minimum-object-create-time=MINIMUM_OBJECT_CREATE_TIME\ --cloud-storage-ingestion-match-glob=MATCH_GLOB
更改下列內容:
-
TOPIC_ID 是主題 ID 或名稱。這個欄位無法更新。
-
BUCKET_NAME:指定現有值區的名稱。例如:
prod_bucket
。值區名稱不得包含專案 ID。如要建立值區,請參閱「建立值區」。 -
INPUT_FORMAT:指定攝入物件的格式。這可以是
text
、avro
或pubsub_avro
。如要進一步瞭解這些選項,請參閱「 輸入格式」。 -
TEXT_DELIMITER:指定用於將文字物件拆分為 Pub/Sub 訊息的分隔符。這應該是單一字元,且只應在
INPUT_FORMAT
為text
時設定。預設為換行字元 (\n
)。使用 gcloud CLI 指定分隔符時,請特別留意如何處理特殊字元,例如換行符號
\n
。請使用格式'\n'
,確保正確解讀分隔符。只要使用\n
而不加上引號或轉義,就會產生"n"
分隔符。 -
MINIMUM_OBJECT_CREATE_TIME:指定物件建立後,可供攝入的最低時間。格式應為
YYYY-MM-DDThh:mm:ssZ
,以世界標準時間為準。例如:2024-10-14T08:30:30Z
。從
0001-01-01T00:00:00Z
到9999-12-31T23:59:59Z
之間的任何日期 (包括兩者) 皆有效。 -
MATCH_GLOB:指定要比對的 glob 模式,以便擷取物件。使用 gcloud CLI 時,如果比對萬用字元含有
*
字元,則*
字元必須以\*\*.txt
的形式加上反斜線轉義,或是整個比對萬用字元必須以"**.txt"
或'**.txt'
加上引號。如要進一步瞭解支援的 glob 模式語法,請參閱 Cloud Storage 說明文件。
-
Cloud Storage 匯入主題的配額和限制
匯入主題的發布者傳送量受限於主題的發布配額。詳情請參閱「Pub/Sub 配額和限制」。