PublishMessage-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Die PublishMessage-Richtlinie ist in Apigee und Apigee Hybrid Version 1.7 und höher verfügbar.

Ü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. Nicht alle Nutzer müssen Richtlinien- und Umgebungstypen kennen. 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	<CloudPubSub> <DisplayName> <Source>

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

Untergeordnetes Element	Erforderlich?	Beschreibung
<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>	Erforderlich	Gibt die zu veröffentlichende Nachricht an.
Weitere untergeordnete Elemente
<Topic>	Erforderlich	Gibt das Pub/Sub-Thema an, in dem Sie die Nachricht veröffentlichen möchten.

Das <PublishMessage>-Element verwendet die folgende Syntax:

Syntax

<?xml version="1.0" encoding="UTF-8"?><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

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

<?xml version="1.0" encoding="UTF-8"?><PublishMessage continueOnError="false" enabled="true" name="Publish-Message-1">
    <DisplayName>Publish Message-1</DisplayName>
    <Source>{flow-variable-1}</Source>
    <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.

<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?	Erforderlich
Typ	String
Übergeordnetes Element	<PublishMessage>
Untergeordnete Elemente	Keine

Das <Source>-Element verwendet die folgende Syntax:

Syntax

 <Source>SOURCE</Source>

Example-1

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

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

Example-2

Im folgenden Beispiel wird die Quelle auf source-message-text-01 festgelegt:

<Source>source-message-text-01</Source>

<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/{request.header.project}/topics/{request.header.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	Komplexer Typ
Übergeordnetes Element	<CloudPubSub>
Untergeordnete Elemente	Keine

Das <Topic>-Element 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 <Source> veröffentlicht werden soll.

<IgnoreUnresolvedVariables>

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

Standardwert	Falsch
Erforderlich?	Optional
Typ	Boolesch
Ü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

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode	HTTP-Status	Ursache
steps.publishmessage.PermissionDeniedError	500	Dieser Fehler tritt auf, wenn das Laufzeitdienstkonto das Proxy-Dienstkonto nicht übernehmen kann oder wenn das Proxy-Dienstkonto nicht die Berechtigung hat, in dem Thema zu veröffentlichen.
steps.publishmessage.ExecutionError	500	Dieser Fehler tritt auf, wenn beim Veröffentlichen der Nachricht in Pub/Sub ein unerwarteter Fehler aufgetreten ist. Sie können die Details des Fehlers in der Fehlermeldung ansehen.

Fehlervariablen

Wenn in einer Richtlinie Ausführungsfehler auftreten, generiert Apigee Fehlermeldungen. Sie können sich diese Fehlermeldungen in der Fehlerantwort ansehen. Häufig sind vom System generierte Fehlermeldungen im Kontext Ihres Produkts möglicherweise nicht relevant. Sie können die Fehlermeldungen basierend auf dem Fehlertyp anpassen, um die Nachrichten aussagekräftiger zu machen.

Zum Anpassen der Fehlermeldungen können Sie entweder Fehlerregeln oder die RaiseFault-Richtlinie verwenden. Informationen zu Unterschieden zwischen Fehlerregeln und der RaiseFault-Richtlinie finden Sie unter FaultRules-Richtlinie im Vergleich zur RaiseFault-Richtlinie. Prüfen Sie, ob Bedingungen mit dem Element Condition in den Fehlerregeln und in der RaiseFault-Richtlinie verwendet werden. Apigee stellt Fehlervariablen bereit, die für jede Richtlinie eindeutig sind. Die Werte der Fehlervariablen werden festgelegt, wenn eine Richtlinie Laufzeitfehler auslöst. Mit diesen Variablen können Sie nach bestimmten Fehlerbedingungen suchen und entsprechende Maßnahmen ergreifen. Weitere Informationen zum Prüfen von Fehlerbedingungen finden Sie unter Bedingungen erstellen.

Variablen	Wo	Beispiel
fault.name	Der fault.name kann mit einem der Fehler übereinstimmen, die in der Tabelle Laufzeitfehler aufgeführt sind. Der Fehlername ist der letzte Teil des Fehlercodes.	fault.name Matches "UnresolvedVariable"
publishmessage.POLICY_NAME.failed	POLICY_NAME ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat.	publishmessage.publish-message-1.failed = true

Weitere Informationen zu Richtlinienfehlern finden Sie unter Was Sie über Richtlinienfehler wissen müssen.