PublishMessage-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Übersicht

Mit der PublishMessage-Richtlinie können Sie Informationen zum API-Proxy-Ablauf in einem Google Cloud Pub/Sub-Thema veröffentlichen. Pub/Sub von Google ermöglicht Diensten eine asynchrone Kommunikation mit deutlich geringerer Latenz. Weitere Informationen zu Pub/Sub finden Sie unter Was ist Pub/Sub? Die Informationen, die Sie in einem Pub/Sub-Thema veröffentlichen möchten, können ein Literaltext oder eine Ablaufvariable sein. Sie können auch eine Kombination aus Literaltext und Ablaufvariablen mithilfe einer Nachrichtenvorlage angeben.

Wenn die Veröffentlichungsanfrage erfolgreich ist, setzt Apigee die Ablaufvariable publishmessage.message.id auf den vom Pub/Sub-Server zurückgegebenen Wert. Weitere Informationen finden Sie unter Ablaufvariablen.

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

Hinweis:

• Sie können eine Nachricht mit der PublishMessage-Richtlinie nur zu einem Thema veröffentlichen. Verwenden Sie mehrere PublishMessage-Richtlinien (eine Richtlinie für jedes Thema), wenn Sie eine Nachricht zu mehreren Themen veröffentlichen möchten.
• Zum Ausführen der PublishMessage-Richtlinie sollten Sie die Pub/Sub APIs für Ihr Google Cloud-Projekt aktivieren. Weitere Informationen zum Aktivieren von APIs für ein Google Cloud-Projekt finden Sie unter Dienste aktivieren und deaktivieren.

Authentifizierung und Proxybereitstellung

Zum Ausführen der PublishMessage-Richtlinie benötigen Sie ein Authentifizierungstoken. Es gibt jedoch kein explizites <Authentication>-Element in der Richtliniendefinition. Sie müssen Ihren API-Proxy zur Verwendung der Google-Authentifizierung bereitstellen, der das Authentifizierungstoken intern zur Anfrage hinzufügt. Informationen zum Bereitstellen eines API-Proxys, der Google-Authentifizierung verwendet, finden Sie unter Bereitstellungsschritte. Neben der Verwendung der Google-Authentifizierung in Ihrem API-Proxy müssen Sie Ihren API-Proxy mit einem Dienstkonto bereitstellen, das eine Rolle mit der Berechtigung pubsub.topics.publish hat. Weitere Informationen zu IAM-Rollen (Identity and Access Management) für Pub/Sub finden Sie unter Berechtigungen und Rollen.

<PublishMessage>

Gibt die PublishMessage-Richtlinie an.

Standardwert	–
Erforderlich?	Erforderlich
Typ	Komplexer Typ
Übergeordnetes Element	–
Untergeordnete Elemente	<Attributes> <CloudPubSub> <DisplayName> <IgnoreUnresolvedVariables> <Source> <UseMessageAsSource>

Die folgende Tabelle enthält eine allgemeine Beschreibung der untergeordneten Elemente von <PublishMessage>:

Untergeordnetes Element	Erforderlich?	Beschreibung
<Attributes>	Optional	Eine Reihe von Attributen, die an die Pub/Sub-Nachricht angehängt werden sollen.
<CloudPubSub>	Erforderlich	Übergeordnetes Element von <Topic>. Das Element <Topic> gibt das Pub/Sub-Thema an, in dem Sie Ihre Nachricht veröffentlichen möchten.
<DisplayName>	Optional	Ein benutzerdefinierter Name für die Richtlinie.
<IgnoreUnresolvedVariables>	Optional	Gibt an, ob die Verarbeitung beendet wird, wenn Apigee auf eine nicht aufgelöste Variable stößt.
<Source>	Optional	Gibt die Nachricht an, die im Pub/Sub-Thema veröffentlicht werden soll. Dieses Element ist optional, aber Sie müssen entweder <Source> oder <UseMessageAsSource> verwenden.
<UseMessageAsSource>	Optional	Gibt die Nachricht an, die im Pub/Sub-Thema veröffentlicht werden soll. Dieses Element ist optional, aber Sie müssen entweder <Source> oder <UseMessageAsSource> verwenden.
Weitere untergeordnete Elemente
<Topic>	Erforderlich	Ein untergeordnetes Element von <CloudPubSub>. Gibt das Pub/Sub-Thema an, in dem Sie die Nachricht veröffentlichen möchten.

Das Element <PublishMessage> verwendet die folgende Syntax:

Syntax

<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>

Beispiel – Quelle

Das folgende Beispiel zeigt die Definition der <PublishMessage>-Richtlinie:

<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>

Beispiel – UseMessageAsSource

In dieser <PublishMessage>-Richtlinie wird das UseMessageAsSource-Element angegeben:

<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>

Beispiel – Attribute

In dieser <PublishMessage>-Richtlinie wird das Attributes-Element angegeben:

<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>

Dieses Element hat folgende Attribute, die allen Richtlinien gemeinsam sind:

Attribut	Standard	Erforderlich?	Beschreibung
name	-	Erforderlich	Der interne Name der Richtlinie. Der Wert des Attributs name kann Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche und Punkte enthalten. Dieser Wert darf 255 Zeichen nicht überschreiten. Optional können Sie das Element <DisplayName> verwenden, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen Namen in einer natürlichen Sprache zu versehen.
continueOnError	false	Optional	Legen Sie false fest, um einen Fehler zurückzugeben, wenn eine Richtlinie fehlschlägt. Dies ist für die meisten Richtlinien das erwartete Verhalten. Legen Sie true fest, damit die Ablaufausführung auch nach dem Fehlschlagen einer Richtlinie fortgesetzt wird. Weitere Informationen: Fehlerregeln werden NUR im Fehlerzustand ausgelöst (über continueOnError) Umgang mit Fehlern im aktuellen Ablauf
enabled	wahr	Optional	Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen. Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht durchgesetzt, selbst wenn sie mit einem Ablauf verknüpft ist.
async	false	Verworfen	Dieses Attribut wurde verworfen.

Verweis auf untergeordnetes Element

In diesem Abschnitt werden die untergeordneten Elemente von <PublishMessage> beschrieben.

<Attributes>

Gibt die Attribute an, die an die Pub/Sub-Nachricht angehängt werden sollen.

Jedes Attribut ist ein Schlüssel/Wert-Paar. Der Name, der dem Attribut zugeordnet ist, muss eindeutig sein. Der Wert für jede wird dynamisch zur Laufzeit über eine Nachrichtenvorlage bestimmt.

Standardwert	–
Erforderlich?	Erforderlich
Typ	String
Übergeordnetes Element	<PublishMessage>
Untergeordnete Elemente	Keine

Das Element <Attributes> verwendet die folgende Syntax:

Syntax

  <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>

Beispiel 1

Im folgenden Beispiel wird beim Veröffentlichen der Nachricht ein einzelnes Attribut mit einem festen Wert festgelegt:

<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>

Beispiel 2

Im folgenden Beispiel werden beim Veröffentlichen der Nachricht mehrere Attribute festgelegt. Die Werte einiger Attribute werden dynamisch zur Laufzeit bestimmt:

<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>

Wird zusätzlich zum Attribut name verwendet, um die Richtlinie im Proxy-Editor der Verwaltungs-UI mit einem anderen, natürlicher klingenden Namen zu versehen.

Das Element <DisplayName> ist für alle Richtlinien gleich.

Standardwert	–
Erforderlich?	Optional. Wenn Sie <DisplayName> weglassen, wird der Wert des Attributs name der Richtlinie verwendet.
Typ	String
Übergeordnetes Element	<PolicyElement>
Untergeordnete Elemente	Keine

Das <DisplayName>-Element verwendet die folgende Syntax:

Syntax

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

Beispiel

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

Das <DisplayName>-Element hat keine Attribute oder untergeordneten Elemente.

<Source>

Gibt die zu veröffentlichende Nachricht an.

Die Nachricht kann ein Literaltext, eine Ablaufvariable oder eine Kombination aus beiden in Form einer Nachrichtenvorlage sein.

Standardwert	–
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<PublishMessage>
Untergeordnete Elemente	Keine

Das Element <Source> verwendet die folgende Syntax:

Syntax

 <Source>SOURCE</Source>

Beispiel-1

Im folgenden Beispiel wird die Quellnachricht auf den Wert der Ablaufvariablen flow-var-1 festgelegt:

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

Beispiel-2

Im folgenden Beispiel wird eine Nachrichtenvorlage verwendet, um eine JSON-Nachricht mit dynamischen Inhalten zu veröffentlichen:

<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>

Übergeordnetes Element von <Topic>.

Sie können jeweils nur in einem Pub/Sub-Thema veröffentlichen. Daher kann das Element <CloudPubSub> nur ein einzelnes <Topic>-Element enthalten.

Standardwert	–
Erforderlich?	Erforderlich
Typ	Komplexer Typ
Übergeordnetes Element	<PublishMessage>
Untergeordnete Elemente	<Topic>

Das <CloudPubSub>-Element verwendet die folgende Syntax:

Syntax

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

Beispiel

Das folgende Beispiel zeigt die Attribute des Elements <CloudPubSub>:

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

<Topic>

Gibt das Pub/Sub-Thema an, in dem Sie die Nachricht <Source> veröffentlichen möchten.

Sie müssen den Namen des Themas im Format projects/project-id/topics/topic-name angeben.

Standardwert	–
Erforderlich?	Erforderlich
Typ	String
Übergeordnetes Element	<CloudPubSub>
Untergeordnete Elemente	Keine

Das Element <Topic> verwendet die folgende Syntax:

Syntax

<Topic>TOPIC_NAME</Topic>

Beispiel

Im folgenden Beispiel wird das Pub/Sub-Thema angegeben, in dem veröffentlicht werden soll:

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

In diesem Beispiel ist project-id-marketing Ihre Google Cloud-Projekt-ID und topic-name-test1 das Thema, in dem die Nachricht veröffentlicht werden soll.

<UseMessageAsSource>

Gibt die zu veröffentlichende Nachricht an.

Verwenden Sie dieses Element als Alternative zum <Source>-Element. Der Wert sollte der Name einer Ablaufvariablen sein, die auf eine Nachricht verweist, z. B. request, response oder message. Wenn Sie dieses Element angeben, verwendet die Richtlinie den Inhalt der Nachricht als zu veröffentlichende Nachricht. Sie sollten dieses Element anstelle von <Source> verwenden, wenn der Nachrichteninhalt ein Oktettstrom ist, der nicht als String dargestellt werden kann, z. B. Inhalt aus einer Binärdatei.

Standardwert	–
Erforderlich?	Optional
Typ	String
Übergeordnetes Element	<PublishMessage>
Untergeordnete Elemente	Keine

Das Element <UseMessageAsSource> verwendet die folgende Syntax:

Syntax

<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>

Beispiel-1

Im folgenden Beispiel wird in der Richtlinie festgelegt, dass der Inhalt der Anfragenachricht als Nutzlast für die Pub/Sub-Nachricht verwendet werden soll:

<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>

Gibt an, ob die Verarbeitung beendet wird, wenn Apigee auf eine nicht aufgelöste Variable stößt.

Standardwert	False
Erforderlich?	Optional
Typ	Boolescher Wert
Übergeordnetes Element	<PublishMessage>
Untergeordnete Elemente	Keine

Legen Sie den Wert auf true fest, um nicht aufgelöste Variablen zu ignorieren und die Verarbeitung fortzusetzen, andernfalls false. Der Standardwert ist false.

Das Festlegen von true für <IgnoreUnresolvedVariables> unterscheidet sich vom Festlegen von continueOnError auf true für <PublishMessage>. Wenn Sie true für continueOnError angeben, ignoriert Apigee alle Fehler, also nicht nur Fehler in Variablen.

Das <IgnoreUnresolvedVariables>-Element verwendet die folgende Syntax:

Syntax

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

Beispiel

Im folgenden Beispiel wird für <IgnoreUnresolvedVariables> der Wert true festgelegt:

<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

Ablaufvariablen

Ablaufvariablen sind Objekte, die bestimmte Daten enthalten, und stehen Ihnen im Kontext eines API-Proxy-Ablaufs zur Verfügung. Diese Variablen speichern Informationen wie Nutzlastinformationen, URL-Pfad, IP-Adressen und Daten aus der Richtlinienausführung. Weitere Informationen zu Ablaufvariablen finden Sie unter Ablaufvariablen verwenden.

Wenn die PublishMessage-Richtlinie erfolgreich im Pub/Sub-Thema veröffentlicht hat, setzt Apigee die Ablaufvariable publishmessage.message.id auf die messageId, die vom Pub/Sub-Server zurückgegeben wird. Die Ablaufvariable ist vom Typ String und die Variable steht Ihnen ab dem Proxy-Anfrageablauf zur Verfügung. Je nach Ihrer Anforderung können Sie die Ablaufvariable in anderen nachgelagerten Richtlinien verwenden. Wenn jedoch die Veröffentlichung fehlschlägt, legt Apigee die Variable publishmessage.message.id nicht fest und der Zugriff auf diese Variable führt zu Fehlern.

Weitere Informationen zu den verschiedenen Arten von Ablaufvariablen finden Sie in der Referenz zu Ablaufvariablen.

Fehlercodes

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