Proprietà di abbonamento

Le proprietà di sottoscrizione Pub/Sub sono le caratteristiche di una sottoscrizione. Puoi impostare le proprietà di sottoscrizione quando crei o aggiorni un abbonamento.

Questo documento descrive le diverse proprietà di abbonamento che puoi impostare per un abbonamento.

Prima di iniziare

• Scopri di più sugli abbonamenti.

• Comprendi il flusso di lavoro per l'abbonamento che stai per creare: Pull, Push o BigQuery.

Proprietà comuni degli abbonamenti

Quando crei un abbonamento, devi specificare una serie di opzioni per configurarlo. Alcune di queste proprietà sono comuni a tutti i tipi di abbonamento e sono descritte nelle sezioni successive.

Tempo di conservazione dei messaggi

L'opzione Durata conservazione messaggi specifica per quanto tempo Pub/Sub conserva i messaggi dopo la pubblicazione. Al termine della durata di conservazione del messaggio, Pub/Sub potrebbe eliminarlo indipendentemente dallo stato di conferma del messaggio. Per conservare i messaggi confermati per la durata di conservazione dei messaggi, vedi Riprodurre e ignorare i messaggi.

Di seguito sono riportati i valori per l'opzione Durata della conservazione dei messaggi:

• Valore predefinito = 7 giorni
• Valore minimo = 10 minuti
• Valore massimo = 31 giorni

I messaggi non confermati possono essere causati da abbonamenti inattivi, esigenze di backup o elaborazione lenta. Se riesci a elaborare i messaggi entro 24 ore, gli addebiti aggiuntivi non vengono applicati. Per evitare nuovi addebiti, gestisci questi scenari come segue:

• Abbonamenti inattivi. Elimina gli abbonamenti inattivi per evitare di incorrere in costi di conservazione dei messaggi degli abbonamenti.

• Spazio di archiviazione dei backup. Se utilizzi la conservazione delle sottoscrizioni come spazio di archiviazione di backup, puoi passare a un'altra opzione di archiviazione, ad esempio la conservazione dei messaggi degli argomenti o la conservazione dei messaggi confermati. La conservazione dei messaggi dell'argomento archivia i messaggi solo una volta a livello di argomento e rimangono disponibili per tutte le sottoscrizioni da utilizzare in caso di necessità.

• Ritardi nell'elaborazione. Aggiungi altri abbonati (se possibile) per elaborare i messaggi entro un giorno.

Conserva messaggi confermati

Se specifichi Tempo di conservazione dei messaggi, puoi anche specificare se conservare i messaggi confermati.

L'opzione Conserva i messaggi confermati ti consente di conservare i messaggi confermati per la durata di conservazione dei messaggi specificata. Questa opzione aumenta le tariffe di archiviazione dei messaggi. Per ulteriori informazioni, consulta Costi di archiviazione.

Periodo di scadenza

L'opzione Periodo di scadenza ti consente di estendere il periodo di scadenza del tuo abbonamento.

Gli abbonamenti senza attività dell'abbonato o modifiche apportate alle proprietà dell'abbonamento scadono. Se Pub/Sub rileva attività degli abbonati o se aggiorni una delle proprietà dell'abbonamento, il timer di eliminazione dell'abbonamento si riavvia. Esempi di attività degli abbonati includono connessioni aperte, pull attivi o push riusciti.

Se specifichi il periodo di scadenza, il valore deve essere maggiore della durata di conservazione dei messaggi specificata nell'opzione Durata di conservazione dei messaggi.

Di seguito sono riportati i valori per l'opzione Periodo di scadenza:

• Valore predefinito = 31 giorni
• Valore minimo = 1 giorno

Per evitare che un abbonamento scada, imposta il periodo di scadenza su never expire.

Scadenza per l'accettazione

L'opzione Scadenza conferma specifica la scadenza iniziale dopo la quale un messaggio senza conferma viene inviato di nuovo. Puoi estendere la scadenza per l'acknowledgement su base per messaggio inviando richieste ModifyAckDeadline successive.

Di seguito sono riportati i valori per l'opzione Scadenza per l'acknowledgment:

• Valore predefinito = 10 secondi
• Valore minimo = 10 secondi
• Valore massimo = 600 secondi

In alcuni casi, le librerie client Pub/Sub possono controllare la frequenza di recapito e modificare dinamicamente la scadenza per l'acknowledgment. In questo modo, il messaggio potrebbe essere recapitato di nuovo prima della scadenza per il conferma che hai impostato. Per eseguire l'override di questo comportamento, utilizza minDurationPerAckExtension e maxDurationPerAckExtension. Per ulteriori informazioni sull'utilizzo di questi valori, consulta Supporto della pubblicazione esattamente una volta nelle librerie client.

Filtro sottoscrizioni

Utilizza l'opzione Filtro iscrizioni per specificare una stringa con un'espressione di filtro. Se un'iscrizione ha un filtro, vengono inviati solo i messaggi che corrispondono al filtro. Il servizio Pub/Sub conferma automaticamente i messaggi che non corrispondono al filtro.

• Puoi filtrare i messaggi in base ai rispettivi attributi, ma non in base ai dati contenuti nel messaggio.

• Se non specificato, la sottoscrizione non filtra i messaggi e gli abbonati ricevono tutti i messaggi.

• I filtri non possono essere modificati o rimossi dopo l'applicazione.

Quando ricevi i messaggi da una sottoscrizione con un filtro, non ti vengono addebitati costi di traffico in uscita per i messaggi che Pub/Sub riconosce automaticamente. Per questi messaggi sono previsti costi di consegna dei messaggi e tariffe per l'archiviazione correlata alla ricerca.

Per ulteriori informazioni, vedi Filtrare i messaggi di un abbonamento.

Ordinamento messaggi

Quando in un abbonamento è attivato l'ordinamento dei messaggi, i client sottoscrittore ricevono i messaggi pubblicati nella stessa regione con la stessa chiave di ordinamento nell'ordine in cui sono stati ricevuti dal servizio.

Quando utilizzi l'invio ordinato, le conferme per i messaggi successivi non vengono elaborate finché non vengono elaborate quelle per i messaggi precedenti.

I publisher devono inviare i messaggi con una chiave di ordinamento in modo che Pub/Sub possa consegnarli in ordine.

Se non è impostata, Pub/Sub potrebbe non consegnare i messaggi in ordine, anche se hanno una chiave di ordinamento.

Argomento messaggi non recapitabili

Quando un messaggio non può essere consegnato dopo un determinato numero di tentativi di consegna o un abbonato non può confermare il messaggio, puoi configurare un argomento messaggi non recapitabili a cui questi messaggi possono essere ripubblicati.

Se imposti un argomento messaggi non recapitabili, puoi anche specificare il numero massimo di tentativi di consegna. Di seguito sono riportati i valori per il numero massimo di tentativi di consegna per l'argomento messaggi non recapitabili:

• Valore predefinito = 5 tentativi di invio
• Valore minimo = 5 tentativi di consegna
• Valore massimo = 100 tentativi di consegna

Se l'argomento messaggi non recapitabili si trova in un progetto diverso dall'abbonamento, devi anche specificare l'ID progetto con l'argomento dei argomento messaggi non recapitabili.

Per ulteriori informazioni, vedi Inoltro agli argomenti della posta inutilizzata.

Policy di ripetizione

Se la scadenza per la conferma scade o un abbonato risponde con una conferma negativa, Pub/Sub può inviare nuovamente il messaggio. Questo tentativo di invio viene chiamato Criterio di ripetizione dell'abbonamento.

Per impostazione predefinita, il criterio di ripetizione per un abbonamento è impostato su Riprova immediatamente. Con questa opzione, Pub/Sub invia nuovamente il messaggio quando scade la scadenza per il conferma o un sottoscrittore risponde con una conferma negativa.

Puoi anche impostare il valore su Esegui nuovo tentativo dopo ritardo backoff esponenziale. In questo caso, devi specificare i valori di backoff massimo e minimo.

Ecco alcune linee guida per impostare i valori di backoff minimo e massimo:

• Se imposti il valore massimo per la durata del backoff, il valore predefinito per la durata minima del backoff è 10 secondi.

• Se imposti il valore minimo per la durata del backoff, il valore predefinito per la durata massima del backoff è 600 secondi.

• La durata massima del backoff che puoi specificare è 600 secondi.

Norme di ripetizione e messaggi raggruppati

Se i messaggi sono in un batch, Pub/Sub avvia il backoff exponenciale quando si verifica una delle seguenti condizioni:

• L'abbonato invia un riconoscimento negativo per ogni messaggio nel batch.

• Scade la scadenza per la conferma.

Criterio di ripetizione e sottoscrizione push

Se ricevi messaggi da una sottoscrizione push, Pub/Sub potrebbe recapitare i messaggi dopo il tempo di attesa push anziché dopo la durata del tempo di attesa esponenziale. Quando il backoff push è più lungo della durata del backoff esponenziale, Pub/Sub riconsegna i messaggi non confermati dopo il backoff push.

Proprietà di sottoscrizione pull

Quando configuri un abbonamento pull, puoi specificare le seguenti proprietà.

Consegna "exactly-once"

Pubblicazione "exactly-once". Se impostato, Pub/Sub soddisfa le garanzie di consegna exactly-once. Se non specificato, l'abbonamento supporta la consegna almeno una volta per ogni messaggio.

Proprietà di sottoscrizione push

Quando configuri una sottoscrizione push, puoi specificare le seguenti proprietà.

Endpoint

URL endpoint (obbligatorio). Un indirizzo HTTPS accessibile pubblicamente. Il server per l'endpoint push deve avere un certificato SSL valido firmato da un'autorità di certificazione. Il servizio Pub/Sub invia i messaggi agli endpoint push dalla stessa regione Google Cloud in cui il servizio Pub/Sub li archivia. Il servizio Pub/Sub invia messaggi dalla stessa regione Google Cloud secondo il criterio del "best effort".

Pub/Sub non richiede più una prova della proprietà per i domini URL con sottoscrizione push. Se il tuo dominio riceve richieste POST inaspettate da Pub/Sub, puoi segnalare un presunto abuso.

Autenticazione

Attiva l'autenticazione. Se questa opzione è attivata, i messaggi inviati da Pub/Sub all'endpoint push includono un'intestazione di autorizzazione per consentire all'endpoint di autenticare la richiesta. I meccanismi di autenticazione e autorizzazione automatici sono disponibili per gli endpoint delle funzioni App Engine Standard e Cloud Run ospitati nello stesso progetto dell'abbonamento.

La configurazione dell'autenticazione per una sottoscrizione push autenticata è costituita da un account di servizio gestito dall'utente e dai parametri del segmento di pubblico specificati in una chiamata create, patch o ModifyPushConfig. Devi anche concedere un ruolo specifico a un agente di servizio, come discusso nella sezione successiva.

• Account di servizio gestito dall'utente (obbligatorio). L'account di servizio associato all'iscrizione push. Questo account viene utilizzato come attestazione email del token web JSON (JWT) generato. Di seguito è riportato un elenco dei requisiti per l'account di servizio:

  • Questo account di servizio deve trovarsi nello stesso progetto dell'abbonamento push.

  • L'entità che crea o modifica l'iscrizione push deve avere l'autorizzazione iam.serviceAccounts.actAs per l'account di servizio. Puoi concedere un ruolo con questa autorizzazione al progetto, alla cartella o all'organizzazione per consentire all'utente chiamante di rubare l'identità di più account di servizio oppure concedere un ruolo con questa autorizzazione all'account di servizio per consentire all'utente chiamante di rubare l'identità solo di questo account di servizio.

• Pubblico. Una singola stringa senza sensibilità alle maiuscole che il webhook utilizza per convalidare il pubblico previsto di questo token specifico.

• Agente di servizio (obbligatorio).

  • Pub/Sub crea automaticamente un account di servizio per te con il formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

  • A questo agente di servizio deve essere concessa l'autorizzazione iam.serviceAccounts.getOpenIdToken (inclusa nel ruolo roles/iam.serviceAccountTokenCreator) per consentire a Pub/Sub di creare token JWT per le richieste push autenticate.

Annullamento del wrapping del payload

L'opzione Abilita l'annullamento del wrapping del payload rimuove da tutti i messaggi Pub/Sub tutti i metadati, ad eccezione dei dati del messaggio. Con lo scollegamento del payload, i dati del messaggio vengono inviati direttamente come corpo HTTP.

• Scrivi metadati. Aggiunge nuovamente i metadati del messaggio rimossi in precedenza all'intestazione della richiesta.

Proprietà BigQuery

Quando selezioni un tipo di importazione della sottoscrizione come Scrive in BigQuery, puoi specificare le seguenti proprietà aggiuntive.

Utilizza schema argomento

Questa opzione consente a Pub/Sub di utilizzare lo schema dell'argomento Pub/Sub a cui è associata la sottoscrizione. Inoltre, Pub/Sub scrive i campi nei messaggi nelle colonne corrispondenti della tabella BigQuery.

Quando utilizzi questa opzione, ricordati di verificare i seguenti requisiti aggiuntivi:

• I campi nello schema dell'argomento e nello schema di BigQuery devono avere gli stessi nomi e i relativi tipi devono essere compatibili tra loro.

• Qualsiasi campo facoltativo nello schema dell'argomento deve essere facoltativo anche nello schema di BigQuery.

• I campi obbligatori nello schema dell'argomento non devono essere obbligatori nello schema di BigQuery.

• Se sono presenti campi BigQuery non presenti nello schema dell'argomento, questi campi devono essere in modalità NULLABLE.

• Se lo schema dell'argomento contiene campi aggiuntivi che non sono presenti nello schema di BigQuery e che possono essere ignorati, seleziona l'opzione Ignora campi sconosciuti.

• Puoi selezionare una sola delle proprietà di sottoscrizione, Utilizza lo schema dell'argomento o Utilizza lo schema della tabella.

Se non selezioni l'opzione Utilizza schema argomento o Utilizza schema tabella, assicurati che la tabella BigQuery abbia una colonna denominata data di tipo BYTES, STRING o JSON. Pub/Sub scrive il messaggio in questa colonna BigQuery.

Le modifiche allo schema degli argomenti Pub/Sub o allo schema della tabella BigQuery potrebbero non essere applicate immediatamente ai messaggi scritti nella tabella BigQuery. Ad esempio, se l'opzione Elimina campi sconosciuti è attivata e un campo è presente nello schema Pub/Sub, ma non in quello di BigQuery, i messaggi scritti nella tabella BigQuery potrebbero non contenere ancora il campo dopo averlo aggiunto allo schema di BigQuery. Alla fine, gli schemi si sincronizzano e i messaggi successivi includono il campo.

Quando utilizzi l'opzione Utilizza schema dell'argomento per la sottoscrizione BigQuery, puoi anche usufruire del CDC (Change Data Capture) di BigQuery. CDC aggiorna le tabelle BigQuery elaborando e applicando le modifiche alle righe esistenti.

Per scoprire di più su questa funzionalità, consulta Aggiornare le tabelle di streaming con l'acquisizione dei dati sulle modifiche.

Per scoprire come utilizzare questa funzionalità con gli abbonamenti BigQuery, consulta Acquisizione dei dati sulle modifiche di BigQuery.

Utilizza schema tabella

Questa opzione consente a Pub/Sub di utilizzare lo schema della tabella BigQuery per scrivere i campi di un messaggio JSON nelle colonne corrispondenti. Quando utilizzi questa opzione, ricordati di verificare i seguenti requisiti aggiuntivi:

• I messaggi pubblicati devono essere in formato JSON.

• Sono supportate le seguenti conversioni JSON:

  Tipo JSON	Tipo di dati BigQuery
  string	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME o TIMESTAMP
  number	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME o TIMESTAMP

  • Quando utilizzi le conversioni da number a DATE, DATETIME, TIME o TIMESTAMP, il numero deve rispettare le rappresentazioni supportate.
  • Quando utilizzi la conversione da number a NUMERIC o BIGNUMERIC, la precisione e l'intervallo di valori sono limitati a quelli accettati dallo standard IEEE 754 per l'aritmetica a virgola mobile. Se hai bisogno di una precisione elevata o di una gamma più ampia di valori, utilizza le conversioni da string a NUMERIC o BIGNUMERIC.
  • Quando utilizzi le conversioni da string a NUMERIC o BIGNUMERIC, Pub/Sub presuppone che la stringa sia un numero leggibile (ad es. "123.124"). Se l'elaborazione della stringa come numero leggibile non va a buon fine, Pub/Sub la tratta come byte codificati con BigDecimalByteStringEncoder.

• Se all'argomento della sottoscrizione è associato uno schema, la proprietà di codifica dei messaggi deve essere impostata su JSON.

• Se esistono campi BigQuery non presenti nei messaggi, questi campi BigQuery devono essere in modalità NULLABLE.

• Se i messaggi contengono campi aggiuntivi non presenti nello schema BigQuery e questi campi possono essere ignorati, seleziona l'opzione Ignora campi sconosciuti.

• Puoi selezionare una sola delle proprietà di sottoscrizione, Utilizza lo schema dell'argomento o Utilizza lo schema della tabella.

Se non selezioni l'opzione Utilizza schema argomento o Utilizza schema tabella, assicurati che la tabella BigQuery abbia una colonna denominata data di tipo BYTES, STRING o JSON. Pub/Sub scrive il messaggio in questa colonna BigQuery.

Le modifiche allo schema della tabella BigQuery potrebbero non essere applicate immediatamente ai messaggi scritti nella tabella BigQuery. Ad esempio, se l'opzione Elimina campi sconosciuti è attivata e un campo è presente nei messaggi, ma non nello schema di BigQuery, i messaggi scritti nella tabella BigQuery potrebbero non contenere ancora il campo dopo averlo aggiunto allo schema di BigQuery. Alla fine, lo schema si sincronizza e i messaggi successivi includono il campo.

Quando utilizzi l'opzione Utilizza lo schema della tabella per la tua sottoscrizione BigQuery, puoi anche sfruttare il vantaggio di BigQuery Change Data Capture (CDC). CDC aggiorna le tabelle BigQuery elaborando e applicando le modifiche alle righe esistenti.

Per scoprire di più su questa funzionalità, consulta Aggiornare le tabelle di streaming con l'acquisizione dei dati sulle modifiche.

Per scoprire come utilizzare questa funzionalità con gli abbonamenti BigQuery, consulta Acquisizione dei dati sulle modifiche di BigQuery.

Rilascia campi sconosciuti

Questa opzione viene utilizzata con l'opzione Utilizza schema argomento o Utilizza schema tabella. Questa opzione consente a Pub/Sub di ignorare qualsiasi campo presente nello schema o nel messaggio dell'argomento, ma non nello schema di BigQuery. Se non è impostato Elimina campi sconosciuti, i messaggi con campi aggiuntivi non vengono scritti in BigQuery e rimangono nel backlog della sottoscrizione. L'abbonamento termina in uno stato di errore.

Scrivi metadati

Questa opzione consente a Pub/Sub di scrivere i metadati di ogni messaggio in colonne aggiuntive della tabella BigQuery. In caso contrario, i metadati non vengono scritti nella tabella BigQuery.

Se selezioni l'opzione Scrivi metadati, assicurati che la tabella BigQuery contenga i campi descritti nella tabella seguente.

Se non selezioni l'opzione Scrivi metadati, la tabella BigQuery di destinazione richiede solo il campo data, a meno che use_topic_schema non sia true. Se selezioni sia l'opzione Scrivi metadati sia Utilizza schema argomento, lo schema dell'argomento non deve contenere campi con nomi corrispondenti a quelli dei parametri dei metadati. Questa limitazione include le versioni con lettere maiuscole di questi parametri con lettere minuscole.

Parametri
subscription_name	STRING Nome di un abbonamento.
message_id	STRING ID di un messaggio
publish_time	TIMESTAMP L'ora di pubblicazione di un messaggio.
data	BYTES, STRING o JSON Il corpo del messaggio. Il campo data è obbligatorio per tutte le tabelle BigQuery di destinazione che non selezionano Utilizza schema argomento o Utilizza schema tabella. Se il campo è di tipo JSON, il corpo del messaggio deve essere JSON valido.
attributes	STRING o JSON Un oggetto JSON contenente tutti gli attributi del messaggio. Contiene inoltre campi aggiuntivi che fanno parte del messaggio Pub/Sub, inclusa la chiave di ordinamento, se presente.

Proprietà Cloud Storage

Quando selezioni un tipo di importazione dell'abbonamento come Scrittura in Cloud Storage, puoi specificare le seguenti proprietà aggiuntive.

Nome bucket

Prima di creare un abbonamento Cloud Storage, deve già esistere un bucket Cloud Storage.

I messaggi vengono inviati in batch e archiviati nel bucket Cloud Storage. Un singolo batch o file viene archiviato come oggetto nel bucket.

Il bucket Cloud Storage deve avere la funzionalità Pagamento a carico del richiedente disabilitata.

Per creare un bucket Cloud Storage, consulta Creare bucket.

Prefisso, suffisso e data e ora del nome file

I file Cloud Storage di output generati dall'abbonamento Cloud Storage vengono archiviati come oggetti nel bucket Cloud Storage. Il nome dell'oggetto archiviato nel bucket Cloud Storage è nel seguente formato: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

L'elenco seguente include i dettagli del formato del file e i campi che puoi personalizzare:

• <file-prefix> è il prefisso del nome file personalizzato. Questo è un campo facoltativo.

• <UTC-date-time> è una stringa generata automaticamente personalizzabile in base al momento della creazione dell'oggetto.

• <uuid> è una stringa casuale generata automaticamente per l'oggetto.

• <file-suffix> è il suffisso del nome file personalizzato. Questo è un campo facoltativo. Il sufisso del nome del file non può terminare con "/".

• Puoi modificare il prefisso e il suffisso del nome file:

  • Ad esempio, se il valore del prefisso del nome del file è prod_ e il valore del suffisso del nome del file è _archive, un nome di oggetto di esempio è prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Se non specifichi il prefisso e il suffisso del nome file, il nome dell'oggetto memorizzato nel bucket Cloud Storage ha il seguente formato: <UTC-date-time>_<uuid>.

  • I requisiti di denominazione degli oggetti Cloud Storage si applicano anche al prefisso e al suffisso del nome del file. Per saperne di più, consulta Informazioni sugli oggetti Cloud Storage.

• Puoi modificare la modalità di visualizzazione della data e dell'ora nel nome file:

  • Confronti datetime obbligatori che puoi utilizzare una sola volta: anno (YYYY o YY), mese (MM), giorno (DD), ora (hh), minuto (mm), secondo (ss). Ad esempio, YY-YYYY o MMM non sono validi.

  • Confronti facoltativi che puoi utilizzare una sola volta: separatore data/ora (T) e differenza di fuso orario (Z o +00:00).

  • Elementi facoltativi che puoi utilizzare più volte: trattino (-), trattino basso (_), due punti (:) e barra (/).

  • Ad esempio, se il valore del formato data e ora del nome del file è YYYY-MM-DD/hh_mm_ssZ, un nome di oggetto di esempio è prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Se il formato data/ora del nome del file termina con un carattere che non è un'espressione di corrispondenza, questo carattere sostituirà il separatore tra <UTC-date-time> e <uuid>. Ad esempio, se il valore del formato datetime del nome del file è YYYY-MM-DDThh_mm_ss-, un nome di oggetto di esempio è prod_2023-09-25T04_10_00-uNiQuE_archive.

Raggruppamento di file

Le iscrizioni Cloud Storage ti consentono di decidere quando creare un nuovo file di output archiviato come oggetto nel bucket Cloud Storage. Pub/Sub scrive un file di output quando viene soddisfatta una delle condizioni di raggruppamento specificate. Di seguito sono riportate le condizioni di raggruppamento di Cloud Storage:

• Durata massima del batch di archiviazione. Questa è un'impostazione obbligatoria. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il valore specificato per la durata massima. Se non lo specifichi, viene applicato un valore predefinito di 5 minuti. Di seguito sono riportati i valori applicabili per la durata massima:

  • Valore minimo = 1 minuto
  • Valore predefinito = 5 minuti
  • Valore massimo = 10 minuti

• Byte massimi batch di archiviazione. Questa è un'impostazione facoltativa. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il valore specificato di byte massimi. Di seguito sono riportati i valori applicabili per i byte massimi:

  • Valore minimo = 1 KB
  • Valore massimo = 10 GiB

• Messaggi relativi al limite massimo del batch di archiviazione. Questa è un'impostazione facoltativa. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il numero specificato di messaggi massimi. Di seguito sono riportati i valori applicabili per i messaggi massimi:

  • Valore minimo = 1000

Ad esempio, puoi configurare la durata massima come 6 minuti e il numero massimo di byte come 2 GB. Se al quarto minuto il file di output raggiunge le dimensioni di 2 GB, Pub/Sub completa il file precedente e inizia a scrivere in un nuovo file.

Un abbonamento Cloud Storage potrebbe scrivere contemporaneamente in più file di un bucket Cloud Storage. Se hai configurato il tuo abbonamento in modo da creare un nuovo file ogni 6 minuti, potresti notare la creazione di più file Cloud Storage ogni 6 minuti.

In alcuni casi, Pub/Sub potrebbe iniziare a scrivere in un nuovo file prima dell'ora configurata dalle condizioni di raggruppamento dei file. Un file potrebbe anche superare il valore di byte massimi se l'abbonamento riceve messaggi più grandi del valore di byte massimi.

Formato file

Quando crei un abbonamento Cloud Storage, puoi specificare il formato dei file di output da archiviare in un bucket Cloud Storage come Testo o Avro.

• Testo: i messaggi vengono memorizzati in testo normale. Un carattere di a capo separa un messaggio dal messaggio precedente nel file. Vengono archiviati solo i payload dei messaggi, non gli attributi o altri metadati.

• Avro: i messaggi vengono archiviati in formato binario Apache Avro. Quando selezioni Avro, puoi attivare le seguenti proprietà aggiuntive:

  • Scrivi metadati: questa opzione ti consente di archiviare i metadati del messaggio insieme al messaggio. I metadati come i campi subscription_name, message_id, publish_time e attributes vengono scritti nei campi di primo livello dell'oggetto Avro di output, mentre tutte le altre proprietà del messaggio diverse dai dati (ad esempio, un valore ordering_key, se presente) vengono aggiunte come voci nella mappa attributes.

    Se l'opzione metadati di scrittura è disattivata, nell'oggetto Avro di output viene scritto solo il payload del messaggio. Ecco lo schema Avro per i messaggi di output con i metadati di scrittura disattivati:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    Ecco lo schema Avro per i messaggi di output con metadati di scrittura abilitati:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • Utilizza schema argomento: questa opzione consente a Pub/Sub di utilizzare lo schema dell'argomento Pub/Sub a cui è associata la sottoscrizione durante la scrittura dei file Avro.

    Quando utilizzi questa opzione, ricordati di verificare i seguenti requisiti aggiuntivi:

    • Lo schema dell'argomento deve essere in formato Apache Avro.

    • Se sono abilitati sia Utilizza schema dell'argomento sia Scrivi metadati, lo schema dell'argomento deve avere un oggetto Record alla radice. Pub/Sub espande l'elenco dei campi del record in modo da includere i campi dei metadati. Di conseguenza, il record non può contenere campi con lo stesso nome dei campi dei metadati (subscription_name, message_id, publish_time o attributes).

Passaggi successivi

• Crea una sottoscrizione pull.
• Crea una sottoscrizione push.
• Crea una sottoscrizione BigQuery.
• Crea una sottoscrizione Cloud Storage.