Pub/Sub システムを構築する場合、ペイロードのラップ解除を使用すると、標準の Pub/Sub push エンドポイント実装のすべてのシステム要件を遵守していない他のシステムに接続できます。
想定されるペイロードのラップ解除のユースケースには次のようなものがあります。
- 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 サブスクリプションでのみ使用できます。
- 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 ラップ メッセージの例です。この場合、ペイロードのラップ解除は有効になりません。
公開 | 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/..." } |
書き込みメタデータが無効になっているメッセージのラップ解除
次の例は、メタデータの書き込みオプションを無効にした、ラップ解除されたメッセージを示しています。この場合、x-goog-pubsub-*
ヘッダーとメッセージ属性は含まれません。
公開 | 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"} |
書き込みメタデータを有効にしたメッセージのラップ解除
次の例は、書き込みメタデータ オプションが有効になっているアンラップされたメッセージを示しています。この場合、x-goog-pubsub-*
ヘッダーとメッセージ属性が含まれます。
公開 | 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"} |
ペイロードのラップ解除を構成する
サブスクリプションのペイロードのラップ解除の push 配信を有効にするには、Google Cloud コンソールの [サブスクリプションの詳細] ページ、Google Cloud CLI、またはクライアント ライブラリを使用します。
Console
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 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
ヘッダーが必要な場合は、公開時に公開されるすべてのメッセージに対して明示的に宣言してください。これを行うには、まずメタデータの書き込みを有効にする必要があります。メタデータの書き込みを有効にした結果は、関連する例に示してあります。
次のステップ
- ペイロードのラップ解除に問題がある場合は、ペイロードのラップ解除のトラブルシューティングをご覧ください。