Notifiche Pub/Sub

Dopo aver completato un trasferimento di Storage Transfer Service, potresti voler avviare un'altra attività, gestire un errore rilevato durante un trasferimento o registrare un trasferimento. Pub/Sub fornisce una coda a cui i tuoi programmi si abbonano per ricevere i 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 ulteriori informazioni su Pub/Sub, consulta Che cos'è Cloud Pub/Sub

Prerequisiti

Prima di poter utilizzare questa funzionalità, svolgi i seguenti passaggi:

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

    Attiva l'API

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

  3. Ottieni l'indirizzo email dell'account di servizio associato al progetto che contiene il bucket Storage Transfer Service.

    1. Concedi all'account 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 un 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 evento desiderati, corrispondenti ai TransferOperation.Statuses:

    • "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 ulteriori informazioni, consulta la specifica REST di Pub/Sub di Storage Transfer Service.

Formato delle notifiche

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

  • Attributi: un set di coppie chiave:valore che descrivono l'evento.
  • Payload: una stringa contenente i metadati dell'oggetto modificato.

Attributi

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

Per ulteriori informazioni sul formato dei messaggi Pub/Sub, consulta PubsubMessage.

Nome attributo Esempio Descrizione
eventType TRANSFER_OPERATION_SUCCESS Stato del TransferOperation, da NotificationConfig.EventType
payloadFormat "JSON" Formato del messaggio: "JSON" o "NONE". Da NotificationConfig.PayloadFormat.
projectId project-3 ID del progetto host del 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 di payload Descrizione
NONE La notifica non include alcun payload.
JSON Il payload viene formattato come risposta JSON in application/json.

Configurazioni di notifiche Pub/Sub di esempio

Notifiche solo per i trasferimenti non riusciti

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

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

Sostituisci quanto segue:

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

Invia notifica per tutti i trasferimenti completati

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

// REST JSON format:
//   https://cloud.google.com/storage-transfer/docs/create-manage-transfer-program
{
   ...
   "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

Eseguire azioni arbitrarie su un trasferimento

Per eseguire un'azione arbitraria, crea una notifica Pub/Sub utilizzando una funzione Cloud con un attivatore Pub/Sub abbinata a una funzione Cloud in background. Per ulteriori informazioni, consulta Tutorial su Cloud Pub/Sub.

Esempi di azioni arbitrarie includono:

Garanzie di consegna

Storage Transfer Service invia notifiche per qualsiasi TransferOperations avviato dopo aver aggiunto una configurazione di notifica e garantisce l'invio almeno una volta a Pub/Sub. Pub/Sub offre inoltre la consegna "almeno una volta" 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 vengono ricevute da Pub/Sub.

Se una notifica non può essere recapitata costantemente a un Pub/Sub Storage Transfer Service potrebbe eliminare la notifica dopo 7 giorni. Consegna a domicilio l'errore può verificarsi quando l'argomento Pub/Sub non esiste più, Storage Transfer Service non ha più l'autorizzazione per pubblicare nell'argomento oppure quando il progetto proprietario dell'argomento supera la quota di pubblicazione.