排解 BigQuery 訂閱問題

本頁提供 BigQuery 訂閱項目的常見疑難排解提示。

查看 BigQuery 訂閱項目的狀態

如要查看訂閱狀態，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的 Pub/Sub 訂閱項目頁面。

    前往「訂閱項目」頁面

  2. 查看 BigQuery 訂閱項目的「狀態」圖示。

    如果圖示是綠色勾號，代表訂閱項目狀態良好。

    如果圖示是紅色驚嘆號，表示訂閱方案處於錯誤狀態。

  3. 按一下 BigQuery 訂閱項目。

    系統會開啟訂閱詳細資料頁面。

  4. 查看「訂閱狀態」中的錯誤訊息。

  5. 請根據錯誤訊息，前往本頁的相關章節排解問題。

問題解決後，訂閱項目最終會恢復正常狀態。

無法建立或更新訂閱項目

如果您無法建立或更新 BigQuery 訂閱項目，可能是遇到下列常見問題。

找不到資料表錯誤

如果您在建立或更新訂閱項目工作流程中指定的資料表不存在，工作流程就會傳回找不到資料表的錯誤。在 Google Cloud 控制台中，訊息類似於下列內容：

The BigQuery table or dataset specified cannot be found.

如要解決這個問題，請建立資料表，並確保您可以在透過 BigQuery 訂閱項目使用資料表之前，檢查資料表的狀態。

結構定義不符錯誤

如果資料表和主題的結構定義不相容，建立或更新訂閱項目工作流程就會傳回結構定義不符的錯誤。在 Google Cloud 控制台中，訊息類似於下列內容：

Incompatible schema type for field project_ids: expected INT64, got STRING

指定的錯誤訊息是針對名為「project_ids」的欄位，指出結構定義不相符。 視結構定義不符的類型而定，您可能會看到不同版本的錯誤訊息。

如要解決這個問題，請檢查結構化資料對應是否相容。

服務帳戶錯誤

如果未設定 Pub/Sub 服務帳戶的正確權限，建立或更新訂閱項目的工作流程就會傳回錯誤。在 Google Cloud 控制台中，訊息類似於下列內容：

Service account service-1234234234@gcp-sa-pubsub.iam.gserviceaccount.com
is missing permissions required to write to the BigQuery table:
bigquery.tables.get, bigquery.tables.updateData.

如要解決這個問題，請檢查服務帳戶是否具備正確的權限。

訂閱狀態顯示紅色驚嘆號

如果您在建立訂閱項目後編輯資料表，可能會影響 Pub/Sub 將訊息寫入資料表的方式。如果變更導致問題，訂閱項目的狀態欄位會設為錯誤狀態。

在訂閱詳細資料頁面中，檢查「Subscription state」欄位的狀態。 Subscription state 欄位會提供更具體的錯誤，可能如下所示：

  • 找不到資料表：資料表已刪除。建立資料表並檢查資料表狀態。請參閱「取得資料表資訊」。

  • 資料表權限遭拒：Pub/Sub 服務帳戶不再具備寫入資料表的權限。檢查服務帳戶是否具備正確的權限。

  • 資料表結構定義不符：資料表結構定義與 BigQuery 訂閱設定不再相容。確認結構定義對應是否相容。

如果 Pub/Sub 訂閱項目處於錯誤狀態，系統不會將訊息寫入 BigQuery 資料表，而是保留在訂閱項目的待處理工作中。請注意，如果已設定，訊息不會傳送至附加的無效信件主題。未確認的訊息會保留 message_retention_duration 中設定的期間(預設為 7 天)。

積壓的工作越來越多

如果訂閱項目中累積大量待處理訊息，或訊息傳送至訂閱項目的死信主題，請查看下列可能原因。

INVALID_ARGUMENT 錯誤訊息

如果提供的訊息格式在 Pub/Sub 服務中有效，但在 BigQuery 目的地資料表結構定義中無效，就會發生這個錯誤。也就是說，訊息中有一或多個欄位的值不符合 BigQuery 資料表結構定義的規定。請查看架構相容性，確認資料類型和格式正確無誤。常見錯誤包括：

  • 空字串 ("") 不是有效的 JSON。將資料傳送至可為空值的 JSON BigQuery 資料表欄時，請提供空 JSON 物件 ({})、null 或空 JSON 字串 ("\"\"")，代表缺少值。傳送空白字串會導致錯誤。

  • 如果訊息欄位值超過 BigQuery 欄位的長度上限，訊息會因大小限制而無法傳送。

如要排解 INVALID_ARGUMENT 錯誤，請將dead-letter 主題新增至感興趣的訂閱項目。dead-letter 主題會擷取無法寫入 BigQuery 的訊息，以及名為 CloudPubSubDeadLetterSourceDeliveryErrorMessage 的屬性，說明失敗原因。

您也可以在Metrics Explorer中查看這些傳送失敗情形。選取指標 pubsub.googleapis.com/subscription/push_request_count，然後依 response_code=invalid_argument 篩選。

RESOURCE_EXHAUSTED 錯誤訊息

如果訊息寫入 BigQuery 的速度緩慢，您可能需要提高專案的 Pub/Sub 推送配額或 BigQuery 儲存空間寫入輸送量配額。如要確認是否遇到配額限制，請檢查推送要求指標 (subscription/push_request_count) 是否有任何 resource_exhausted 錯誤。

如要診斷配額問題，也可以查看專案的配額。在包含 Pub/Sub 資源或 BigQuery 執行個體的專案中，依序前往「IAM 與管理」>「配額」。搜尋相關配額，例如 pubsub.googleapis.com/regionalpushsubscriber 或 bigquerystorage.googleapis.com/write/append_bytes。如果需要增加任一配額，可以申請調整配額。

以小時為單位的分區資料表，分區 ID 資料欄中顯示 __UNPARTITIONED__

如果 BigQuery 目的地資料表是依小時分區，資料列一開始會進入 INFORMATION_SCHEMA.PARTITIONS 檢視畫面中標示為 __UNPARTITIONED__ 的特殊分區。 這是使用擷取時間分區的資料表預期會發生的行為。

BigQuery 會使用串流緩衝區，盡量提升寫入程序效率。資料可能會保留在 __UNPARTITIONED__ 分區，直到累積足夠的資料量或至少經過一小時為止。符合這些條件後，BigQuery 會將資料重新分區到適當的小時分區。

您可以使用 INFORMATION_SCHEMA.PARTITIONS 檢視畫面，監控 __UNPARTITIONED__ 分區中的資料。

後續步驟

  • 如果 BigQuery 訂閱方案仍有問題，請參閱「取得支援」。