Pub/Sub für Übertragungen

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

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

Vorbereitung

Bevor Sie diese Funktion verwenden können, müssen Sie Folgendes tun:

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

    API aktivieren

  2. Achten Sie darauf, dass ein bestehendes Cloud Pub/Sub-Thema vorhanden ist, an das Sie Benachrichtigungen senden möchten.

  3. 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.

Benachrichtigungseinstellungen konfigurieren

Zum Konfigurieren von Pub/Sub-Benachrichtigungseinstellungen des Storage Transfer Service verwenden Sie die Storage Transfer Service transferJobs API, 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 dem 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 dabei Folgendes:

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

Weitere Informationen finden Sie unter Pub/Sub-REST-Spezifikation des 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 vom 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". Von 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 einem NotificationConfig, das 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 dabei Folgendes:

  • project-id: Die Google Cloud-Projekt-ID der Übertragung
  • topic-id: 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 einem 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 dabei Folgendes:

  • project-id: Die Google Cloud-Projekt-ID der Übertragung
  • topic-id: 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 Cloud-Funktion "Hintergrund" gekoppelt ist. Weitere Informationen finden Sie in der Cloud Pub/Sub-Anleitung.

Beispiele für beliebige Aktionen:

Übermittlungsgarantien

Der 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. Pub/Sub bietet dem Empfänger mindestens eine Zustellung. Dies bedeutet, dass Sie mehrere Nachrichten mit mehreren IDs erhalten können, die dasselbe Storage Transfer Service-Ereignis darstellen.

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 der Storage Transfer Service die Benachrichtigung möglicherweise nach sieben Tagen. Ein Übermittlungsfehler kann auftreten, wenn das Pub/Sub-Thema nicht mehr vorhanden ist, der Storage Transfer Service nicht mehr über die Berechtigung zum Veröffentlichen des Themas verfügt oder wenn das Projekt, zu dem das Thema gehört, das Veröffentlichungskontingent überschritten hat.