Pub/Sub-Benachrichtigungen

Sie können nach Abschluss einer Übertragung mit Storage Transfer Service eine weitere Aufgabe starten, einen während der Übertragung aufgetretenen Fehler behandeln oder eine Übertragung protokollieren. Pub/Sub stellt eine Warteschlange bereit, die von Ihren Programmen abonniert wird, um Nachrichten zu empfangen, wenn eine Übertragung abgeschlossen ist. Auf diese Weise können Sie Code wiederverwenden und nachfolgende Schritte basierend auf dem Status einer Übertragung programmieren.

Weitere Informationen zu Pub/Sub finden Sie unter Was ist Cloud Pub/Sub?.

Vorbereitung

Bevor Sie dieses Feature verwenden können, müssen Sie Folgendes tun:

Aktivieren Sie die Pub/Sub API für das Projekt, das Pub/Sub-Benachrichtigungen erhält.

API aktivieren
Achten Sie darauf, dass ein Cloud Pub/Sub-Thema vorhanden ist, an das Sie Benachrichtigungen senden möchten.
Rufen Sie die E-Mail-Adresse des Dienstkontos ab, das dem Projekt zugeordnet ist, das Ihren Storage Transfer Service-Bucket enthält.
1. Weisen Sie dem Dienstkonto die IAM-Rolle roles.pubsub.publisher für das gewünschte Pub/Sub-Thema zu.
Hinweis: Zwischen dem Zuweisen der Rolle und ihrer Anwendung auf das Dienstkonto können einige Sekunden vergehen. Wenn Sie diese Berechtigung programmatisch gewähren, warten Sie 30 Sekunden, bevor Sie Storage Transfer Service konfigurieren.

Benachrichtigungseinstellungen konfigurieren

Zum Konfigurieren von Pub/Sub-Benachrichtigungseinstellungen von Storage Transfer Service verwenden Sie die transferJobs API von Storage Transfer Service, um die NotificationConfig-Nachricht zu erstellen. Das Thema erhält Benachrichtigungen auf dem konfigurierten Pub/Sub-Kanal.

Geben Sie in Ihrer NotificationConfig-Nachricht Folgendes an:

Pub/Sub-Thema, an das Benachrichtigungen gesendet werden sollen
Das Format der Nachricht, "JSON" oder "NONE"
Die gewünschten Ereignistypen, die abgeschlossenen TransferOperation.Statuses entsprechen:
- "TRANSFER_OPERATION_SUCCESS"
- "TRANSFER_OPERATION_FAILED"
- "TRANSFER_OPERATION_ABORTED"

Hier sehen Sie eine NotificationConfig-Beispielnachricht:

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

Ersetzen Sie Folgendes:

project-id: die Google Cloud-Projekt-ID der Übertragung
topic-id: der Name des Pub/Sub-Themas

Weitere Informationen finden Sie unter Pub/Sub-REST-Spezifikation von Storage Transfer Service.

Benachrichtigungsformat

Benachrichtigungen, die an ein Pub/Sub-Thema gesendet werden, bestehen aus zwei Teilen:

Attribute: Eine Reihe von Schlüssel/Wert-Paaren, die das Ereignis beschreiben
Nutzlast: Ein String, der die Metadaten des geänderten Objekts enthält

Attribute

Attribute sind Schlüssel/Wert-Paare, die in allen Benachrichtigungen enthalten sind, die von Storage Transfer Service an Ihr Pub/Sub-Thema gesendet werden. Benachrichtigungen enthalten immer die folgenden Schlüssel/Wert-Paare, unabhängig von der Nutzlast der Benachrichtigung:

Weitere Informationen zum Pub/Sub-Nachrichtenformat finden Sie unter PubsubMessage.

Attributname	Beispiel	Beschreibung
`eventType`	`TRANSFER_OPERATION_SUCCESS`	Status von `TransferOperation`, aus `NotificationConfig.EventType`
`payloadFormat`	`"JSON"`	Format der Nachricht, entweder `"JSON"` oder `"NONE"`. Aus `NotificationConfig.PayloadFormat`
`projectId`	`project-3`	ID des Übertragungshost-Projekts
`transferJobName`	`transferJobs/123`	Name des Übertragungsjobs
`transferOperationName`	`transferOperations/456`	Name des Übertragungsvorgangs

Nutzlast

Die Nutzlast enthält die Metadaten von TransferOperation. Beim Erstellen einer Benachrichtigungskonfiguration geben Sie einen Nutzlasttyp an, der in Benachrichtigungen enthalten sein soll, die durch diese Konfiguration ausgelöst werden. Die folgenden Nutzlasttypen stehen zur Wahl:

Nutzlasttyp	Beschreibung
NONE	Die Benachrichtigung enthält keine Nutzlast.
JSON	Die Nutzlast ist als JSON-Antwort in application/json formatiert.

Beispielkonfigurationen für Pub/Sub-Benachrichtigungen

Benachrichtigung nur bei fehlgeschlagenen Übertragungen

Wenn Sie nur Nachrichten für fehlgeschlagene Übertragungen erhalten möchten, senden Sie einen TransferJob mit einer NotificationConfig, die nur nach fehlgeschlagenen Übertragungen filtert:

// 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"
   },
   ...
}

Ersetzen Sie Folgendes:

project-id: die Google Cloud-Projekt-ID der Übertragung
topic-id: der Name des Pub/Sub-Themas

Benachrichtigungen bei allen abgeschlossenen Übertragungen

Wenn Sie unabhängig vom Status über alle abgeschlossenen Übertragungen benachrichtigt werden möchten, senden Sie einen TransferJob mit einer NotificationConfig ohne EventType-Filter:

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

Ersetzen Sie Folgendes:

project-id: die Google Cloud-Projekt-ID der Übertragung
topic-id: der Name des Pub/Sub-Themas

Beliebige Aktionen für eine Übertragung ausführen

Für eine beliebige Aktion erstellen Sie eine Pub/Sub-Benachrichtigung mithilfe einer Cloud-Funktion mit einem Pub/Sub-Trigger, der mit einer Hintergrund-Cloud-Funktion gekoppelt ist. Weitere Informationen finden Sie in der Cloud Pub/Sub-Anleitung.

Beispiele für Aktionen:

Übermittlungsgarantien

Storage Transfer Service sendet Benachrichtigungen für alle TransferOperations, die nach dem Hinzufügen einer Benachrichtigungskonfiguration gestartet wurden, und garantiert eine mindestens einmalige Übermittlung an Pub/Sub. Auch Pub/Sub bietet eine mindestens einmalige Übermittlung an den Empfänger. Dies bedeutet, dass Sie mehrere Nachrichten mit unterschiedlichen IDs zum selben Storage Transfer Service-Ereignis erhalten können.

Es wird nicht garantiert, dass Benachrichtigungen in der Reihenfolge veröffentlicht werden, in der Pub/Sub sie empfängt.

Wenn eine Benachrichtigung dauerhaft nicht an ein Pub/Sub-Thema übermittelt werden kann, löscht Storage Transfer Service die Benachrichtigung möglicherweise nach sieben Tagen. Ein Übermittlungsfehler kann auftreten, wenn das Pub/Sub-Thema nicht mehr vorhanden ist, Storage Transfer Service nicht mehr über die Berechtigung zum Veröffentlichen im Thema verfügt oder das Projekt, zu dem das Thema gehört, das Veröffentlichungskontingent überschreitet.