Quando crei il tuo sistema Pub/Sub, l'unwrapping del payload può aiutarti a connetterti ad altri sistemi che non rispettano tutti i requisiti di sistema di un'implementazione standard di endpoint push di Pub/Sub.
Di seguito sono riportati alcuni casi d'uso potenziali per l'annullamento del wrapping del payload:
- Non è consigliabile scrivere il codice di analisi di messaggi specifici per Pub/Sub per gli endpoint push HTTP.
- Preferisci ricevere i metadati dei messaggi Pub/Sub come intestazioni HTTP anziché i metadati nel corpo POST HTTP.
- Vuoi inviare messaggi Pub/Sub ed escludere i metadati Pub/Sub, ad esempio durante l'invio di dati a un'API di terze parti.
Come funziona l'annullamento del wrapping del payload
L'annullamento del wrapping del payload è una funzionalità che rimuove i messaggi Pub/Sub di tutti i metadati dei messaggi, ad eccezione dei dati dei messaggi. Inviando dati non elaborati, i sottoscrittori possono elaborarlo senza dover rispettare alcun requisito di sistema di Pub/Sub.
- Con l'annullamento del wrapping del payload, i dati dei messaggi vengono consegnati direttamente come corpo HTTP.
- Senza l'annullamento del wrapping del payload, Pub/Sub fornisce un oggetto JSON che contiene più campi di metadati dei messaggi e un campo per i dati dei messaggi. In questo caso, il codice JSON deve essere analizzato per recuperare i dati del messaggio e poi decodificato in base64.
Scrivi metadati
Dopo aver attivato l'annullamento del wrapping del payload, puoi utilizzare l'opzione write metadata, che aggiunge metadati dei messaggi rimossi in precedenza nell'intestazione della richiesta.
- Scrittura metadati abilitata. Aggiungi di nuovo i metadati del messaggio all'intestazione della richiesta. Fornisce anche i dati dei messaggi non elaborati e decodificati.
- Scrittura metadati disabilitata. Invia solo i dati dei messaggi non elaborati e decodificati.
I metadati di scrittura sono esposti tramite Pub/Sub, l'argomento Google Cloud CLI
--push-no-wrapper-write-metadata
e la proprietà API NoWrapper
.
Per impostazione predefinita, questo valore è nullo.
Prima di iniziare
- Scopri di più sulle sottoscrizioni e sulle sottoscrizioni push di Pub/Sub. L'annullamento del wrapping del payload può essere usato solo con le sottoscrizioni push.
- Scopri come configurare una sottoscrizione push.
Esempio di messaggi con wrapping e unwrapping
I seguenti esempi illustrano la differenza tra l'invio di un messaggio HTTP con wrapping e senza wrapper. In questi esempi, i dati dei messaggi contengono
la stringa {"status": "Hello there"}
.
In questo esempio, viene creata una sottoscrizione con la funzionalità di unwrapping del payload abilitata e pubblica un messaggio su mytopic
. Utilizza una chiave di ordinamento con valore some-key
e il tipo di media è dichiarato come application/json
.
gcloud pubsub topics publish mytopic --message='{"status": "Hello there"}' --ordering-key="some-key" --attribute "Content-Type=application/json"
Le seguenti sezioni mostrano la differenza tra un messaggio con wrapping e un messaggio non aggregato.
Messaggio con wrapping
L'esempio seguente mostra un messaggio con wrapping Pub/Sub standard. In questo caso, l'unwrapping del payload non è abilitato.
Pubblicazione | Ricezione endpoint push |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 361 Content-Type: application/json User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com { "message": { "attributes": { "Content-Type": "application/json" }, "data": "eyJzdGF0dXMiOiAiSGVsbG8gdGhlcmUifQ==", // Base64 - {"status": "Hello there"} "messageId": "2070443601311540", "message_id": "2070443601311540", "publishTime": "2021-02-26T19:13:55.749Z", "publish_time": "2021-02-26T19:13:55.749Z" }, "subscription": "projects/myproject/..." } |
Messaggio con wrapping con metadati di scrittura disabilitati
L'esempio seguente mostra un messaggio senza wrapping con l'opzione Scrivi metadati disabilitata. In questo caso, le intestazioni x-goog-pubsub-*
e gli attributi dei messaggi
non sono inclusi.
Pubblicazione | Ricezione endpoint push |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 25 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
Messaggio con wrapping con metadati di scrittura abilitati
L'esempio seguente mostra un messaggio senza wrapping con l'opzione Scrivi metadati abilitata. In questo caso, sono inclusi le intestazioni x-goog-pubsub-*
e gli attributi dei messaggi.
Pubblicazione | Ricezione endpoint push |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
x-goog-pubsub-subscription-name: "projects/myproject/..." x-goog-pubsub-message-id: "2070443601311540" x-goog-pubsub-publish-time: "2021-02-26T19:13:55.749Z" x-goog-pubsub-ordering-key: "some-key" Content-Type: application/json Content-Length: 12 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
Configura l'annullamento del wrapping del payload
Puoi abilitare la consegna push dell'annullamento del wrapping del payload per un abbonamento utilizzando la pagina dei dettagli dell'abbonamento della console Google Cloud, Google Cloud CLI o le librerie client.
Console
Nella console Google Cloud, vai alla pagina Abbonamenti.
Fai clic su Crea sottoscrizione.
Nel campo ID abbonamento, inserisci un nome.
Per informazioni su come assegnare un nome a una sottoscrizione, vedi Linee guida per assegnare un nome a un argomento o a una sottoscrizione.
Seleziona un argomento dal menu a discesa. La sottoscrizione riceve messaggi dall'argomento.
Per Tipo di pubblicazione, seleziona Push.
Per attivare l'annullamento del wrapping del payload, seleziona Abilita l'annullamento del wrapping del payload.
(Facoltativo) Per conservare i metadati dei messaggi nell'intestazione della richiesta, seleziona Scrivi metadati. Devi abilitare questa opzione per impostare un'intestazione Content-Type per i tuoi messaggi.
Specifica l'URL di un endpoint.
Conserva tutti gli altri valori predefiniti.
Fai clic su Crea.
gcloud
Per configurare una sottoscrizione con l'annullamento del wrapping del payload che includa intestazioni HTTP standard, esegui questo comando gcloud pubsub subscriptions create
:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
Sostituisci quanto segue:
SUBSCRIPTION
: il nome o l'ID della tua sottoscrizione pull.TOPIC
: l'ID dell'argomento.PUSH_ENDPOINT
: l'URL da utilizzare come endpoint per questo abbonamento. Ad esempio,https://myproject.appspot.com/myhandler
--push-no-wrapper
: consegna i dati del messaggio direttamente come corpo HTTP.
Per configurare una sottoscrizione con l'annullamento del wrapping del payload e controllare l'uso delle intestazioni x-goog-pubsub-*
, esegui questo comando:
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
--push-no-wrapper-write-metadata
: se impostato su true, scrive i metadati del messaggio Pub/Sub nelle intestazionix-goog-pubsub-<KEY>:<VAL>
della richiesta HTTP. Scrive gli attributi dei messaggi Pub/Sub nelle intestazioni<KEY>:<VAL>
della richiesta HTTP.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python Pub/Sub.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Java Pub/Sub.
C++
Prima di provare questo esempio, segui le istruzioni per la configurazione di C++ nella Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Go.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in Guida rapida: utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Imposta un'intestazione per tipo di contenuti nel messaggio
Dopo aver abilitato l'annullamento del wrapping del payload, Pub/Sub non imposta automaticamente un campo di intestazione per il tipo di media nella richiesta. Se non imposti esplicitamente un campo intestazione Content-Type
, il server web che elabora la richiesta potrebbe impostare un valore predefinito application/octet-stream
o interpretare la richiesta in modo imprevisto.
Se hai bisogno di un'intestazione Content-Type
, assicurati di dichiararla esplicitamente
al momento della pubblicazione di ogni singolo messaggio pubblicato. Per farlo, devi prima abilitare Scrivi metadati. Questo risultato dell'abilitazione di Scrivi metadati
viene mostrato negli esempi forniti.
Passaggi successivi
- Se hai problemi con l'annullamento del wrapping del payload, vedi Risolvere i problemi relativi all'annullamento del wrapping del payload.