Notifiche Pub/Sub

Dopo aver completato un trasferimento di Storage Transfer Service, potresti voler avviare un'altra attività, gestire un errore riscontrato durante un trasferimento o registrare l'avvenuto trasferimento. Pub/Sub fornisce una coda a cui i tuoi programmi si iscrivono per ricevere messaggi al termine di un trasferimento. In questo modo, puoi riutilizzare il codice e programmare i passaggi successivi in base allo stato di un trasferimento.

Per saperne di più su Pub/Sub, consulta Che cos'è Cloud Pub/Sub

Prerequisiti

Prima di poter utilizzare questa funzionalità, segui questi passaggi:

  1. Abilita l'API Pub/Sub per il progetto che riceve le notifiche Pub/Sub.

    Abilita l'API

  2. Avere un argomento Pub/Sub esistente a cui vuoi inviare notifiche.

  3. Recupera l'indirizzo email dell'agente di servizio Storage Transfer Service per il progetto in cui crei il job di trasferimento.

    1. Concedi all'agente di servizio il ruolo IAM roles/pubsub.publisher per l'argomento Pub/Sub desiderato.

Configurazione delle impostazioni di notifica

Per configurare le impostazioni di notifica Pub/Sub di Storage Transfer Service, utilizza l'API transferJobs di Storage Transfer Service per creare il messaggio NotificationConfig. L'argomento riceverà notifiche sul canale Pub/Sub configurato.

Specifica quanto segue nel messaggio NotificationConfig:

  • L'argomento Pub/Sub a cui inviare le notifiche
  • Il formato del messaggio, "JSON" o "NONE"
  • I tipi di eventi desiderati, corrispondenti ai valori TransferOperation.Statuses completati:

    • "TRANSFER_OPERATION_SUCCESS"
    • "TRANSFER_OPERATION_FAILED"
    • "TRANSFER_OPERATION_ABORTED"

Di seguito è riportato un esempio di messaggio NotificationConfig:

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

Sostituisci quanto segue:

  • project-id: l'ID progetto Google Cloud del trasferimento
  • topic-id: il nome dell'argomento Pub/Sub

Per saperne di più, consulta la specifica REST Pub/Sub di Storage Transfer Service.

Formato delle notifiche

Le notifiche inviate all'argomento Pub/Sub sono costituite da due parti:

  • Attributi: un set di coppie chiave:valore che descrivono l'evento.
  • Payload: una stringa che contiene la risorsa TransferOperation, se il formato del payload è JSON.

Attributi

Gli attributi sono coppie chiave:valore contenute in tutte le notifiche inviate da Storage Transfer Service al tuo argomento Pub/Sub. Le notifiche contengono sempre il seguente insieme di coppie chiave:valore, indipendentemente dal payload della notifica:

Per saperne di più sul formato dei messaggi Pub/Sub, consulta PubsubMessage.

Nome attributo Esempio Descrizione
eventType TRANSFER_OPERATION_SUCCESS Stato di TransferOperation, da NotificationConfig.EventType
payloadFormat "JSON" Formato del messaggio, "JSON" o "NONE". Fonte: NotificationConfig.PayloadFormat.
projectId project-3 ID del progetto host di trasferimento.
transferJobName transferJobs/123 Nome del job di trasferimento.
transferOperationName transferOperations/456 Nome dell'operazione di trasferimento.

Payload

Il payload contiene i metadati TransferOperation. Quando crei una configurazione di notifica, specifichi un tipo di payload da includere nelle notifiche attivate da quella configurazione. Puoi specificare i seguenti tipi di payload:

Tipo payload Descrizione
NONE La notifica non include alcun payload.
JSON Il payload è formattato come risposta JSON, in application/json.

Esempi di configurazioni di notifica Pub/Sub

Notifica solo per i trasferimenti non riusciti

Per ricevere messaggi solo per i trasferimenti non riusciti, invia un TransferJob con un NotificationConfig che filtra solo i trasferimenti non riusciti:

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

Sostituisci quanto segue:

  • project-id: l'ID progetto Google Cloud del trasferimento
  • topic-id: il nome dell'argomento Pub/Sub

Invia una notifica per tutti i trasferimenti completati

Per ricevere una notifica per tutti i trasferimenti completati, indipendentemente dallo stato, invia un TransferJob con un NotificationConfig senza filtri EventType:

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

Sostituisci quanto segue:

  • project-id: l'ID progetto Google Cloud del trasferimento
  • topic-id: il nome dell'argomento Pub/Sub

Esecuzione di azioni arbitrarie su un trasferimento

Per eseguire un'azione arbitraria, crea una notifica Pub/Sub utilizzando una funzione Cloud Functions con un trigger Pub/Sub abbinata a una funzione Cloud Functions in background. Per saperne di più, consulta il tutorial su Cloud Pub/Sub.

Ecco alcuni esempi di azioni arbitrarie:

Garanzie di consegna

Storage Transfer Service invia notifiche per qualsiasi TransferOperations avviato dopo l'aggiunta di una configurazione di notifica e garantisce la distribuzione almeno una volta a Pub/Sub. Pub/Sub offre anche la consegna "at-least-once" al destinatario, il che significa che potresti ricevere più messaggi, con più ID, che rappresentano lo stesso evento di Storage Transfer Service.

Non è garantito che le notifiche vengano pubblicate nell'ordine in cui Pub/Sub le riceve.

Se una notifica non può essere recapitata in modo coerente a un argomento Pub/Sub, Storage Transfer Service potrebbe eliminarla dopo 7 giorni. L'errore di invio può verificarsi quando l'argomento Pub/Sub non esiste più, quando Storage Transfer Service non dispone più dell'autorizzazione per pubblicare nell'argomento o quando il progetto proprietario dell'argomento supera la quota di pubblicazione.