Pub/Sub 通知と BigQuery を使用してジョブのステータスをモニタリングする

このドキュメントでは、Pub/Sub 通知を設定してジョブとタスクの状態の変化をモニタリングする方法について説明します。通知はさまざまなユースケースに使用できます。たとえば、このドキュメントでは、通知をデータ分析に使用できる BigQuery テーブルにストリーミングする方法について説明します。Pub/Sub 通知のユースケースの詳細については、Pub/Sub ドキュメントのサブスクリプションタイプを選択するをご覧ください。

始める前に

Batch を以前に使用したことがない場合は、Batch を使ってみるを確認し、プロジェクトとユーザーの前提条件を完了して Batch を有効にします。
バッチジョブに Pub/Sub 通知を設定するには、次の操作を行います。
1. Enable the Pub/Sub API.
  Enable the API
2. Pub/Sub のトピックとサブスクリプションを構成するために必要な権限を取得するには、プロジェクトに対する Pub/Sub 編集者（roles/pubsub.editor）IAM ロールの付与を管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。
  
  必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。
その他の要件は、構成するサブスクリプションの種類によって異なります。たとえば、BigQuery テーブルに通知をストリーミングして分析する場合は、次の操作を行う必要があります。
1. Enable the BigQuery API.
  Enable the API
2. Pub/Sub 通知を BigQuery にストリーミングするために必要な権限を Pub/Sub サービスアカウントに付与するには、Pub/Sub サービスアカウントに Pub/Sub トピックのプロジェクトに対する BigQuery データ編集者（roles/bigquery.dataEditor）IAM ロールを付与するように管理者に依頼します。
  
  このロールの割り当てについて詳しくは、Pub/Sub サービスアカウントに BigQuery のロールを割り当てるをご覧ください。
3. BigQuery で通知を分析するユーザーに、必要な権限があることを確認します。
  BigQuery で Pub/Sub 通知に対してクエリを実行するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。
  - BigQuery テーブルのプロジェクトに対する BigQuery ジョブユーザー（roles/bigquery.jobUser）
  - BigQuery テーブルに対する BigQuery データ閲覧者（roles/bigquery.dataViewer）

Batch の Pub/Sub 通知を設定する

Batch は、ジョブとタスクの状態の変更に関する Pub/Sub 通知をサポートしています。これらの通知は、アラート、オブザーバビリティ、分析に使用できます。

1 つ以上のバッチジョブに Pub/Sub 通知を設定するには、次のセクションで説明する手順を行います。

Batch ジョブの Pub/Sub トピックを作成または識別します。
トピックの通知を受信して使用するためのサブスクリプションを少なくとも 1 つ作成します。
トピックに通知を送信するようにジョブを構成します。

Batch の Pub/Sub 通知を設定したら、必要に応じて、特定の通知を送信するように各ジョブを構成できます。ジョブまたはタスクの状態が変化するたびに通知を受け取ることができます。また、特定のジョブまたはタスクの状態に合わせて通知をフィルタリングすることもできます。特に、Pub/Sub では、ジョブまたはタスクが最初に入った状態に関する通知を送信しません。Pub/Sub は、ジョブがある状態から別の状態に移行した場合にのみ通知を送信します。Pub/Sub 通知用に構成できる属性の詳細については、Pub/Sub ステータス通知を送信するジョブを作成して実行するをご覧ください。

Batch 用の Pub/Sub トピックを作成または識別する

バッチ通知に使用する新しい Pub/Sub トピックを作成するか、既存の Pub/Sub トピックを特定します。

このドキュメントの後半で説明するように、管理者が許可する追加の権限を付与するまで、ジョブはこの Pub/Sub トピックに通知を送信できません。

通知を受信して使用するサブスクリプションを作成する

Pub/Sub トピックに公開されたメッセージを受信して使用するには、そのトピックへのサブスクリプションを少なくとも 1 つ作成する必要があります。

たとえば、BigQuery に通知をストリーミングするようにトピックを構成します。その後、通知を公開するジョブを実行するときに、BigQuery テーブルで通知を受信して分析できます。詳細については、このドキュメントの例: BigQuery で Pub/Sub 通知を受信して使用するをご覧ください。

それ以外の場合は、サブスクリプションとその他のサブスクリプションオプションの詳細については、Pub/Sub ドキュメントのサブスクリプションの概要をご覧ください。

トピックに通知を送信するジョブを構成する

Pub/Sub 通知をトピックに送信するジョブを構成するには、Pub/Sub ステータス通知を送信するジョブを作成して実行するの手順に従ってください。具体的には、次の情報を入力してください。

まだ行っていない場合は、Pub/Sub トピックに通知を送信するジョブに対して必要なすべての権限を付与するよう管理者に依頼してください。これらの権限は、ページの必要なロールのセクションに記載されています。
ジョブの notifications フィールドを定義して、Pub/Sub 通知を有効にするジョブを作成し、実行します。

例: BigQuery で Pub/Sub 通知を受信して使用する

以降のセクションでは、BigQuery で Pub/Sub 通知を受信して使用するユースケースの例について説明します。トピックの Pub/Sub 通知を BigQuery テーブルにストリーミングするサブスクリプションを構成することで、ジョブとタスクの状態の変化の履歴を保持し、それらの変化をクエリできます。

BigQuery に通知をストリーミングするサブスクリプションを構成する

次の手順で、トピックから BigQuery テーブルに通知をストリーミングする Pub/Sub サブスクリプションを構成します。

まだ行っていない場合は、Batch 用の Pub/Sub トピックを作成または識別します。
まだ作成していない場合は、BigQuery データセットを作成します。

次のスキーマ定義を使用して BigQuery テーブルを作成します。

[
  {
    "name": "data",
    "type": "STRING"
  },
  {
    "name": "subscription_name",
    "type": "STRING"
  },
  {
    "name": "message_id",
    "type": "STRING"
  },
  {
    "name": "attributes",
    "type": "JSON"
  },
  {
    "name": "publish_time",
    "type": "TIMESTAMP",
    "mode": "NULLABLE"
  }
]

BigQuery にストリーミングする Pub/Sub サブスクリプションを作成し、次のオプションを指定します。
- トピック: Batch の Pub/Sub トピックを選択します。
- プロジェクト: BigQuery テーブルを含むプロジェクトを選択します。
- データセット: BigQuery テーブルを含むデータセットを選択します。
- テーブル: 前の手順で作成したテーブルを選択します。
- [トピックスキーマを使用する] を選択します。
- [メタデータを書き込む] を選択します。

これで、Pub/Sub 通知がそのトピックに送信されるたびに、Pub/Sub はその通知を BigQuery テーブルにストリーミングします。Pub/Sub 通知を送信するようにジョブを構成したら、BigQuery で通知を分析できます。

BigQuery で通知を分析する

トピックに対して BigQuery テーブルへのサブスクリプションを構成し、トピックに通知を送信するジョブを実行すると、BigQuery で通知を分析できます。BigQuery で通知を分析するには、BigQuery テーブルの attributes 列でクエリを実行します。クエリできる属性は、タスクとジョブのどちらの通知を構成したかによって異なります。

タスクの通知の次の属性をクエリできます。

JobUID
NewTaskState
Region
TaskName
TaskUID
Type

ジョブの通知の次の属性をクエリできます。

JobUID
JobName
NewJobState
Region
Type

たとえば、次のクエリは、各通知に関連付けられた JobUID を表示します。

select attributes.JobUID from `example-table`

次のステップ

Pub/Sub ステータス通知を送信するジョブを作成して実行する方法を学習する。
Pub/Sub サブスクリプションの詳細を確認する。
BigQuery 分析の詳細を確認する。