Questa pagina è stata tradotta dall'API Cloud Translation.

Proprietà di abbonamento

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

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

Prima di iniziare

Scopri di più sugli abbonamenti.
Comprendi il flusso di lavoro per l'abbonamento che creerai: pull, push o BigQuery.

Proprietà comuni dell'abbonamento

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 trattate 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 del periodo di conservazione dei messaggi, Pub/Sub potrebbe eliminare il messaggio indipendentemente dallo stato di conferma del messaggio. Per conservare i messaggi confermati per la durata di conservazione dei messaggi, vedi Riproduzione e eliminazione dei 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 il risultato di sottoscrizioni inattive, esigenze di backup o elaborazione lenta. Se riesci a elaborare i messaggi entro 24 ore, non ti verranno addebitati costi aggiuntivi. Puoi evitare nuovi addebiti gestendo questi scenari nel seguente modo:

Abbonamenti inattivi. Elimina gli abbonamenti inattivi per evitare addebiti per la conservazione dei messaggi di abbonamento.
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 memorizza i messaggi una sola volta a livello di argomento e rimangono disponibili per tutte le sottoscrizioni da utilizzare quando necessario.
Ritardi nell'elaborazione. Aggiungi altri abbonati (se possibile) per elaborare i messaggi entro un giorno.

Conserva messaggi confermati

Se specifichi la durata di conservazione dei messaggi, puoi anche specificare se vuoi 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 maggiori informazioni, consulta la pagina 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à o modifiche apportate alle proprietà dell'abbonamento scadono. Se Pub/Sub rileva l'attività dei sottoscrittori o se aggiorni una delle proprietà dell'abbonamento, il conto alla rovescia per l'eliminazione dell'abbonamento riparte. Esempi di attività dell'abbonato includono connessioni aperte, pull attivi o push riusciti.

Se specifichi il periodo di scadenza, il valore deve essere almeno pari alla durata della conservazione dei messaggi specificata nell'opzione Durata della 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 una sottoscrizione scada, imposta il periodo di scadenza su never expire.

Scadenza per la conferma

L'opzione Scadenza della conferma specifica la scadenza iniziale dopo la quale un messaggio non confermato viene inviato di nuovo. Puoi estendere la scadenza dell'acknowledgement per singolo messaggio inviando richieste ModifyAckDeadline successive.

Di seguito sono riportati i valori per l'opzione Termine di conferma:

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

In alcuni casi, le librerie client Pub/Sub possono controllare la velocità di pubblicazione e modificare dinamicamente il termine di riconoscimento. In questo modo, il messaggio potrebbe essere recapitato nuovamente prima della scadenza della 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.

Single Message Transforms (SMT)

Le SMT consentono modifiche leggere agli attributi e ai dati dei messaggi direttamente in Pub/Sub. Questa funzionalità consente la pulizia, il filtraggio o la conversione del formato dei dati prima che i messaggi vengano inviati a un client abbonato.

Per saperne di più, vedi Panoramica delle SMT e Creare un abbonamento con le SMT.

Filtro sottoscrizioni

Utilizza l'opzione Filtro sottoscrizione per specificare una stringa con un'espressione di filtro. Se un abbonamento ha un filtro, vengono inviati solo i messaggi che corrispondono al filtro. Il servizio Pub/Sub riconosce 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, l'abbonamento 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 correlate alla ricerca.

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

Ordinamento messaggi

Quando una sottoscrizione ha l'ordinamento dei messaggi abilitato, i client sottoscrittori ricevono i messaggi pubblicati nella stessa regione con la stessa chiave di ordinamento nell'ordine in cui sono stati ricevuti dal servizio.

Quando utilizzi la consegna ordinata, le conferme di ricezione dei messaggi successivi non vengono elaborate finché non vengono elaborate le conferme di ricezione dei messaggi precedenti.

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

Se non è impostato, Pub/Sub potrebbe non recapitare 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 la ricezione del messaggio, puoi configurare un argomento messaggi non recapitabili in 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 consegna
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 specificare anche l'ID progetto con l'argomento dei argomento messaggi non recapitabili.

Per saperne di più, consulta Forwarding agli argomenti dead letter.

Policy di ripetizione

Se la scadenza di conferma scade o un abbonato risponde con una conferma negativa, Pub/Sub può inviare nuovamente il messaggio. Questo tentativo di riconsegna è noto come 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 il termine di 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 massimo e minimo:

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.

Policy di ripetizione e messaggi batch

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

Il sottoscrittore invia un riconoscimento negativo per ogni messaggio nel batch.
La scadenza per la conferma scade.

Policy di ripetizione e sottoscrizione push

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

Proprietà della sottoscrizione pull

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

Consegna "exactly-once"

Consegna "exactly-once". Se impostato, Pub/Sub soddisfa le garanzie di consegna exactly-once. Se non specificato, l'abbonamento supporta la distribuzione at-least-once per ogni messaggio.

Proprietà della sottoscrizione push

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

Endpoint

URL dell'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 recapita i messaggi agli endpoint push dalla stessa regione Google Cloud in cui il servizio Pub/Sub archivia i messaggi. Il servizio Pub/Sub recapita i messaggi dalla stessa regione Google Cloud con il criterio "best effort".

Se gli abbonati utilizzano un firewall, non possono ricevere richieste push. Per ricevere richieste push, devi disattivare il firewall e verificare il token JWT (JSON Web Token) utilizzato nella richiesta. Se un abbonato ha un firewall, potresti ricevere un errore 403 permission denied.
Pub/Sub non richiede più la prova della proprietà per i domini URL con sottoscrizione push. Se il tuo dominio riceve richieste POST impreviste da Pub/Sub, puoi segnalare un sospetto abuso.

Autenticazione

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

La configurazione dell'autenticazione per un abbonamento push autenticato è costituita da un account di servizio gestito dall'utente e dai parametri audience specificati in una chiamata create, patch o ModifyPushConfig. Devi anche concedere un ruolo specifico a un account di servizio, come descritto nella sezione successiva.

Pubblico. Una singola stringa senza distinzione tra maiuscole e minuscole che il webhook utilizza per convalidare il pubblico di destinazione di questo token specifico.
Service account. Pub/Sub crea automaticamente un account di servizio per te con il formato service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

Prerequisiti per l'attivazione dell'autenticazione

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

Questo service account gestito dall'utente deve trovarsi nello stesso progetto dell'abbonamento push.
L'entità che crea o modifica la sottoscrizione push deve disporre dell'autorizzazione iam.serviceAccounts.actAs per l'account di servizio gestito dall'utente per collegare l'account di servizio alla sottoscrizione push. Per saperne di più, consulta Collegamento di service account alle risorse.
Autorizzazioni richieste: a questo service account deve essere concessa l'autorizzazione iam.serviceAccounts.getOpenIdToken (inclusa nel ruolo roles/iam.serviceAccountTokenCreator) per consentire a Pub/Sub di creare token JWT per l'account di servizio specificato per autenticare le richieste push.

Annullamento del wrapping del payload

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

Puoi anche attivare l'opzione Scrivi metadati. L'opzione Scrivi metadati aggiunge nuovamente i metadati del messaggio rimossi in precedenza all'intestazione della richiesta.

Proprietà BigQuery

Quando selezioni Scrivi in BigQuery come tipo di distribuzione della sottoscrizione, 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 è collegata la sottoscrizione. Inoltre, Pub/Sub scrive i campi nei messaggi nelle colonne corrispondenti della tabella BigQuery.

Quando utilizzi questa opzione, ricorda di controllare i seguenti requisiti aggiuntivi:

I campi nello schema dell'argomento e nello schema BigQuery devono avere gli stessi nomi e i loro tipi devono essere compatibili tra loro.
Qualsiasi campo facoltativo nello schema dell'argomento deve essere facoltativo anche nello schema BigQuery.
I campi obbligatori nello schema dell'argomento non devono essere obbligatori nello schema BigQuery.
Se sono presenti campi BigQuery non presenti nello schema dell'argomento, questi campi BigQuery devono essere in modalità NULLABLE.
Se lo schema dell'argomento ha campi aggiuntivi che non sono presenti nello schema BigQuery e questi campi possono essere eliminati, seleziona l'opzione Elimina campi sconosciuti.
Puoi selezionare solo una delle proprietà dell'abbonamento, Usa schema argomento o Usa schema 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.

Potresti non vedere immediatamente le modifiche allo schema degli argomenti Pub/Sub o allo schema della tabella BigQuery con i messaggi scritti nella tabella BigQuery. Ad esempio, se l'opzione Elimina campi sconosciuti è abilitata e un campo è presente nello schema Pub/Sub, ma non in quello BigQuery, i messaggi scritti nella tabella BigQuery potrebbero comunque non contenere il campo dopo averlo aggiunto allo schema 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 dell'acquisizione dei dati delle modifiche (CDC) di BigQuery. CDC aggiorna le tabelle BigQuery elaborando e applicando le modifiche alle righe esistenti.

Per scoprire di più su questa funzionalità, vedi Aggiornare le tabelle di flusso con l'acquisizione delle modifiche ai dati.

Per scoprire come utilizzare questa funzionalità con gli abbonamenti BigQuery, consulta Acquisizione delle modifiche ai dati 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 controllare i seguenti requisiti aggiuntivi:

I nomi di ogni colonna della tabella BigQuery devono contenere solo lettere (a-z, A-Z), numeri (0-9) o trattini bassi (_).
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 number in 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 in virgola mobile. Se hai bisogno di un'elevata precisione o di una gamma più ampia di valori, utilizza le conversioni string in 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 considera la stringa 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 sono presenti campi BigQuery non presenti nei messaggi, questi campi BigQuery devono essere in modalità NULLABLE.
Se i messaggi hanno campi aggiuntivi non presenti nello schema BigQuery e questi campi possono essere eliminati, seleziona l'opzione Elimina campi sconosciuti.
Puoi selezionare solo una delle proprietà dell'abbonamento, Usa schema argomento o Usa schema tabella.

Potresti non vedere immediatamente le modifiche allo schema della tabella BigQuery con i messaggi scritti nella tabella BigQuery. Ad esempio, se l'opzione Ignora campi sconosciuti è abilitata e un campo è presente nei messaggi, ma non nello schema BigQuery, i messaggi scritti nella tabella BigQuery potrebbero comunque non contenere il campo dopo averlo aggiunto allo schema BigQuery. Alla fine, lo schema viene sincronizzato e i messaggi successivi includono il campo.

Quando utilizzi l'opzione Utilizza schema tabella per la tua sottoscrizione BigQuery, puoi anche usufruire 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à, vedi Aggiornare le tabelle di flusso con l'acquisizione delle modifiche ai dati.

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

Rilascia campi sconosciuti

Questa opzione viene utilizzata con l'opzione Utilizza schema argomento o Utilizza schema tabella. Se questa opzione è abilitata, Pub/Sub ignora qualsiasi campo presente nello schema dell'argomento o nel messaggio, ma non nello schema BigQuery. I campi che non fanno parte dello schema BigQuery vengono eliminati durante la scrittura del messaggio nella tabella BigQuery.

Se l'opzione Elimina campi sconosciuti non è impostata, i messaggi con campi aggiuntivi non vengono scritti in BigQuery e rimangono nel backlog della sottoscrizione, a meno che non configuri un argomento messaggi non recapitabili.

L'impostazione Ignora campi sconosciuti non influisce sui campi non definiti nello schema dell'argomento Pub/Sub o nello schema della tabella BigQuery. In questo caso, alla sottoscrizione viene recapitato un messaggio Pub/Sub valido. Tuttavia, poiché BigQuery non ha colonne definite per questi campi aggiuntivi, questi campi vengono eliminati durante il processo di scrittura BigQuery. Per evitare questo comportamento, assicurati che qualsiasi campo contenuto nel messaggio Pub/Sub sia contenuto anche nello schema della tabella BigQuery.

Il comportamento relativo ai campi aggiuntivi può dipendere anche dal tipo di schema specifico (Avro, buffer di protocollo) e dalla codifica (JSON, binaria) utilizzati. Per informazioni su come questi fattori influiscono sulla gestione dei campi aggiuntivi, consulta la documentazione relativa al tipo di schema e alla codifica specifici.

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 le opzioni Scrivi metadati e 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 camel case di questi parametri snake case.

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 un JSON valido.
`attributes`	STRING o JSON Un oggetto JSON contenente tutti gli attributi del messaggio. Contiene anche campi aggiuntivi che fanno parte del messaggio Pub/Sub, inclusa la chiave di ordinamento, se presente.

Proprietà di Cloud Storage

Quando selezioni Scrivi in Cloud Storage come tipo di distribuzione della sottoscrizione, puoi specificare le seguenti proprietà aggiuntive.

Nome bucket

Prima di creare una sottoscrizione 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 Pagamenti a carico del richiedente disabilitato.

Per creare un bucket Cloud Storage, consulta Creare bucket.

Prefisso, suffisso e data/ora del nome file

I file Cloud Storage di output generati dall'abbonamento a 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>.

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

<file-prefix> è il prefisso personalizzato del nome file. Questo è un campo facoltativo.
<UTC-date-time> è una stringa personalizzabile generata automaticamente in base all'ora in cui viene creato l'oggetto.
<uuid> è una stringa casuale generata automaticamente per l'oggetto.
<file-suffix> è il suffisso personalizzato del nome file. Questo è un campo facoltativo. Il suffisso del nome file non può terminare con "/".
Puoi modificare il prefisso e il suffisso del nome file:
- Ad esempio, se il valore del prefisso del nome file è prod_ e il valore del suffisso del nome file è _archive, un nome 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 archiviato nel bucket Cloud Storage ha il 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 maggiori informazioni, consulta Informazioni sugli oggetti Cloud Storage.
Puoi modificare la modalità di visualizzazione della data e dell'ora nel nome file:
- Corrispondenze datetime obbligatorie 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.
- Corrispondenze facoltative che puoi utilizzare una sola volta: separatore di data e ora (T) e offset del 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 file è YYYY-MM-DD/hh_mm_ssZ, un nome oggetto di esempio è prod_2023-09-25/04_10_00Z_uNiQuE_archive.
- Se il formato data e ora del nome file termina con un carattere che non è un matcher, questo carattere sostituirà il separatore tra <UTC-date-time> e <uuid>. Ad esempio, se il valore del formato data e ora del nome file è YYYY-MM-DDThh_mm_ss-, un nome oggetto di esempio è prod_2023-09-25T04_10_00-uNiQuE_archive.

Batch di file

Gli abbonamenti 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 batch specificate. Di seguito sono riportate le condizioni di batch di Cloud Storage:

Durata massima batch di archiviazione. Questa è un'impostazione obbligatoria. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il valore specificato della durata massima. Se non specifichi il valore, 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 GB
Messaggi massimi batch di archiviazione. Questa è un'impostazione facoltativa. L'abbonamento Cloud Storage scrive un nuovo file di output se viene superato il numero massimo di messaggi specificato. Di seguito sono riportati i valori applicabili per max_messages:
- Valore minimo = 1000

Ad esempio, puoi configurare la durata massima come 6 minuti e i byte massimi come 2 GB. Se al quarto minuto il file di output raggiunge una dimensione di 2 GB, Pub/Sub finalizza il file precedente e inizia a scrivere in un nuovo file.

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

In alcune situazioni, 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 Max bytes se l'abbonamento riceve messaggi più grandi del valore Max bytes.

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 come testo normale. Un carattere di nuova riga separa un messaggio da quello 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 memorizzare 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, una chiave di ordinamento, se presente) vengono aggiunte come voci nella mappa attributes.
  
  Se l'opzione Scrivi metadati è disattivata, nell'oggetto Avro di output viene scritto solo il payload del messaggio. Ecco lo schema Avro per i messaggi di output con l'opzione Scrivi metadati disattivata:
```
{
  "type": "record",
  "namespace": "com.google.pubsub",
  "name": "PubsubMessage",
  "fields": [
    { "name": "data", "type": "bytes" }
  ]
}
```
  Ecco lo schema Avro per i messaggi di output con l'opzione Scrivi metadati abilitata:
```
{
  "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 è collegata la sottoscrizione durante la scrittura dei file Avro.
  
  Quando utilizzi questa opzione, ricorda di controllare i seguenti requisiti aggiuntivi:
  - Lo schema dell'argomento deve essere in formato Apache Avro.
  - Se sono abilitate sia l'opzione Usa schema dell'argomento sia l'opzione Scrivi metadati, lo schema dell'argomento deve avere un oggetto Record alla radice. Pub/Sub espanderà l'elenco dei campi del record per 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).

Service account

Hai le seguenti opzioni per scrivere messaggi in una tabella BigQuery o in un bucket Cloud Storage:

Configura un service account personalizzato in modo che solo gli utenti che dispongono dell'autorizzazione iam.serviceAccounts.actAs per il account di servizio possano creare un abbonamento che scrive nella tabella o nel bucket. Un ruolo di esempio che include l'autorizzazione iam.serviceAccounts.actAs è il ruolo Utente account di servizio (roles/iam.serviceAccountUser).
Utilizza l'agente di servizio Pub/Sub predefinito che consente a qualsiasi utente con la possibilità di creare sottoscrizioni nel progetto di creare una sottoscrizione che scrive nella tabella o nel bucket. L'agente di servizio Pub/Sub è l'impostazione predefinita quando non specifichi un service account personalizzato.