このページでは、BigQuery サブスクリプションに関する一般的なトラブルシューティングのヒントを紹介します。
BigQuery サブスクリプションの状態を確認する
サブスクリプションの状態を確認する手順は次のとおりです。
Google Cloud コンソールで、Pub/Sub サブスクリプション ページに移動します。
BigQuery サブスクリプションの [状態] のアイコンを確認します。
アイコンが緑色のチェックマークの場合は、サブスクリプションは正常です。
アイコンが赤色の感嘆符の場合は、サブスクリプションがエラー状態です。
BigQuery サブスクリプションをクリックします。
[サブスクリプションの詳細] ページが開きます。
[サブスクリプションの状態] でエラー メッセージを確認します。
エラー メッセージに応じて、このページの該当するセクションに移動して、問題のトラブルシューティングを行います。
問題が解決すると、最終的にサブスクリプションは正常な状態に戻ります。
サブスクリプションを作成または更新できない
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 はデータを適切な時間単位のパーティションに再パーティショニングします。
INFORMATION_SCHEMA.PARTITIONS ビューを使用すると、__UNPARTITIONED__ パーティション内のデータをモニタリングできます。
次のステップ
- BigQuery サブスクリプションに問題がまだある場合は、サポートの利用をご覧ください。