BigQuery サブスクリプションのトラブルシューティング

このページでは、BigQuery サブスクリプションの一般的なトラブルシューティングのヒントをいくつか紹介します。

BigQuery サブスクリプションの状態を確認する

サブスクリプションの状態を確認する手順は次のとおりです。

  1. コンソールで、Pub/Sub サブスクリプション ページに移動します。 Google Cloud

    [サブスクリプション] に移動

  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 フィールドには、より具体的なエラーが含まれます。それは次のいずれかです。

  • table not found: テーブルが削除されています。テーブルを作成して、テーブルの状態を確認します。テーブル情報を取得するをご覧ください。

  • テーブルの権限が拒否された: Pub/Sub サービス アカウントには、テーブルへの書き込み権限がなくなりました。サービス アカウントに正しい権限が付与されているかどうか確認します。

  • テーブル スキーマの不一致: テーブル スキーマと BigQuery サブスクリプションの設定の互換性がなくなりました。スキーマ マッピングに互換性があるかどうかを確認します。

Pub/Sub サブスクリプションがエラー状態の場合、メッセージは BigQuery テーブルに書き込まれず、サブスクリプションのバックログに残ります。構成されている場合、アタッチされたデッドレター トピックにはメッセージが配信されないことに注意してください。未確認メッセージは、message_retention_duration で設定された期間（デフォルトでは 7 日間）保持されます。

バックログが蓄積している

サブスクリプションにメッセージのバックログが蓄積されている場合や、サブスクリプションのデッドレター トピックにメッセージが送信されている場合は、次の考えられる原因を確認してください。

INVALID_ARGUMENT エラー メッセージ

このエラーは、指定されたメッセージの形式が Pub/Sub では有効と見なされるが、BigQuery の宛先テーブル スキーマでは有効と見なされない場合に発生します。つまり、メッセージの 1 つ以上のフィールドに、BigQuery テーブル スキーマで許可されていない値が含まれているといことです。スキーマの互換性を確認して、データ型と形式が正しいことを確認します。最も一般的なエラーには、次のようなものがあります。

  • 空の文字列（""）は有効な JSON ではありません。null に成り得る JSON BigQuery テーブル列にデータを送信する場合は、空の JSON オブジェクト ({})、null、または空の JSON 文字列 ("\"\"") をいずれか指定して、欠落値を示します。空の文字列を送信するとエラーが発生します。

  • メッセージ フィールドの値が BigQuery フィールドの最大長を超えると、サイズの制限によりメッセージが失敗します。

INVALID_ARGUMENT エラーのトラブルシューティングを行うには、対象のサブスクリプションにデッドレター トピックを追加します。デッドレター トピックは、BigQuery に書き込めなかったというメッセージと、失敗の理由を説明する CloudPubSubDeadLetterSourceDeliveryErrorMessage という属性をキャプチャします。

これらの配信エラーは Metrics Explorer でも確認できます。指標 pubsub.googleapis.com/subscription/push_request_count を選択し、response_code=invalid_argument でフィルタします。

RESOURCE_EXHAUSTED エラー メッセージ

メッセージが BigQuery にゆっくりと書き込まれている場合は、プロジェクトの Pub/Sub push 割り当てまたは BigQuery ストレージ書き込みスループット割り当てを増やす必要があります。割り当て制限が発生しているかどうかを確認するには、push リクエスト指標（subscription/push_request_count）に resource_exhausted エラーがないか確認します。

割り当ての問題を診断するもう 1 つの方法は、プロジェクトの割り当てを確認することです。Pub/Sub リソースまたは BigQuery インスタンスを含むプロジェクトで、[IAM と管理者] > [割り当て] に移動します。関連する割り当て（pubsub.googleapis.com/regionalpushsubscriber または bigquerystorage.googleapis.com/write/append_bytes）を検索します。いずれかの割り当ての増加が必要な場合は、割り当ての調整をリクエストできます。

パーティション ID 列に __UNPARTITIONED__ と表示される時間単位のパーティション分割テーブル

BigQuery の宛先テーブルが時間単位でパーティショニングされている場合、行は最初に INFORMATION_SCHEMA.PARTITIONS ビュー内の __UNPARTITIONED__ というラベルの特別なパーティションに格納されます。これは、取り込み時間パーティショニングを使用するテーブルでは想定内の動作です。

BigQuery では、書き込みプロセスを最適化するためにストリーミング バッファを使用しています。 十分な量のデータが蓄積されるか、1 時間以上経過するまで、データは __UNPARTITIONED__ パーティションに存在する可能性があります。これらの条件が満たされると、BigQuery はデータを適切な時間単位のパーティションに再パーティショニングします。

__UNPARTITIONED__ パーティション内のデータは、INFORMATION_SCHEMA.PARTITIONS ビューを使用してモニタリングできます。

次のステップ

  • BigQuery サブスクリプションに問題がまだある場合は、サポートの利用をご覧ください。