Quando crei il tuo sistema Pub/Sub, l'annullamento del wrapping del payload può aiutarti a connetterti ad altri sistemi che non rispettano tutti i requisiti di sistema di un'implementazione dell'endpoint push Pub/Sub standard.
Di seguito sono riportati alcuni potenziali casi d'uso per lo sballaggio del payload:
- Non vuoi scrivere codice di analisi dei messaggi specifico di Pub/Sub per i tuoi endpoint push HTTP.
- Preferisci ricevere i metadati dei messaggi Pub/Sub come intestazioni HTTP instead of the metadata in the HTTP POST body.
- Vuoi inviare messaggi Pub/Sub ed escludere i metadati Pub/Sub, ad esempio quando invii 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 da tutti i messaggi Pub/Sub tutti i metadati, tranne i dati dei messaggi. Inviando i dati dei messaggi non elaborati, gli abbonati possono elaborare il messaggio senza dover rispettare alcun requisito di sistema di Pub/Sub.
- Con lo scollegamento del payload, i dati del messaggio vengono inviati direttamente come corpo HTTP.
- Senza l'annullamento del wrapping del payload, Pub/Sub invia un oggetto JSON che contiene più campi di metadati dei messaggi e un campo di dati dei messaggi. In questo caso, il JSON deve essere analizzato per recuperare i dati del messaggio e poi decodificato in base64.
Scrivere metadati
Dopo aver attivato l'annullamento del wrapping del payload, puoi utilizzare l'opzione scrivi metadati, che aggiunge i metadati del messaggio rimossi in precedenza all'intestazione della richiesta.
- Metadati di scrittura abilitati. Aggiungi di nuovo i metadati del messaggio all'intestazione della richiesta. Invia anche i dati dei messaggi non elaborati e decodificati.
- Metadati di scrittura disattivati. Invia solo i dati dei messaggi non elaborati e decodificati.
I metadati di scrittura vengono esposti tramite Pub/Sub, l'argomento --push-no-wrapper-write-metadata
di Google Cloud CLI e la proprietà API NoWrapper
.
Per impostazione predefinita, questo valore è null.
Prima di iniziare
- Scopri di più sugli abbonamenti e sulle sottoscrizioni push Pub/Sub. L'annullamento del wrapping del payload può essere utilizzato solo con le iscrizioni push.
- Scopri come configurare un abbonamento push.
Esempio per messaggi con a capo e senza a capo
Gli esempi riportati di seguito illustrano la differenza tra l'invio di un messaggio HTTP con wrapping e senza wrapping. In questi esempi, i dati del messaggio contengono la stringa {"status": "Hello there"}
.
Per questo esempio, viene creata una sottoscrizione con la funzionalità di scomposizione del payload attivata e viene pubblicato un messaggio in mytopic
. Utilizza un'ordine
chiave con un valore di 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 sezioni seguenti mostrano la differenza tra un messaggio con wrapping e un messaggio senza wrapping.
Messaggio a capo
L'esempio seguente mostra un messaggio con wrapping Pub/Sub standard. In questo caso, lo scollegamento del payload non è abilitato.
Pubblica | Riceve 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 non sottoposto a wrapping con metadati di scrittura disattivati
L'esempio seguente mostra un messaggio non analizzato con l'opzione di scrittura dei metadati disabilitata. In questo caso, le intestazioni x-goog-pubsub-*
e gli attributi dei messaggi
non sono inclusi.
Pubblica | Riceve 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 senza wrapping con metadati di scrittura abilitati
L'esempio seguente mostra un messaggio non analizzato con l'opzione di scrittura dei metadati attivata. In questo caso, sono incluse le intestazioni x-goog-pubsub-*
e gli attributi dei messaggi.
Pubblica | Riceve 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"} |
Configurare l'annullamento del wrapping del payload
Puoi attivare il caricamento push di scomposizione del payload per un abbonamento utilizzando la pagina Dettagli 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 sottoscrizione, inserisci un nome.
Per informazioni su come assegnare un nome a un abbonamento, consulta le linee guida per assegnare un nome a un argomento o a un abbonamento.
Seleziona un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.
In Tipo di importazione, seleziona Push.
Per attivare l'annullamento del wrapping del payload, seleziona Attiva l'annullamento del wrapping del payload.
(Facoltativo) Per conservare i metadati dei messaggi nell'intestazione della richiesta, seleziona Scrivi metadati. Devi attivare questa opzione per impostare un'intestazione Content-Type per i tuoi messaggi.
Specifica un URL endpoint.
Mantieni invariati tutti gli altri valori predefiniti.
Fai clic su Crea.
gcloud
Per configurare un abbonamento con scomposizione del payload che include intestazioni HTTP standard, esegui il seguente 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 dell'abbonamento 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
: invia i dati del messaggio direttamente come corpo HTTP.
Per configurare un abbonamento con scomposizione del payload e controllare l'utilizzo degli intestazioni x-goog-pubsub-*
, esegui il seguente 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 true, scrive i metadati dei messaggi Pub/Sub nelle intestazionix-goog-pubsub-<KEY>:<VAL>
della richiesta HTTP. Scrive gli attributi del messaggio Pub/Sub nelle intestazioni<KEY>:<VAL>
della richiesta HTTP.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python riportate nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub per Python.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java riportate nella Guida rapida all'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 di configurazione C++ riportate nella guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go riportate nella guida rapida all'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 riportate nella Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js riportate nella Guida rapida all'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Pub/Sub Node.js.
Impostare un'intestazione Content-Type nel messaggio
Dopo aver attivato lo scollegamento del payload, Pub/Sub non imposta automaticamente un campo dell'intestazione del tipo di media nella richiesta. Se
non imposti esplicitamente un campo dell'intestazione Content-Type
, il server web
che elabora la tua richiesta potrebbe impostare un valore predefinito di
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 per ogni singolo messaggio pubblicato. Per farlo, devi prima attivare l'opzione Scrivere metadati. Questo risultato dell'attivazione di Scrivere metadati
è mostrato negli esempi forniti.
Passaggi successivi
- Se hai problemi con lo scollegamento del payload, consulta Risolvere i problemi di scollegamento del payload.