PublishMessage 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

總覽

您可以使用 PublishMessage 政策，將 API Proxy 流程資訊發布至 Google Cloud Pub/Sub 主題。Google 的 Pub/Sub 服務可讓服務以非同步方式通訊，延遲時間大幅縮短。如要進一步瞭解 Pub/Sub，請參閱「什麼是 Pub/Sub？」一文。 您要發布至 Pub/Sub 主題的資訊可以是字面文字或流程變數。您也可以使用訊息範本，指定字面文字和流程變數的組合。

如果發布要求成功，Apigee 會將 publishmessage.message.id 流程變數設為 Pub/Sub 伺服器傳回的值。詳情請參閱「流程變數」。

這項政策屬於標準政策，可部署至任何環境類型。如要瞭解各環境類型適用的政策類型和可用性，請參閱「政策類型」。

注意：

• 您可以使用 PublishMessage 政策，將訊息發布到單一主題。如要將訊息發布到多個主題，請使用多個 PublishMessage 政策 (每個主題各一項政策)。
• 如要執行 PublishMessage 政策，您應為 Google Cloud 專案啟用 Pub/Sub API。如要進一步瞭解如何為 Google Cloud 專案啟用 API，請參閱「啟用及停用服務」一文。

驗證和 Proxy 部署

如要執行 PublishMessage 政策，您需要驗證權杖。不過，政策定義中沒有明確的 <Authentication> 元素。您必須部署 API 代理，才能使用 Google 驗證，這會在幕後將驗證權杖新增至要求。如要瞭解如何部署使用 Google 驗證的 API Proxy，請參閱部署步驟。 除了在 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 個半形字元。 您可以選擇使用 <DisplayName> 元素，在管理 UI 代理程式編輯器中為政策加上不同、自然語言的名稱。
continueOnError	false	選用	將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱： 錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤
enabled	是	選用	設為 true 即可強制執行政策。設為 false 即可關閉政策。即使政策仍附加至流程，系統也不會強制執行這項政策。
async	false	已淘汰	此屬性已淘汰。

子元素參照

本節說明 <PublishMessage> 的子元素。

<Attributes>

指定要附加至 Pub/Sub 訊息的屬性。

每個屬性都是鍵/值組合。與屬性相關聯的名稱不得重複。 每個值都是在執行階段透過訊息範本動態決定。

預設值	不適用
必填與否	必填
類型	字串
父項元素	<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>

Example-1

以下範例會將來源訊息設為 flow-var-1 流程變數的值：

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

Example-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> 的父項元素。

您只能發布至一個 Pub/Sub 主題。因此，<CloudPubSub> 元素中只能有一個 <Topic> 元素。

預設值	不適用
必填與否	必填
類型	複雜型別
父項元素	<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>

Example-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 遇到無法解析的變數時，是否要停止處理程序。

預設值	否
必填與否	選用
類型	布林值
父項元素	<PublishMessage>
子元素	無

將值設為 true 可忽略未解析的變數並繼續處理；否則請設為 false。預設值為 false。

將 <IgnoreUnresolvedVariables> 設為 true 與將 <PublishMessage> 的 continueOnError 設為 true 不同。如果將 continueOnError 設為 true，Apigee 會忽略所有錯誤，而不只是變數中的錯誤。

<IgnoreUnresolvedVariables> 元素使用下列語法：

語法

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

範例

以下範例將 <IgnoreUnresolvedVariables> 設為 true：

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

流程變數

流程變數是保存特定資料的物件，可在 API Proxy 流程的環境中使用。這些變數會儲存酬載資訊、網址路徑、IP 位址和政策執行資料等資訊。如要進一步瞭解流程變數，請參閱「使用流程變數」。

如果 PublishMessage 政策成功發布至 Pub/Sub 主題，Apigee 會將 publishmessage.message.id 流程變數設為 Pub/Sub 伺服器傳回的 messageId。流程變數的類型為字串，且您可從 Proxy 要求流程開始使用該變數。您可以視需求在其他下游政策中使用流程變數。不過，如果發布失敗，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