Quando crei il 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 standard dell'endpoint push Pub/Sub.
Di seguito sono riportati alcuni potenziali casi d'uso per l'unwrapping del payload:
- Non vuoi scrivere codice di analisi dei messaggi specifico di Pub/Sub per gli endpoint push HTTP.
- Preferisci ricevere i metadati dei messaggi Pub/Sub come intestazioni HTTP anziché nel corpo della richiesta HTTP POST.
- 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 tutti i metadati dei messaggi Pub/Sub, ad eccezione dei dati dei messaggi. Inviando dati dei messaggi non elaborati, gli abbonati possono elaborare il messaggio senza dover rispettare i requisiti di sistema di Pub/Sub.
- Con l'unwrapping del payload, i dati del messaggio vengono inviati direttamente come corpo HTTP.
- Senza l'annullamento del wrapping del payload, Pub/Sub fornisce un oggetto JSON che contiene più campi di metadati del messaggio e un campo di dati del messaggio. In questo caso, il 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 Scrivi metadati, che aggiunge i metadati del messaggio rimossi in precedenza all'intestazione della richiesta.
- Scrivi metadati abilitato. Aggiungi di nuovo i metadati del messaggio all'intestazione della richiesta. Invia anche i dati dei messaggi non elaborati e decodificati.
- Scrittura dei metadati disattivata. Invia solo i dati dei messaggi non elaborati e decodificati.
La scrittura dei metadati viene esposta 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ù sulle sottoscrizioni e sulle sottoscrizioni push di Pub/Sub. L'annullamento del wrapping del payload può essere utilizzato solo con le sottoscrizioni push.
- Scopri come configurare un abbonamento push.
Esempio di messaggi sottoposti a wrapping e non sottoposti a wrapping
I seguenti esempi illustrano la differenza tra l'invio di un messaggio HTTP sottoposto a wrapping e non sottoposto a 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 unwrap del payload abilitata e viene pubblicato un messaggio in mytopic. Utilizza una chiave di ordinamento
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 sottoposto a wrapping e uno non sottoposto a wrapping.
Messaggio a capo
L'esempio seguente mostra un messaggio Pub/Sub standard sottoposto a wrapping. In questo caso, l'annullamento del wrapping del payload non è abilitato.
| Pubblica | Push Endpoint Receives |
|---|---|
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 senza wrapping con scrittura dei metadati disattivata
L'esempio seguente mostra un messaggio non sottoposto a wrapping con l'opzione Scrivi metadati
disattivata. In questo caso, le intestazioni x-goog-pubsub-* e gli attributi del messaggio
non sono inclusi.
| Pubblica | 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 senza wrapping con la scrittura dei metadati abilitata
L'esempio seguente mostra un messaggio non sottoposto a wrapping con l'opzione Scrivi metadati
attivata. In questo caso, sono incluse le intestazioni x-goog-pubsub-* e gli attributi del messaggio.
| Pubblica | 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 attivare la distribuzione push di unwrapping del payload per un abbonamento utilizzando la console Cloud de Confiance , la pagina Dettagli abbonamento, Google Cloud CLI o le librerie client.
Console
Nella console Cloud de Confiance , vai alla pagina Sottoscrizioni.
Fai clic su Crea sottoscrizione.
Nel campo ID sottoscrizione, inserisci un nome.
Per informazioni su come denominare 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 consegna, seleziona Push.
Per abilitare 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 un URL endpoint.
Mantieni tutti gli altri valori predefiniti.
Fai clic su Crea.
gcloud
Per configurare un abbonamento con il decrittaggio 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 della 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: invia i dati del messaggio direttamente come corpo HTTP.
Per configurare un abbonamento con l'unwrapping del payload e controllare l'utilizzo degli
header 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 del messaggio Pub/Sub nelle intestazioni della richiesta HTTP.x-goog-pubsub-<KEY>:<VAL>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 nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub Python.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java di Pub/Sub.
C++
Prima di provare questo esempio, segui le istruzioni di configurazione di C++ nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub C++.
Go
L'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice deprecati.
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida all'utilizzo delle librerie client. Per saperne di più, 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 nella guida rapida all'utilizzo delle librerie client. Per saperne di più, 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 nella guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Node.js Pub/Sub.
Impostare un'intestazione Content-Type nel messaggio
Dopo aver attivato l'unwrapping del payload, Pub/Sub non
imposta automaticamente un campo di intestazione del tipo di media nella richiesta. Se non imposti esplicitamente un campo di 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 è necessaria 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'attivazione di Scrivi metadati
è mostrato negli esempi forniti.
Passaggi successivi
- Se hai problemi con l'unwrapping del payload, consulta la pagina Risolvere i problemi relativi all'unwrapping del payload.