Notifiche Pub/Sub

Dopo aver completato un trasferimento di Storage Transfer Service, potresti voler iniziare un'altra attività, gestire un errore riscontrato durante un trasferimento o registrare il trasferimento che si è verificato. Pub/Sub fornisce una coda a cui i tuoi programmi si iscrivono per ricevere messaggi al termine del trasferimento. Ciò consente di riutilizzare il codice e di programmare i passaggi successivi in base allo stato del trasferimento.

Per ulteriori informazioni su Pub/Sub, consulta la sezione Che cos'è Cloud Pub/Sub

Prerequisiti

Prima di poter utilizzare questa funzionalità, procedi come segue:

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

    Abilita l'API

  2. Hai un argomento Pub/Sub esistente a cui vuoi inviare le 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 Storage Transfer Service TransferJobs per creare il messaggio NotificationConfig. L'argomento riceverà le notifiche nel canale Pub/Sub configurato.

Specifica quanto segue nel messaggio NotificationConfig:

  • L'argomento Pub/Sub a cui inviare notifiche
  • Il formato del messaggio, "JSON" o "NONE"

  • I tipi di eventi che ti interessano, corrispondenti a quelli completati 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: ID progetto Google Cloud del trasferimento
  • topic-id: nome dell'argomento Pub/Sub

Per ulteriori informazioni, consulta la specifica REST di Storage Transfer Service Pub Sub.

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 all'argomento Pub/Sub. Le notifiche contengono sempre il seguente insieme di coppie chiave-valore, indipendentemente dal payload di notifica:

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

Nome dell'attributo Esempio Descrizione
eventType TRANSFER_OPERATION_SUCCESS Stato della TransferOperation, da NotificationConfig.EventType
payloadFormat "JSON" Formato del messaggio, "JSON" o "NONE". Da 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 delle notifiche, devi specificare un tipo di payload da includere nelle notifiche attivate da tale configurazione. Puoi specificare i seguenti tipi di payload:

Tipo di payload Descrizione
NESSUNA Nessun payload incluso nella notifica.
JSON Il payload è formattato come una risposta JSON, in applicazione/json.

Esempi di configurazioni di notifica Pub/Sub

Notifica solo di trasferimenti non riusciti

Per ricevere messaggi solo per i trasferimenti non riusciti, invia un elemento TransferJob con un elemento NotificationConfig che filtra solo i 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: ID progetto Google Cloud del trasferimento
  • topic-id: nome dell'argomento Pub/Sub

Notifica per tutti i trasferimenti completati

Per inviare una notifica per tutti i trasferimenti completati, indipendentemente dallo stato, invia un elemento TransferJob con un filtro 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: ID progetto Google Cloud del trasferimento
  • topic-id: 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 Functions con un trigger Pub/Sub abbinata a una funzione cloud in background. Per ulteriori informazioni, consulta il tutorial su Cloud Pub/Sub.

Ecco alcuni esempi di azioni arbitrarie:

Garanzie di consegna

Storage Transfer Service invia notifiche per qualsiasi elemento TransferOperations avviato dopo aver aggiunto una configurazione delle notifiche e garantisce la consegna almeno una volta a Pub/Sub. Pub/Sub offre anche la consegna almeno una volta al destinatario, il che significa che puoi ricevere più messaggi, con più ID, che rappresentano lo stesso evento 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 a un argomento Pub/Sub, Storage Transfer Service potrebbe eliminarla dopo 7 giorni. Il mancato recapito 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.