Pub/Sub システムを構築する際にペイロードのアンラップを行うと、標準の Pub/Sub プッシュ エンドポイント実装のすべてのシステム要件に準拠していない他のシステムに接続できます。
想定されるペイロードのラップ解除のユースケースには次のようなものがあります。
- HTTP push エンドポイントに Pub/Sub 固有のメッセージ解析コードを作成する必要はありません。
- HTTP POST 本文のメタデータではなく、HTTP ヘッダーとして Pub/Sub メッセージ メタデータを受信したい。
- たとえば、サードパーティ API にデータを送信する場合に、Pub/Sub メッセージを送信し、Pub/Sub メタデータを除外します。
ペイロードのラップ解除を行う方法
ペイロードのラップ解除は、メッセージ データを除くすべてのメッセージ メタデータを Pub/Sub メッセージから削除する機能です。未加工のメッセージ データを送信することで、サブスクライバーは Pub/Sub のシステム要件に準拠することなくメッセージを処理できます。
- ペイロードのアンラップでは、メッセージ データが HTTP 本文として直接配信されます。
- ペイロードのラップ解除を行わない場合、Pub/Sub は複数のメッセージ メタデータ フィールドとメッセージ データ フィールドを含む JSON オブジェクトを配信します。この場合、JSON を解析してメッセージ データを取得し、base64 でデコードする必要があります。
メタデータを書き込む
ペイロードのラップ解除を有効にすると、メタデータを書き込むオプションを使用できます。これにより、以前に削除したメッセージ メタデータをリクエスト ヘッダーに追加できます。
- メタデータの書き込みが有効。メッセージ メタデータをリクエスト ヘッダーに再度追加します。また、デコードされたメッセージのデータ(未加工)を配信します。
- メタデータの書き込みが無効になっています。デコードされたメッセージのデータ(未加工)のみを配信します。
書き込みメタデータは、Pub/Sub、Google Cloud CLI 引数 --push-no-wrapper-write-metadata、API プロパティ NoWrapper を介して公開されます。デフォルトでは、この値は null です。
準備
- Pub/Sub のサブスクリプションとプッシュ サブスクリプションについて学習する。ペイロードのラップ解除は、push サブスクリプションでのみ使用できます。
- プッシュ サブスクリプションを構成する方法を学習する。
ラップされたメッセージとラップされていないメッセージの例
次の例は、ラップされた HTTP メッセージとラップされていない HTTP メッセージを送信する場合の違いを示しています。これらの例では、メッセージ データに文字列 {"status": "Hello there"} が含まれています。
この例では、ペイロードのラップ解除機能を有効にしてサブスクリプションを作成し、mytopic にメッセージをパブリッシュします。値が some-key の順序キーを使用し、メディアタイプは application/json として宣言されます。
gcloud pubsub topics publish mytopic
--message='{"status": "Hello there"}'
--ordering-key="some-key"
--attribute "Content-Type=application/json"
以降のセクションでは、ラップされたメッセージとラップされていないメッセージの違いを示します。
折り返されたメッセージ
次の例は、標準の Pub/Sub ラップされたメッセージを示しています。この場合、ペイロードのラップ解除は有効になっていません。
| 公開 | プッシュ エンドポイントの受信 |
|---|---|
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/..."
} |
書き込みメタデータを無効にしたメッセージのラップ解除
次の例は、書き込みメタデータ オプションが無効になっているラップ解除されたメッセージを示しています。この場合、x-goog-pubsub-* ヘッダーとメッセージ属性は含まれません。
| 公開 | プッシュ エンドポイントの受信 |
|---|---|
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"} |
書き込みメタデータを有効にしたメッセージのラップ解除
次の例は、書き込みメタデータ オプションが有効になっているラップ解除されたメッセージを示しています。この場合、x-goog-pubsub-* ヘッダーとメッセージ属性が含まれます。
| 公開 | プッシュ エンドポイントの受信 |
|---|---|
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"} |
ペイロードのラップ解除を構成する
サブスクリプションに対してペイロードのラップ解除のプッシュ配信を有効にするには、 Google Cloud コンソールの [サブスクリプションの詳細] ページ、Google Cloud CLI、またはクライアント ライブラリを使用します。
コンソール
Google Cloud コンソールで、[サブスクリプション] ページに移動します。
[サブスクリプションを作成] をクリックします。
[サブスクリプション ID] フィールドに名前を入力します。
サブスクリプションの指定方法については、トピックまたはサブスクリプションの指定方法のガイドラインをご覧ください。
プルダウン メニューからトピックを選択します。サブスクリプションがトピックからメッセージを受信します。
[配信タイプ] で、[push] を選択します。
ペイロードのアンラッピングを有効にするには、[ペイロードのアンラッピングを有効にする] を選択します。
(省略可)リクエスト ヘッダーにメッセージのメタデータを保持するには、[メタデータを書き込む] を選択します。メッセージに Content-Type ヘッダーを設定するには、このオプションを有効にする必要があります。
エンドポイント URL を指定します。
他のすべてのデフォルト値は保持されます。
[作成] をクリックします。
gcloud
標準の HTTP ヘッダーを含むペイロードのアンラッピングでサブスクリプションを構成するには、次の gcloud pubsub subscriptions create コマンドを実行します。
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
以下を置き換えます。
SUBSCRIPTION: pull サブスクリプションの名前または ID。TOPIC: トピックの ID。PUSH_ENDPOINT: このサブスクリプションのエンドポイントとして使用する URL。例:https://myproject.appspot.com/myhandler--push-no-wrapper: メッセージ データを HTTP 本文として直接配信します。
ペイロードのアンラップを使用してサブスクリプションを構成し、x-goog-pubsub-* ヘッダーの使用を制御するには、次のコマンドを実行します。
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
--push-no-wrapper-write-metadata: true の場合、Pub/Sub メッセージのメタデータを HTTP リクエストのx-goog-pubsub-<KEY>:<VAL>ヘッダーに書き込みます。Pub/Sub メッセージ属性を HTTP リクエストの<KEY>:<VAL>ヘッダーに書き込みます。
Python
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Python の設定手順を実施してください。詳細については、Pub/Sub Python API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、Pub/Sub Java API のリファレンス ドキュメントをご覧ください。
C++
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の C++ の設定手順を実施してください。詳細については、Pub/Sub C++ API リファレンス ドキュメントをご覧ください。
Go
次のサンプルでは、Go Pub/Sub クライアント ライブラリのメジャー バージョン(v2)を使用しています。まだ v1 ライブラリを使用している場合は、v2 への移行ガイドをご覧ください。v1 コードサンプルの一覧については、 非推奨のコードサンプルをご覧ください。
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Go の設定手順を実施してください。詳細については、Pub/Sub Go API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、Pub/Sub Node.js API リファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、Pub/Sub Node.js API リファレンス ドキュメントをご覧ください。
メッセージにコンテンツ タイプのヘッダーを設定する
ペイロードのラップ解除を有効にしても、Pub/Sub はリクエストのメディアタイプ ヘッダー フィールドを自動的に設定しません。Content-Type ヘッダー フィールドを明示的に設定しない場合、リクエストを処理するウェブサーバーがデフォルト値の application/octet-stream を設定するか、予期しない方法でリクエストを解釈する場合があります。
Content-Type ヘッダーが必要な場合は、公開時に公開されるすべてのメッセージに対して明示的に宣言してください。これを行うには、まずメタデータの書き込みを有効にする必要があります。メタデータの書き込みを有効にした結果は、関連する例に示してあります。
次のステップ
- ペイロードのラップ解除で問題が発生した場合は、ペイロードのラップ解除のトラブルシューティングをご覧ください。