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 ポリシーを実行するには、認証トークンが必要です。ただし、ポリシー定義に明示的な <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 変数を設定しません。この変数にアクセスすると、エラーが発生します。

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

エラーコード

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラーメッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。

ランタイムエラー

このエラーは、ポリシーの実行時に発生することがあります。

障害コード	HTTP ステータス	原因
`steps.publishmessage.PermissionDeniedError`	`500`	このエラーは、ランタイムサービスアカウントがプロキシサービスアカウントの権限を借用できないか、プロキシサービスアカウントにトピックへのパブリッシュ権限がない場合に発生します。
`steps.publishmessage.ExecutionError`	`500`	このエラーは、Pub/Sub へのメッセージのパブリッシュ中に予期しないエラーが発生した場合に発生します。エラーの詳細はエラーメッセージで確認できます。
`steps.publishmessage.MessageVariableNotMessageType`	`500`	このエラーは、`UseMessageAsSource` で指定した変数名を解決できない場合、またはその変数名がメッセージ型でない場合に発生します。

障害変数

ポリシーで実行エラーが発生すると、Apigee によってエラーメッセージが生成されます。これらのエラーメッセージはエラーレスポンスで確認できます。多くの場合、システムによって生成されたエラーメッセージは、製品のコンテキストとは関係ありません。エラーのタイプに基づいてエラーメッセージをカスタマイズして、より有用なメッセージにすることができます。

エラーメッセージをカスタマイズするには、障害ルールまたは RaiseFault ポリシーを使用します。障害ルールと RaiseFault ポリシーの違いについては、FaultRule ポリシーと RaiseFault ポリシーをご覧ください。障害ルールと RaiseFault ポリシーの両方で Condition 要素を使用して条件を確認する必要があります。Apigee では、各ポリシーに固有の障害変数が用意されています。障害変数の値は、ポリシーがランタイムエラーをトリガーするときに設定されます。これらの変数を使用することで、特定のエラー条件を確認し、適切なアクションを実行できます。エラー条件の確認について詳しくは、条件の作成をご覧ください。

変数	説明	例
`fault.name`	`fault.name` は、ランタイムエラーの表にある障害のいずれかに一致します。障害名は、障害コードの最後の部分です。	`fault.name Matches "UnresolvedVariable"`
`publishmessage.POLICY_NAME.failed`	`POLICY_NAME` は、障害が発生したポリシーのユーザー指定の名前です。	`publishmessage.publish-message-1.failed = true`

ポリシーエラーの詳細については、ポリシーエラーについて知っておくべきことをご覧ください。

PublishMessage ポリシー コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

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

<PublishMessage>

構文

例 - ソース

例 - UseMessageAsSource

例 - 属性

子要素のリファレンス

<Attributes>

構文

例 1

例 2

<DisplayName>

構文

例

<Source>

構文

例 1

例 2

<CloudPubSub>

構文

例

<Topic>

構文

例

<UseMessageAsSource>

構文

例 1

<IgnoreUnresolvedVariables>

構文

例