このページでは、BigQuery サブスクリプションの一般的なトラブルシューティングのヒントを紹介します。
BigQuery のサブスクリプションの状態を確認する
サブスクリプションの状態を確認するには、次の手順に従います。
Google Cloud コンソールで、Pub/Sub サブスクリプション ページに移動します。
BigQuery サブスクリプションの [状態] のアイコンを確認します。
アイコンが緑色のチェックマークの場合、サブスクリプションは正常です。
アイコンが赤色の感嘆符の場合、サブスクリプションはエラー状態です。
BigQuery のサブスクリプションをクリックします。
[サブスクリプションの詳細] ページが開きます。
[サブスクリプションの状態] でエラー メッセージを確認します。
エラー メッセージに応じて、このページの関連するセクションに移動し、問題のトラブルシューティングを行ってください。
問題が解決すると、サブスクリプションは最終的に正常な状態に戻ります。
サブスクリプションを作成または更新できない
ここでは、BigQuery サブスクリプションの作成または更新で問題が発生した場合に発生する可能性のある一般的な問題の一部について説明します。
表が見つからないエラー
サブスクリプションの作成または更新ワークフローで指定したテーブルが存在しない場合、ワークフローは「テーブルが見つかりません」というエラーを返します。 Google Cloud コンソールでは、メッセージは次のようになります。
The BigQuery table or dataset specified cannot be found.
この問題を解決するには、テーブルを作成し、BigQuery サブスクリプションで使用する前にそのstateを確認するようにしてください。
スキーマ不一致エラー
テーブルとトピックのスキーマに互換性がない場合、サブスクリプションの作成または更新ワークフローはスキーマ不一致エラーを返します。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 エラーが発生していないか確認します。
割り当ての問題を診断する別の方法は、プロジェクトの割り当てを確認することです。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 サブスクリプションの問題が解決しない場合は、サポートの利用をご覧ください。