Questo documento spiega come creare una sottoscrizione Pub/Sub con Single Message Transform (SMT).
Le SMT di sottoscrizione consentono modifiche leggere ai dati e agli attributi 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 creare una sottoscrizione con SMT, puoi utilizzare la Trusted Cloud console, Google Cloud CLI, la libreria client o l'API Pub/Sub.
Prima di iniziare
Scopri di più sul servizio Pub/Sub e sulla sua terminologia.
Scopri di più sulle SMT.
Ruoli e autorizzazioni richiesti
Per ottenere le autorizzazioni
necessarie per creare un abbonamento con SMT,
chiedi all'amministratore di concederti il ruolo IAM
Pub/Sub Editor (roles/pubsub.editor
)
nel progetto.
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Questo ruolo predefinito contiene le autorizzazioni necessarie per creare un abbonamento con SMT. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
Per creare un abbonamento con SMT sono necessarie le seguenti autorizzazioni:
-
Concedi l'autorizzazione per creare una sottoscrizione nel progetto:
pubsub.subscriptions.create
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
A seconda del tipo di abbonamento, potresti aver bisogno di autorizzazioni aggiuntive. Per scoprire l'elenco esatto delle autorizzazioni, consulta il documento che illustra la creazione dell'abbonamento specifico. Ad esempio, se stai creando una sottoscrizione BigQuery con SMT, consulta la pagina Creare sottoscrizioni BigQuery.
Se crei una sottoscrizione in un progetto diverso da quello dell'argomento, devi concedere il ruolo roles/pubsub.subscriber
all'entità del progetto che contiene la sottoscrizione nel progetto che contiene l'argomento.
Puoi configurare il controllo dell'accesso a livello di progetto e a livello di singola risorsa.
Creare una sottoscrizione con SMT
Prima di creare un abbonamento con SMT, consulta la documentazione relativa alle proprietà di un abbonamento.
I seguenti esempi presuppongono che tu voglia creare un abbonamento con questa funzione definita dall'utente SMT. Per saperne di più sulle UDF, consulta la panoramica delle UDF.
function redactSSN(message, metadata) {
const data = JSON.parse(message.data);
delete data['ssn'];
message.data = JSON.stringify(data);
return message;
}
Console
Nella console Trusted Cloud , vai alla pagina Sottoscrizioni di Pub/Sub.
-
Fai clic su Crea sottoscrizione.
Viene visualizzata la pagina Crea sottoscrizione.
-
Nel campo ID abbonamento, inserisci un ID per l'abbonamento. Per ulteriori informazioni sulla denominazione degli abbonamenti, consulta le linee guida per la denominazione.
-
In Trasformazioni, fai clic su Aggiungi una trasformazione.
-
Inserisci un nome di funzione. Ad esempio:
redactSSN
. -
Se non vuoi utilizzare la SMT con il tuo abbonamento immediatamente, fai clic sull'opzione Disattiva trasformazione. L'SMT verrà comunque salvato, ma non verrà eseguito man mano che i messaggi scorrono nella sottoscrizione.
-
Inserisci una nuova trasformazione. Ad esempio:
function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; }
-
Pub/Sub fornisce una funzione di convalida che consente di convalidare un SMT. Fai clic su Convalida per convalidare la trasformazione.
-
Se vuoi aggiungere un'altra trasformazione, fai clic su Aggiungi una trasformazione.
- Per disporre tutti gli SMT in un ordine specifico, puoi utilizzare le frecce su e giù. Per rimuovere un SMT, fai clic sul pulsante di eliminazione.
-
Pub/Sub fornisce una funzione di test che consente di controllare il risultato dell'esecuzione di SMT su un messaggio di esempio. Per testare le SMT, fai clic su Testa trasformazione.
-
Nella finestra Testa trasformazione, seleziona la funzione che vuoi testare.
-
Nella finestra Messaggio di input, inserisci un messaggio di esempio.
-
Se vuoi aggiungere attributi del messaggio, fai clic su Aggiungi un attributo e inserisci una o più coppie chiave-valore.
-
Fai clic su Test. Viene visualizzato il risultato dell'applicazione delle SMT al messaggio.
-
Chiudi la finestra per interrompere il test delle SMT sui messaggi di esempio.
-
Fai clic su Crea per creare l'abbonamento.
gcloud
-
In the Trusted Cloud console, activate Cloud Shell.
At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Pub/Sub fornisce una funzione di convalida che consente di convalidare un SMT. Esegui il comando
gcloud pubsub message-transforms validate
:gcloud pubsub message-transforms validate --message-transform-file=TRANSFORM_FILE
Sostituisci quanto segue:
-
TRANSFORM_FILE: il percorso del file YAML o JSON contenente un singolo SMT.
Ecco un esempio di file di trasformazione YAML:
- javascriptUdf: code: > function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; } functionName: redactSSN
-
-
Pub/Sub fornisce una funzione di test che consente di controllare il risultato dell'esecuzione di una o più SMT su un messaggio di esempio. Esegui il comando
gcloud pubsub message-transforms test
:gcloud pubsub message-transforms test --message-transforms-file=TRANSFORMS_FILE --message=MESSAGE --attributes=ATTRIBUTES
Sostituisci quanto segue:
-
TRANSFORMS_FILE: il percorso del file YAML o JSON contenente uno o più SMT.
Ecco un esempio di file di trasformazioni YAML:
- javascriptUdf: code: > function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; } functionName: redactSSN
-
MESSAGE: Corpo del messaggio con cui testare gli SMT.
-
ATTRIBUTES: Attributi del messaggio con cui testare le SMT.
-
-
Per creare l'abbonamento, esegui il comando
gcloud pubsub subscriptions create
:gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_NAME \ --message-transforms-file=TRANSFORMS_FILE
Sostituisci quanto segue:
-
SUBSCRIPTION_ID: l'ID o il nome dell'abbonamento che vuoi creare. Per le linee guida su come denominare un abbonamento, vedi Nomi delle risorse. Il nome di un abbonamento è immutabile.
-
TOPIC_NAME: Il nome dell'argomento a cui abbonarsi, nel formato
projects/PROJECT_ID/topics/TOPIC_ID
. -
TRANSFORMS_FILE: Il percorso del file YAML o JSON contenente uno o più SMT.
Ecco un esempio di file di trasformazioni YAML:
- javascriptUdf: code: > function redactSSN(message, metadata) { const data = JSON.parse(message.data); delete data['ssn']; message.data = JSON.stringify(data); return message; } functionName: redactSSN
-
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Java.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di Pub/Sub per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Per eseguire l'autenticazione in Pub/Sub, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Prima di eseguire gli esempi di codice, imposta la variabile di ambiente
GOOGLE_CLOUD_UNIVERSE_DOMAIN
su s3nsapis.fr
.
Come interagiscono gli SMT con altre funzionalità di abbonamento
Se il tuo abbonamento utilizza sia SMT sia i filtri integrati di Pub/Sub, il filtro viene applicato prima dell'SMT. Ciò comporta le seguenti implicazioni:
- Se il tuo SMT modifica gli attributi del messaggio, il filtro Pub/Sub non viene applicato al nuovo insieme di attributi.
- Il tuo SMT non verrà applicato ai messaggi filtrati dal filtro Pub/Sub.
Se il tuo SMT filtra i messaggi, tieni presente l'impatto sul monitoraggio del backlog degli abbonamenti. Se inserisci l'abbonamento in una pipeline Dataflow, non filtrare i messaggi utilizzando SMT, in quanto interrompe la scalabilità automatica di Dataflow.