Storage Transfer Service の転送が完了した後、別のタスクの開始、転送中に発生したエラーの処理、または転送の発生をログに記録する必要が生じることがあります。Pub/Sub は、転送が完了したときにプログラムがメッセージを受信するために登録するキューを提供します。これにより、コードを再利用し、転送の状態に基づいて次のステップをプログラミングできます。
Pub/Sub の詳細については、Cloud Pub/Sub とはをご覧ください。
前提条件
この機能を使用する前に、次の操作を行います。
Pub/Sub 通知を受信するプロジェクトの Pub/Sub API を有効にします。
通知の送信先とする既存の Pub/Sub トピックを用意します。
Storage Transfer Service バケットを含むプロジェクトに関連付けられているサービス アカウントのメールアドレスを取得します。
- 目的の Pub/Sub トピックの IAM ロール
roles.pubsub.publisher
をサービス アカウントに付与します。
- 目的の Pub/Sub トピックの IAM ロール
通知設定の構成
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 プロジェクト IDtopic-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 プロジェクト IDtopic-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 プロジェクト IDtopic-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 がトピックに公開する権限を持たない場合、またはトピックを所有するプロジェクトが公開割り当てを超えた場合、配信の失敗が発生します。