このドキュメントでは、BigQuery サブスクリプションの作成方法について説明します。BigQuery サブスクリプションを作成するには、Google Cloud コンソール、Google Cloud CLI、クライアント ライブラリ、または Pub/Sub API を使用できます。
準備
このドキュメントを読む前に、次の内容をよく理解しておいてください。
サブスクリプションの仕組み。
BigQuery サブスクリプションのワークフロー。
メッセージ エラーを処理するデッドレター トピックを構成する方法。
BigQuery サブスクリプションを作成する前に、Pub/Sub と BigQuery に精通しているだけでなく、次の前提条件を満たしていることを確認してください。
BigQuery テーブルが存在している。あるいは、このドキュメントの後半のセクションで説明するように、BigQuery サブスクリプションの作成時に作成することもできます。
Pub/Sub トピックのスキーマと BigQuery テーブルの間の互換性。互換性のない BigQuery テーブルを追加すると、互換性に関連するエラー メッセージが出力されます。詳細については、スキーマの互換性をご覧ください。
必要なロールと権限
ロールと権限に関するガイドラインは次の一覧に示すとおりです。
サブスクリプションを作成するには、プロジェクト レベルでアクセス制御を構成する必要があります。
このセクションで後述するように、サブスクリプションとトピックが異なるプロジェクトにある場合は、リソースレベルの権限も必要です。
BigQuery サブスクリプションを作成するには、Pub/Sub サービス アカウントに特定の BigQuery テーブルへの書き込み権限が付与されている必要があります。これらの権限を付与する方法について詳しくは、このドキュメントの次のセクションをご覧ください。
プロジェクト内の BigQuery サブスクリプションを構成して、別のプロジェクトの BigQuery テーブルに書き込むことができます。
BigQuery サブスクリプションの作成に必要な権限を取得するには、管理者にプロジェクトに対する Pub/Sub 編集者 (roles/pubsub.editor
)IAM ロールを付与するよう依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。
この事前定義ロールには、BigQuery サブスクリプションの作成に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
BigQuery サブスクリプションを作成するには、次の権限が必要です。
-
サブスクリプションから pull する:
pubsub.subscriptions.consume
-
サブスクリプションを作成する:
pubsub.subscriptions.create
-
サブスクリプションを削除する:
pubsub.subscriptions.delete
-
サブスクリプションを取得する:
pubsub.subscriptions.get
-
サブスクリプションを一覧表示する:
pubsub.subscriptions.list
-
サブスクリプションを更新する:
pubsub.subscriptions.update
-
サブスクリプションをトピックに接続する:
pubsub.topics.attachSubscription
-
サブスクリプションの IAM ポリシーを取得する:
pubsub.subscriptions.getIamPolicy
-
サブスクリプションの IAM ポリシーを構成する:
pubsub.subscriptions.setIamPolicy
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
別のプロジェクトのトピックに関連付けられているプロジェクトで BigQuery サブスクリプションを作成する必要がある場合は、トピック管理者にトピックに対する Pub/Sub 編集者の (roles/pubsub.editor)
IAM ロールも付与するよう依頼してください。
Pub/Sub サービス アカウントに BigQuery のロールを割り当てる
一部の Google Cloud サービスには Google Cloud管理のサービス アカウントがあり、このサービスを利用してユーザーのリソースにアクセスできます。これらのサービス アカウントは、サービス エージェントと呼ばれます。Pub/Sub は、プロジェクトごとに service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
形式のサービス アカウントを作成し、維持します。
BigQuery サブスクリプションを作成するには、Pub/Sub サービス アカウントに、特定の BigQuery テーブルへの書き込みとテーブル メタデータの読み取りを行う権限が必要です。
Pub/Sub サービス アカウントに BigQuery データ編集者(roles/bigquery.dataEditor
)ロールを付与します。
Google Cloud コンソールの [IAM] ページに移動します。
[アクセス権を付与] をクリックします。
[プリンシパルを追加] セクションに、Pub/Sub サービス アカウントの名前を入力します。サービス アカウントの形式は
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
です。たとえば、project-number=112233445566
を使用するプロジェクトの場合、サービス アカウントの形式はservice-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
です。[ロールの割り当て] セクションで、[別のロールを追加] をクリックします。
[ロールを選択] プルダウンに「
BigQuery
」と入力し、[BigQuery データ編集者のロール] を選択します。[保存] をクリックします。
BigQuery IAM の詳細については、BigQuery のロールと権限をご覧ください。
BigQuery サブスクリプション プロパティ
BigQuery のサブスクリプションを構成するときに、次のプロパティを指定できます。
共通の特徴
すべてのサブスクリプションで設定できる共通のサブスクリプション プロパティについて学習します。
トピック スキーマを使用する
このオプションにより、Pub/Sub は、サブスクリプションが接続されている Pub/Sub トピックのスキーマを使用できます。さらに、Pub/Sub はメッセージ内のフィールドを BigQuery テーブル内の対応する列に書き込みます。
このオプションを使用する場合は、以下の追加要件を確認してください。
トピック スキーマ内のフィールドと BigQuery スキーマ内のフィールドは、同じ名前でなければならず、その型には相互に互換性が必要です。
トピック スキーマのオプション フィールドは BigQuery スキーマでも省略可能な必要があります。
トピック スキーマの必須フィールドは、BigQuery スキーマでは必要ありません。
BigQuery フィールドがトピック スキーマに存在しない場合、これらの BigQuery フィールドは
NULLABLE
モードにする必要があります。トピック スキーマに、BigQuery スキーマに存在しない追加のフィールドがあり、このようなフィールドを削除できる場合は、[不明な項目を削除する] オプションを選択します。
サブスクリプション プロパティとして [トピック スキーマを使用する] または [テーブル スキーマを使用する] のいずれか 1 つのみを選択できます。
[トピック スキーマを使用する] または [テーブル スキーマを使用する] オプションを選択しない場合は、BigQuery テーブルに、BYTES
、STRING
、または JSON
型の data
という列があることを確認してください。Pub/Sub は、この BigQuery 列にメッセージを書き込みます。
Pub/Sub トピック スキーマまたは BigQuery テーブル スキーマの変更は、BigQuery テーブルに書き込まれたメッセージにすぐに反映されない場合があります。たとえば、[不明なフィールドを削除する] オプションが有効で、フィールドが Pub/Sub スキーマには存在するが BigQuery スキーマにはない場合、BigQuery テーブルに書き込まれるメッセージには、BigQuery スキーマに追加した後も、フィールドが含まれていない場合があります。最終的に、スキーマが同期され、後続のメッセージにこのフィールドが含まれます。
BigQuery サブスクリプションで [テーブル スキーマを使用する] オプションを使用すると、BigQuery 変更データ キャプチャ(CDC)も利用できます。CDC は、既存の行を処理して変更を適用し、BigQuery テーブルを更新します。
この機能の詳細については、変更データ キャプチャを使用してテーブル更新をストリーミングするをご覧ください。
BigQuery サブスクリプションでこの機能を使用する方法については、BigQuery の変更データ キャプチャをご覧ください。
テーブル スキーマを使用する
このオプションにより、Pub/Sub は BigQuery テーブルのスキーマを使用して、JSON メッセージのフィールドを対応する列に書き込むことができます。このオプションを使用する場合は、次の追加要件を確認してください。
BigQuery テーブルの各列の名前には、英字(a ~ z、A ~ Z)、数字(0 ~ 9)、アンダースコア(_)のみを使用できます。
公開されるメッセージは JSON 形式である必要があります。
次の JSON 変換がサポートされています。
JSON 型 BigQuery のデータ型 string
NUMERIC
、BIGNUMERIC
、DATE
、TIME
、DATETIME
、またはTIMESTAMP
number
NUMERIC
、BIGNUMERIC
、DATE
、TIME
、DATETIME
、またはTIMESTAMP
number
からDATE
、DATETIME
、TIME
、TIMESTAMP
への変換を使用する場合は、数値がサポートされている表現に準拠している必要があります。number
からNUMERIC
またはBIGNUMERIC
へのコンバージョンを使用する場合、値の適合率と範囲は、浮動小数点演算の IEEE 754 標準で許容されるものに制限されます。高い適合率やより広い範囲の値が必要な場合は、代わりにstring
からNUMERIC
またはBIGNUMERIC
へのコンバージョンを使用します。string
からNUMERIC
またはBIGNUMERIC
へのコンバージョンを使用する場合、Pub/Sub は文字列が人間が判読できる数値("123.124"
など)であると想定します。文字列を人間が判読できる数値として処理できない場合、Pub/Sub は文字列を BigDecimalByteStringEncoder でエンコードされたバイトとして扱います。
サブスクリプションのトピックにスキーマが関連付けられている場合は、メッセージ エンコード プロパティを
JSON
に設定する必要があります。メッセージに存在しない BigQuery フィールドがある場合、これらの BigQuery フィールドは
NULLABLE
モードにする必要があります。BigQuery スキーマに存在しない追加のフィールドがメッセージにあり、このようなフィールドを削除できる場合は、[不明なフィールドを削除する] オプションを選択します。
サブスクリプション プロパティとして [トピック スキーマを使用する] または [テーブル スキーマを使用する] のいずれか 1 つのみを選択できます。
[トピック スキーマを使用する] または [テーブル スキーマを使用する] オプションを選択しない場合は、BigQuery テーブルに、BYTES
、STRING
、または JSON
型の data
という列があることを確認してください。Pub/Sub は、この BigQuery 列にメッセージを書き込みます。
BigQuery テーブル スキーマの変更は、BigQuery テーブルに書き込まれたメッセージにすぐに反映されない場合があります。 たとえば、[不明なフィールドを削除する] オプションが有効で、フィールドがメッセージには存在するが BigQuery スキーマにはない場合、BigQuery テーブルに書き込まれるメッセージには、BigQuery スキーマに追加した後も、フィールドが含まれていない場合があります。最終的に、スキーマが同期され、後続のメッセージにこのフィールドが含まれます。
BigQuery サブスクリプションで [テーブル スキーマを使用する] オプションを使用すると、BigQuery 変更データ キャプチャ(CDC)も利用できます。 CDC は、既存の行を処理して変更を適用し、BigQuery テーブルを更新します。
この機能の詳細については、変更データ キャプチャを使用してテーブル更新をストリーミングするをご覧ください。
BigQuery サブスクリプションでこの機能を使用する方法については、BigQuery 変更データ キャプチャをご覧ください。
不明な項目を削除する
このオプションは、[トピック スキーマを使用する] または [テーブル スキーマを使用する] オプションで使用します。このオプションを有効にすると、Pub/Sub は、トピック スキーマやメッセージには存在するが BigQuery スキーマには存在しないフィールドをドロップできます。BigQuery スキーマに含まれないフィールドは、BigQuery テーブルにメッセージを書き込むときに破棄されます。
[不明な項目を削除する] が設定されていない場合、余分な項目を含むメッセージは BigQuery に書き込まれず、デッドレター トピックを構成しない限り、サブスクリプション バックログに残ります。
[不明な項目を削除する] の設定は、Pub/Sub トピック スキーマまたは BigQuery テーブル スキーマのいずれにも定義されていないフィールドには影響しません。この場合、有効な Pub/Sub メッセージがサブスクリプションに配信されます。ただし、BigQuery にはこれらの追加フィールドの列が定義されていないため、これらのフィールドは BigQuery の書き込みプロセス中に破棄されます。この動作を回避するには、Pub/Sub メッセージに含まれるフィールドが BigQuery テーブル スキーマにも含まれていることを確認します。
追加フィールドに関する動作は、使用される特定のスキーマタイプ(Avro、プロトコル バッファ)とエンコード(JSON、バイナリ)によっても異なります。これらの要因が余分なフィールドの処理にどのように影響するかについては、特定のスキーマ型とエンコードのドキュメントをご覧ください。
メタデータを書き込む
このオプションを使用すると、Pub/Sub が各メッセージのメタデータを BigQuery テーブルの追加の列に書き込むようにする場合は、このオプションを選択できます。それ以外の場合、メタデータは BigQuery テーブルに書き込まれません。
[メタデータを書き込む] オプションを選択する場合は、BigQuery テーブルに次の表に示すフィールドがあることを確認してください。
メタデータを書き込むオプションを選択しない場合、use_topic_schema
が true でない限り、宛先 BigQuery テーブルでは data
フィールドのみが必要になります。[メタデータを書き込む] と [トピック スキーマを使用する] の両方のオプションを選択した場合、トピックのスキーマには、次の名前にメタデータ パラメータと一致する名前のフィールドを含めないでください。この制限には、スネークケース パラメータのキャメルケース バージョンが含まれます。
パラメータ | |
---|---|
subscription_name |
STRING サブスクリプションの名前。 |
message_id |
STRING メッセージの ID |
publish_time |
TIMESTAMP メッセージのパブリッシュ時刻。 |
data |
BYTES、STRING、または JSON メッセージの本文。
|
attributes |
STRING または JSON すべてのメッセージ属性を含む JSON オブジェクト。また、存在する場合、順序指定キーなど、Pub/Sub メッセージの一部である追加のフィールドも含まれています。 |
BigQuery サブスクリプションの作成
次のサンプルでは、BigQuery 配信でサブスクリプションを作成する方法を示します。
Console
- Google Cloud コンソールで、[サブスクリプション] ページに移動します。
- [サブスクリプションを作成] をクリックします。
- [サブスクリプション ID] フィールドに名前を入力します。
サブスクリプションの指定方法については、トピックまたはサブスクリプションの指定方法のガイドラインをご覧ください。
- プルダウン メニューからトピックを選択するか、作成します。サブスクリプションがトピックからメッセージを受信します。
- [BigQuery への書き込み] として [配信タイプ] を選択します。
- BigQuery テーブルのプロジェクトを選択します。
- 既存のデータセットを選択するか、新規に作成します。
データセットの作成方法については、データセットの作成をご覧ください。
- 既存のテーブルを選択するか、新規に作成します。
テーブルの作成方法については、テーブルの作成をご覧ください。
- メッセージ エラーを処理するには、デッドレターを有効にすることを強くおすすめします。
詳細については、デッドレター トピックをご覧ください。
- [作成] をクリックします。
[トピック] ページからサブスクリプションを作成することもできます。 このショートカットは、トピックとサブスクリプションの関連付けに使用できます。
- Google Cloud コンソールで [トピック] ページに移動します。
- サブスクリプションを作成するトピックの横にある more_vert をクリックします。
- コンテキスト メニューから [サブスクリプションを作成] を選択します。
- [BigQuery への書き込み] として [配信タイプ] を選択します。
- BigQuery テーブルのプロジェクトを選択します。
- 既存のデータセットを選択するか、新規に作成します。
データセットの作成方法については、データセットの作成をご覧ください。
- 既存のテーブルを選択するか、新規に作成します。
データセットの作成方法については、テーブルの作成をご覧ください。
- メッセージ エラーを処理するには、デッドレターを有効にすることを強くおすすめします。
詳細については、デッドレター トピックをご覧ください。
- [作成] をクリックします。
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 subscriptions create
コマンドを使用します。gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --bigquery-table=PROJECT_ID:DATASET_ID.TABLE_ID
以下を置き換えます。
- SUBSCRIPTION_ID: サブスクリプションの ID を指定します。
- TOPIC_ID: トピックの ID を指定します。このトピックでは、スキーマが必要です。
- PROJECT_ID: プロジェクトの ID を指定します。
- DATASET_ID: 既存のデータセットの ID を指定します。データセットを作成するには、データセットの作成をご覧ください。
- TABLE_ID: 既存のテーブルの ID を指定します。 トピックにスキーマがない場合、このテーブルには data フィールドが必要です。テーブルを作成するには、スキーマ定義を含む空のテーブルを作成するをご覧ください。
C++
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある C++ 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub C++ API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
C#
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある C# 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub C# API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Go
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Go 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Go API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Java
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Java 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Java API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Node.js
Node.js
PHP
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub PHP API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Python
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Python 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Python API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
Ruby
このサンプルを試す前に、Pub/Sub クイックスタート: クライアント ライブラリの使用にある Ruby 向けの手順に従って設定を行ってください。 詳細については、Pub/Sub Ruby API のリファレンス ドキュメントをご覧ください。
Pub/Sub に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアント ライブラリの認証を設定するをご覧ください。
BigQuery サブスクリプションをモニタリングする
Cloud Monitoring には、サブスクリプションをモニタリングするための指標がいくつか用意されています。
Pub/Sub に関連する使用可能なすべての指標のリストとその説明については、Pub/Sub のモニタリング ドキュメントをご覧ください。
Pub/Sub 内からサブスクリプションをモニタリングすることもできます。
次のステップ
gcloud
コマンドを使用して、サブスクリプションを作成または変更する。- REST API を使用してサブスクリプションを作成または変更する。
- BigQuery サブスクリプションのトラブルシューティングを行う。