Pub/Sub 通知

Storage Transfer Service の転送が完了した後、別のタスクの開始、転送中に発生したエラーの処理、または転送の発生をログに記録する必要が生じることがあります。Pub/Sub は、転送が完了したときにプログラムがメッセージを受信するために登録するキューを提供します。これにより、コードを再利用し、転送の状態に基づいて次のステップをプログラミングできます。

Pub/Sub の詳細については、Cloud Pub/Sub とはをご覧ください。

前提条件

この機能を使用する前に、次の操作を行います。

Pub/Sub 通知を受信するプロジェクトの Pub/Sub API を有効にします。

API を有効にする
通知の送信先とする既存の Pub/Sub トピックを用意します。
Storage Transfer Service バケットを含むプロジェクトに関連付けられているサービスアカウントのメールアドレスを取得します。
1. 目的の Pub/Sub トピックの IAM ロール roles.pubsub.publisher をサービスアカウントに付与します。
注: ロールを割り当てた後、その役割がサービスアカウントに適用されるまでには数秒かかることがあります。この権限をプログラムで付与する場合は、30 秒待ってから Storage Transfer Service を構成します。

通知設定の構成

Storage Transfer Service の Pub/Sub 通知設定を構成するには、Storage Transfer Service transferJobs API を使用して NotificationConfig メッセージを作成します。トピックは、構成された Pub/Sub チャネルで通知を受け取ります。

NotificationConfig メッセージで次の指定を行います。

通知を送信する先の Pub/Sub トピック
メッセージの形式（"JSON" または "NONE"）
完了した TransferOperation.Statuses に対応する、目的のイベントタイプ
- "TRANSFER_OPERATION_SUCCESS"
- "TRANSFER_OPERATION_FAILED"
- "TRANSFER_OPERATION_ABORTED"

NotificationConfig メッセージの例を次に示します。

{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_SUCCESS"],
     "payloadFormat": "JSON"
   },
   ...
}

以下を置き換えます。

project-id: 転送の Google Cloud プロジェクト ID
topic-id: Pub/Sub トピック名

詳細については、Storage Transfer Service の Pub Sub REST の仕様をご覧ください。

通知形式

Pub/Sub トピックに送信される通知は、次の 2 つの部分で構成されます。

属性: イベントを記述する Key-Value ペアのセット
ペイロード: 変更されたオブジェクトのメタデータを含む文字列

属性

属性とは、Storage Transfer Service から Pub/Sub トピックに送信されるすべての通知に含まれる Key-Value ペアのことです。ペイロードに関係なく、通知には次のキー値ペアが含まれます。

Pub/Sub メッセージ形式の詳細については、PubsubMessage をご覧ください。

属性名	例	説明
`eventType`	`TRANSFER_OPERATION_SUCCESS`	`TransferOperation` のステータス、`NotificationConfig.EventType` から。
`payloadFormat`	`"JSON"`	メッセージの形式（`"JSON"` または `"NONE"`）。`NotificationConfig.PayloadFormat` から。
`projectId`	`project-3`	転送ホストプロジェクトの ID。
`transferJobName`	`transferJobs/123`	転送ジョブの名前。
`transferOperationName`	`transferOperations/456`	転送オペレーションの名前。

ペイロード

ペイロードには TransferOperation メタデータが含まれます。通知構成を作成するときに、トリガーされた通知に入れるペイロードの種類を指定します。次の種類のペイロードを指定できます。

ペイロードの種類	説明
なし	通知にペイロードを追加しません。
JSON	ペイロードの形式は application/json の JSON レスポンスです。

Pub/Sub 通知構成の例

失敗した転送のみを通知する

転送に失敗した場合にのみメッセージを受信するには、失敗した転送のみをフィルタリングする NotificationConfig を指定して TransferJob を送信します。

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "eventTypes": ["TRANSFER_OPERATION_FAILED"],
     "payloadFormat: "JSON"
   },
   ...
}

以下を置き換えます。

project-id: 転送の Google Cloud プロジェクト ID
topic-id: Pub/Sub トピック名

完了した転送をすべて通知する

完了したすべての転送について、ステータスに関係なく通知するには、EventType フィルタを指定せず NotificationConfig を指定して TransferJob を送信します。

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "notificationConfig": {
     "pubsubTopic": "projects/project-id/topics/topic-id",
     "payloadFormat: "JSON"
   },
   ...
}

以下を置き換えます。

project-id: 転送の Google Cloud プロジェクト ID
topic-id: Pub/Sub トピック名

転送で任意のアクションを実施する

任意のアクションを実施するには、バックグラウンド関数と組み合わせた Pub/Sub トリガーのある Cloud Functions の関数を使用して、Pub/Sub 通知を作成します。詳細については、Cloud Pub/Sub チュートリアルをご覧ください。

任意のアクションの例は次のとおりです。

配信の保証

Storage Transfer Service は、通知構成を追加した後に開始された TransferOperations に関する通知を送信し、Pub/Sub に少なくとも 1 回は配信を行います。Pub/Sub も、受信者に少なくとも 1 回は配信します。つまり、同じ Storage Transfer Service イベントを表す複数の ID で、複数のメッセージを受信できます。

通知の公開順序は、Pub/Sub で受信する順序と必ずしも一致しません。

Pub/Sub トピックに一貫して通知を配信できない場合、Storage Transfer Service は 7 日後に通知を削除することがあります。Pub/Sub トピックが存在しない場合、Storage Transfer Service がトピックに公開する権限を持たない場合、またはトピックを所有するプロジェクトが公開割り当てを超えた場合、配信の失敗が発生します。