PublishMessage ポリシー

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge のドキュメントを表示する。

概要

PublishMessage ポリシーを使用すると、API プロキシフロー情報を Google Cloud Pub/Sub トピックにパブリッシュできます。Google の Pub/Sub により、サービスが非同期に通信でき、レイテンシが大幅に短縮されます。Pub/Sub の詳細については、Pub/Sub とはをご覧ください。Pub/Sub トピックにパブリッシュする情報には、リテラル テキストまたはフロー変数を使用できます。メッセージ テンプレートを使用して、リテラル テキストとフロー変数の組み合わせを指定することもできます。

パブリッシュ リクエストが成功すると、Apigee は publishmessage.message.id フロー変数を Pub/Sub サーバーによって返された値に設定します。詳細については、フロー変数をご覧ください。

このポリシーは、標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシータイプと各環境タイプで使用可能かどうかは、ポリシータイプをご覧ください。

注:

• PublishMessage ポリシーを使用して、1 つのトピックにのみメッセージをパブリッシュできます。メッセージを複数のトピックにパブリッシュする場合は、複数の PublishMessage ポリシーを使用します（トピックごとに 1 つのポリシー）。
• PublishMessage ポリシーを実行するには、Google Cloud プロジェクトで Pub/Sub API を有効にする必要があります。Google Cloud プロジェクトの API を有効にする方法については、サービスの有効化と無効化をご覧ください。

認証とプロキシのデプロイ

PublishMessage ポリシーを実行するには、認証トークンが必要です。ただし、ポリシー定義に明示的な <Authentication> 要素はありません。Google 認証を使用するには API プロキシをデプロイする必要があります。これにより、リクエストに内部的に認証トークンが追加されます。Google 認証を使用する API プロキシをデプロイする方法については、デプロイ手順をご覧ください。API プロキシで Google 認証を使用する以外に、pubsub.topics.publish 権限を持つロールを持つサービス アカウントを使用して API プロキシをデプロイする必要があります。Pub/Sub の Identity and Access Management（IAM）のロールの詳細については、権限とロールをご覧ください。

<PublishMessage>

PublishMessage ポリシーを指定します。

デフォルト値	なし
必須かどうか	必須
型	複合型
親要素	なし
子要素	<Attributes> <CloudPubSub> <DisplayName> <IgnoreUnresolvedVariables> <Source> <UseMessageAsSource>

次の表は、<PublishMessage> の子要素の概要をまとめたものです。

子要素	必須かどうか	説明
<Attributes>	オプション	Pub/Sub メッセージに適用する一連の属性。
<CloudPubSub>	必須	<Topic> の親要素。<Topic> 要素は、メッセージをパブリッシュする Pub/Sub トピックを指定します。
<DisplayName>	オプション	ポリシーのカスタム名。
<IgnoreUnresolvedVariables>	オプション	Apigee が未解決の変数を検出した場合に、処理を停止するかどうかを指定します。
<Source>	オプション	Pub/Sub トピックにパブリッシュするメッセージを指定します。この要素は省略可能ですが、<Source> または <UseMessageAsSource> のいずれかを使用する必要があります。
<UseMessageAsSource>	オプション	Pub/Sub トピックにパブリッシュするメッセージを指定します。この要素は省略可能ですが、<Source> または <UseMessageAsSource> のいずれかを使用する必要があります。
その他の子要素
<Topic>	必須	<CloudPubSub> の子要素。メッセージのパブリッシュ先の Pub/Sub トピックを指定します。

<PublishMessage> 要素の構文は次のとおりです。

構文

<PublishMessage continueOnError="[true|false]" enabled="[true|false]" name="Publish-Message-1">
    <DisplayName>DISPLAY_NAME</DisplayName>
    <Source>SOURCE_VALUE</Source>
    <CloudPubSub>
        <Topic>TOPIC_NAME</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>
</PublishMessage>

例 - ソース

次の例は、<PublishMessage> ポリシーの定義を示しています。

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>this is a message template {flow-variable1}</Source>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

例 - UseMessageAsSource

この <PublishMessage> ポリシーでは、UseMessageAsSource 要素を指定します。

<PublishMessage continueOnError="false" enabled="true" name="Publish-Message-2">
    <UseMessageAsSource>request</UseMessageAsSource>
    <CloudPubSub>
        <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
    </CloudPubSub>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

例 - 属性

この <PublishMessage> ポリシーでは、Attributes 要素を指定します。

<PublishMessage name="Publish-Message-3">
  <Source>this is a message template {flow-variable1}</Source>
  <Attributes>
    <Attribute name='attr-name-0'>fixed-value</Attribute>
    <Attribute name='another-attribute-name'>{request.queryparam.attr1}</Attribute>
    <Attribute name='a-third-attribute-name'>{request.queryparam.attr2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flow-variable-project-id}/topics/{flow-variable-topic-name}</Topic>
  </CloudPubSub>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</PublishMessage>

この要素には、すべてのポリシーに共通する次の属性があります。

属性	デフォルト	必須かどうか	説明
name	なし	必須	ポリシーの内部名。name 属性の値には、英字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。この値は 255 文字を超えることはできません。 管理 UI プロキシ エディタで <DisplayName> 要素を追加して、ポリシーのラベルに使用する別の自然言語名を指定することもできます。
continueOnError	false	省略可	ポリシーが失敗したときにエラーを返す場合は、false に設定します。これは、ほとんどのポリシーで想定される動作です。ポリシーが失敗した後もフローの実行を続行する場合は、true に設定します。関連情報: 障害ルールはエラー状態の場合にのみトリガーされる（continueOnError について） 現在のフローにおける障害処理
enabled	true	省略可	ポリシーを適用するには、true に設定します。ポリシーを無効にするには、false に設定します。ポリシーがフローに接続されている場合でも適用されません。
async	false	非推奨	この属性は非推奨となりました。

子要素のリファレンス

このセクションでは、<PublishMessage> の子要素について説明します。

<Attributes>

Pub/Sub メッセージに適用する属性を指定します。

各属性は Key-Value ペアです。属性に関連付けられた名前は一意である必要があります。各値は、メッセージ テンプレートを介して実行時に動的に決定されます。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素	<PublishMessage>
子要素	なし

<Attributes> 要素の構文は次のとおりです。

構文

  <Attributes>
    <Attribute name='NAME-1'>fixed-value</Attribute>
    <Attribute name='NAME-2'>{flow-variable}</Attribute>
    ...
    <Attribute name='NAME-N'>message template here {flow-variable:default-value}</Attribute>
  </Attributes>

例 1

次の例では、パブリッシュ時に、固定値を持つ単一の属性をメッセージに設定します。

<PublishMessage name="PM-with-one-attribute">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{request.queryparam.message}</Source>
  <Attributes>
    <Attribute name='my-attribute-1'>fixed-value</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{request.queryparam.project}/topics/{request.queryparam.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

例 2

次の例では、パブリッシュ時に、メッセージに複数の属性を設定します。一部の属性の値は、実行時に動的に決定されます。

<PublishMessage name="PM-with-multiple-attributes">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Source>{my-assembled-message}</Source>
  <Attributes>
    <Attribute name='attr-0'>fixed-value</Attribute>
    <Attribute name='attr-1'>{flow-variable1}</Attribute>
    <Attribute name='attr-2'>fixed portion {flow-variable2:default-value}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

<DisplayName>

name 属性に加えて、管理 UI プロキシ エディタでポリシーを別の、より自然な響きの名前でラベル付けするために使います。

<DisplayName> 要素はすべてのポリシーに共通です。

デフォルト値	なし
必須かどうか	省略可。<DisplayName> を省略した場合、ポリシーの name 属性の値が使用されます。
型	文字列
親要素	<PolicyElement>
子要素	なし

<DisplayName> 要素の構文は次のとおりです。

構文

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

例

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 要素に属性や子要素はありません。

<Source>

パブリッシュするメッセージを指定します。

メッセージには、リテラル テキストやフロー変数を使用することも、メッセージ テンプレートで両方の組み合わせを使用することもできます。

デフォルト値	なし
必須かどうか	オプション
型	文字列
親要素	<PublishMessage>
子要素	なし

<Source> 要素の構文は次のとおりです。

構文

 <Source>SOURCE</Source>

例 1

次の例では、ソース メッセージを flow-var-1 フロー変数の値に設定しています。

<Source>{flow-var-1}</Source>

例 2

次の例では、メッセージ テンプレートを使用して、動的コンテンツを含む JSON メッセージをパブリッシュします。

<PublishMessage name="PM-with-source-template">
  <Source>{
    "name": "value-1",
    "count": "{flow-variable1}",
    "action": "{flow-variable2}"
  }</Source>
  <Attributes>
    <Attribute name='content-type'>application/json</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

<CloudPubSub>

<Topic> の親要素。

1 つの Pub/Sub トピックにのみパブリッシュできます。そのため、<CloudPubSub> 要素に含めることができる <Topic> 要素は 1 つだけです。

デフォルト値	なし
必須かどうか	必須
型	複合型
親要素	<PublishMessage>
子要素	<Topic>

<CloudPubSub> 要素の構文は次のとおりです。

構文

<CloudPubSub>
  <Topic>TOPIC_NAME</Topic>
</CloudPubSub>

例

次の例は、<CloudPubSub> 要素の宣言を示しています。

<CloudPubSub>
  <Topic>projects/{my-project}/topics/{my-topic}</Topic>
</CloudPubSub>

<Topic>

<Source> メッセージをパブリッシュする Pub/Sub トピックを指定します。

トピック名は projects/project-id/topics/topic-name 形式で指定する必要があります。

デフォルト値	なし
必須かどうか	必須
型	文字列
親要素	<CloudPubSub>
子要素	なし

<Topic> 要素の構文は次のとおりです。

構文

<Topic>TOPIC_NAME</Topic>

例

次の例では、パブリッシュ先の Pub/Sub トピックを指定しています。

<Topic>projects/project-id-marketing/topics/topic-name-test1</Topic>

この例では、project-id-marketing は Google Cloud プロジェクト ID で、topic-name-test1 は メッセージがパブリッシュされるトピックです。

<UseMessageAsSource>

パブリッシュするメッセージを指定します。

<Source> 要素の代わりに使用します。値は、メッセージを参照するフロー変数の名前（request、response、message など）にする必要があります。この要素を指定すると、ポリシーはパブリッシュするメッセージとしてメッセージの内容を使用します。メッセージ コンテンツが文字列として表せないオクテット ストリーム（バイナリ ファイルのコンテンツなど）の場合は、<Source> ではなくこの要素を使用する必要があります。

デフォルト値	なし
必須かどうか	オプション
型	文字列
親要素	<PublishMessage>
子要素	なし

<UseMessageAsSource> 要素の構文は次のとおりです。

構文

<PublishMessage name="PM-with-use-message-as-source">
  <UseMessageAsSource>MESSAGE_NAME</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{flowvar1}/topics/{flowvar-topic}</Topic>
  </CloudPubSub>
</PublishMessage>

例 1

次の例では、リクエスト メッセージの内容を Pub/Sub メッセージのペイロードとして使用するようにポリシーに指示します。

<PublishMessage name="PM-with-use-message-as-source">
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <UseMessageAsSource>request</UseMessageAsSource>
  <Attributes>
    <Attribute name='attr-1'>{flowvar1}</Attribute>
  </Attributes>
  <CloudPubSub>
    <Topic>projects/{propertyset.settings.project}/topics/{propertyset.settings.topic}</Topic>
  </CloudPubSub>
</PublishMessage>

<IgnoreUnresolvedVariables>

Apigee が未解決の変数を検出した場合に、処理を停止するかどうかを指定します。

デフォルト値	False
必須かどうか	オプション
型	ブール値
親要素	<PublishMessage>
子要素	なし

未解決の変数を無視して処理を続行するには、値を true に設定します。それ以外の場合は false に設定します。デフォルト値は false です。

<IgnoreUnresolvedVariables> を true に設定することは、<PublishMessage> の continueOnError を true に設定することとは異なります。continueOnError を true に設定すると、変数のエラーだけでなく、すべてのエラーが無視されます。

<IgnoreUnresolvedVariables> 要素の構文は次のとおりです。

構文

<IgnoreUnresolvedVariables>[true|false]</IgnoreUnresolvedVariables>

例

次の例では、<IgnoreUnresolvedVariables> を true に設定します。

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

フロー変数

フロー変数は、特定のデータを保持するオブジェクトで、API プロキシフローのコンテキストで使用できます。これらの変数には、ペイロード情報、URL パス、IP アドレス、ポリシー実行のデータなどの情報が保持されます。フロー変数の詳細については、フロー変数の使用をご覧ください。

PublishMessage ポリシーが正常に Pub/Sub トピックにパブリッシュされると、Apigee は publishmessage.message.id フロー変数を Pub/Sub サーバーによって返された messageId に設定します。フロー変数は string 型で、プロキシ リクエスト フロー以降で使用できます。必要に応じて、他のダウンストリーム ポリシーでフロー変数を使用できます。ただし、パブリッシュが失敗した場合、Apigee は publishmessage.message.id 変数を設定しません。この変数にアクセスすると、エラーが発生します。

さまざまなタイプのフロー変数の詳細については、フロー変数のリファレンスをご覧ください。

エラーコード

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.publishmessage.PermissionDeniedError	500	This error occurs when the runtime service account cannot impersonate the proxy service account or the proxy service account does not have the permission to publish to the topic.
steps.publishmessage.ExecutionError	500	This error occurs if there was an unexpected error while publishing the message to Pub/Sub. You can view the details of the error in the error message.
steps.publishmessage.MessageVariableNotMessageType	500	This error occurs if the variable name you specified in UseMessageAsSource cannot be resolved, or is not a message type.

Fault variables

Whenever there are execution errors in a policy, Apigee generates error messages. You can view these error messages in the error response. Many a time, system generated error messages might not be relevant in the context of your product. You might want to customize the error messages based on the type of error to make the messages more meaningful.

To customize the error messages, you can use either fault rules or the RaiseFault policy. For information about differences between fault rules and the RaiseFault policy, see FaultRules vs. the RaiseFault policy. You must check for conditions using the Condition element in both the fault rules and the RaiseFault policy. Apigee provides fault variables unique to each policy and the values of the fault variables are set when a policy triggers runtime errors. By using these variables, you can check for specific error conditions and take appropriate actions. For more information about checking error conditions, see Building conditions.

Variables	Where	Example
fault.name	The fault.name can match to any of the faults listed in the Runtime errors table. The fault name is the last part of the fault code.	fault.name Matches "UnresolvedVariable"
publishmessage.POLICY_NAME.failed	POLICY_NAME is the user-specified name of the policy that threw the fault.	publishmessage.publish-message-1.failed = true

For more information about policy errors, see What you need to know about policy errors