本頁適用於 Apigee 和 Apigee Hybrid。
查看
Apigee Edge 說明文件。
總覽
您可以使用 PublishMessage 政策，將 API 代理程式流程資訊發布至 Google Cloud Pub/Sub 主題。Google Pub/Sub 可讓服務以非同步方式通訊，且延遲時間大幅縮短。如要進一步瞭解 Pub/Sub，請參閱「什麼是 Pub/Sub？」。您要發布至 Pub/Sub 主題的資訊可以是文字值或流程變數。您也可以使用訊息範本，指定文字文字和流程變數的組合。
如果發布要求成功，Apigee 會將 publishmessage.message.id 流程變數設為 Pub/Sub 伺服器傳回的值。詳情請參閱「流程變數」。
這項政策是標準政策，可部署至任何環境類型。如要瞭解政策類型和各環境類型的可用性，請參閱「政策類型」。
驗證和 Proxy 部署
如要執行「PublishMessage」政策，您需要提供驗證權杖。不過，政策定義中並未明確提供 <Authentication> 元素。您必須部署 API 代理才能使用 Google 驗證，這會在幕後將驗證權杖新增至要求。如要瞭解如何部署使用 Google 驗證機制的 API Proxy，請參閱「部署步驟」。除了在 API 代理程式中使用 Google 驗證機制外，您必須使用具有 pubsub.topics.publish 權限的角色，透過服務帳戶部署 API 代理程式。如要進一步瞭解 Pub/Sub 的 Identity and Access Management (IAM) 角色，請參閱「權限和角色」一文。
<PublishMessage>
指定 PublishMessage 政策。
| 預設值 | 不適用 |
| 是否必要？ | 必填 |
| 類型 | 複雜類型 |
| 上層元素 | N/A |
| 子元素 |
<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 |
不適用 | 必要 |
政策的內部名稱。 您可以選擇使用 |
continueOnError |
false | 選用 | 將其設為 false，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 true，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：
|
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>
流程變數
Flow 變數是用於儲存特定資料的物件，可在 API Proxy 流程中使用。這些變數會儲存酬載資訊、網址路徑、IP 位址，以及政策執行結果的資料。如要進一步瞭解流程變數，請參閱「使用流程變數」。
如果 PublishMessage 政策成功發布至 Pub/Sub 主題，Apigee 會將 publishmessage.message.id 流程變數設為 Pub/Sub 伺服器傳回的 messageId。流程變數的類型為字串，且您可以在 Proxy 要求流程之後使用該變數。您可以根據需求，在其他下游政策中使用流程變數。不過，如果發布失敗，Apigee 就不會設定 publishmessage.message.id 變數，因此存取這個變數會導致錯誤。
如要進一步瞭解各種類型的流程變數，請參閱「流程變數參考資料」。
錯誤代碼
本節說明這項政策觸發錯誤時，Apigee 傳回的錯誤代碼和錯誤訊息，以及 Apigee 設定的錯誤變數。如果您要開發錯誤處理規則，就必須瞭解這項資訊。如需更多資訊，請參閱「關於政策錯誤的相關資訊」和「處理錯誤」。
執行階段錯誤
政策執行時可能會發生這些錯誤。
| 錯誤代碼 | HTTP 狀態 | 原因 |
|---|---|---|
steps.publishmessage.PermissionDeniedError |
500 |
如果執行階段服務帳戶無法模擬 Proxy 服務帳戶，或是 Proxy 服務帳戶沒有發布至主題的權限，就會發生這項錯誤。 |
steps.publishmessage.ExecutionError |
500 |
如果在將訊息發布至 Pub/Sub 時發生非預期錯誤，就會發生這個錯誤。您可以在錯誤訊息中查看錯誤詳細資料。 |
steps.publishmessage.MessageVariableNotMessageType |
500 |
如果您在 UseMessageAsSource 中指定的變數名稱無法解析，或不是訊息類型，就會發生這個錯誤。 |
錯誤變數
每當政策發生執行錯誤時，Apigee 就會產生錯誤訊息。您可以在錯誤回應中查看這些錯誤訊息。很多時候，系統產生的錯誤訊息在產品情境中可能不相關。您可能會根據錯誤類型自訂錯誤訊息，讓訊息更有意義。
如要自訂錯誤訊息，您可以使用錯誤規則或 RaiseFault 政策。如要瞭解錯誤規則與 RaiseFault 政策的差異，請參閱「FaultRules 與 RaiseFault 政策」。您必須在錯誤規則和 RaiseFault 政策中，使用 Condition 元素檢查條件。Apigee 會提供每項政策專屬的錯誤變數，而錯誤變數的值會在政策觸發執行階段錯誤時設定。您可以使用這些變數，檢查特定錯誤情況並採取適當行動。如要進一步瞭解如何檢查錯誤條件，請參閱「建構條件」。
| 變數 | 地點 | 範例 |
|---|---|---|
fault.name |
fault.name 可與「執行階段錯誤」表格中列出的任何錯誤相符。
錯誤名稱是錯誤代碼的最後一個部分。 |
fault.name Matches "UnresolvedVariable" |
publishmessage.POLICY_NAME.failed |
POLICY_NAME 是擲回錯誤的政策的使用者指定名稱。 | publishmessage.publish-message-1.failed = true |