ExtensionCallout-Richtlinie

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Binden Sie mithilfe der ExtensionCallout-Richtlinie eine Erweiterung in einen API-Proxy ein.

Eine Erweiterung bietet Zugriff auf eine bestimmte Ressource außerhalb von Apigee Edge. Die Ressource könnte Google Cloud Platform-Dienste wie Cloud Storage oder Cloud Speech-to-Text sein. Die Ressource kann jedoch jede externe Ressource sein, auf die über HTTP oder HTTPS zugegriffen werden kann.

Was sind Erweiterungen? Eine einführende Anleitung finden Sie unter Anleitung: Erweiterung hinzufügen und verwenden.

Bevor Sie über die ExtensionCallout-Richtlinie auf eine Erweiterung zugreifen können, müssen Sie die Erweiterung aus einem Erweiterungspaket, das bereits in Ihrer Apigee Edge-Organisation installiert ist, hinzufügen, konfigurieren und bereitstellen.

Samples

Im Folgenden finden Sie eine Beispielrichtlinie zur Verwendung mit der Cloud Logging-Erweiterung:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Logging-Extension">
        <DisplayName>Logging Extension</DisplayName>
        <Connector>cloud-extension-sample</Connector>
        <Action>log</Action>
        <Input>{
                "logName" : "example-log",
                "metadata" : "test-metadata",
                "message" : "This is a test"
        }</Input>
    <Output>cloud-extension-example-log</Output>
</ConnectorCallout>

Eine vollständige Anleitung zur Verwendung der Cloud Logging-Erweiterung finden Sie unter Anleitung: Erweiterungen verwenden.

Beispiele für alle verfügbaren Erweiterungen finden Sie in der Übersicht zu Erweiterungen.

ExtensionCallout-Richtlinie

Verwenden Sie die ExtensionCallout-Richtlinie, wenn Sie eine konfigurierte Erweiterung für den Zugriff auf eine externe Ressource von einem API-Proxy verwenden möchten.

Bevor Sie diese Richtlinie verwenden können, benötigen Sie Folgendes:

  • Einige Details zur externen Ressource, auf die Sie über diese Richtlinie zugreifen möchten. Diese Details sind ressourcenspezifisch. Wenn die Richtlinie beispielsweise auf Ihre Cloud Firestore-Datenbank zugreift, müssen Sie die Sammlung und den Namen des Dokuments kennen, das Sie erstellen oder aufrufen möchten. In der Regel verwenden Sie ressourcenspezifische Informationen, wenn Sie die Anfrage- und Antwortverarbeitung dieser Richtlinie konfigurieren.
  • Eine Erweiterung, die der Umgebung, in der Ihr API-Proxy bereitgestellt wird, hinzugefügt, konfiguriert und bereitgestellt wird. Mit anderen Worten: Wenn Sie diese Richtlinie verwenden, um auf einen bestimmten Google Cloud-Dienst zuzugreifen, muss eine bereitgestellte Erweiterung für diesen Dienst in Ihrer Umgebung vorhanden sein. Die Konfigurationsdetails enthalten in der Regel erforderliche Informationen, um den Zugriff auf die Ressource einzuschränken, z. B. eine Projekt-ID oder einen Kontonamen.

ExtensionCallout-Richtlinie in einem PostClientFlow verwenden

Sie können die ExtensionCallout-Richtlinie aus dem PostClientFlow eines API-Proxys aufrufen. PostClientFlow wird ausgeführt, nachdem die Antwort an den anfragenden Client gesendet wurde. Dadurch wird sichergestellt, dass alle Messwerte für das Logging verfügbar sind. Weitere Informationen zur Verwendung von PostClientFlow finden Sie in der API-Proxy-Konfigurationsreferenz.

Wenn Sie die ExtensionCallout-Richtlinie verwenden möchten, um die Google Cloud Logging-Erweiterung aus einem PostClientFlow aufzurufen, muss das Flag features.allowExtensionsInPostClientFlow in Ihrer Organisation auf true gesetzt sein.

  • Wenn Sie Kunde von Apigee Edge for Public Cloud sind, ist das Flag features.allowExtensionsInPostClientFlow standardmäßig auf true gesetzt.

  • Wenn Sie ein Kunde von Apigee Edge für Private Cloud sind, verwenden Sie die API Organisationsattribute aktualisieren, um das Flag features.allowExtensionsInPostClientFlow auf true zu setzen.

Alle Einschränkungen beim Aufrufen der MessageLogging-Richtlinie aus PostClientFlow gelten auch für die ExtensionCallout-Richtlinie. Weitere Informationen finden Sie unter Nutzungshinweise.

Elementverweis

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="false" enabled="true" name="Extension-Callout-1">
    <DisplayName/>
    <Connector/>
    <Action/>
    <Input/>
    <Output/>
</ConnectorCallout>

<ConnectorCallout>-Attribute

<ConnectorCallout name="Extension-Callout-1" continueOnError="false" enabled="true" async="false">

In der folgenden Tabelle werden Attribute beschrieben, die für alle übergeordneten Richtlinienelemente gelten:

Attribut Beschreibung Standard Präsenz
name

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.

 – Erforderlich
continueOnError

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.

 false Optional
enabled

Setzen Sie den Wert auf true, um die Richtlinie zu erzwingen.

Legen Sie false fest, um die Richtlinie zu deaktivieren. Die Richtlinie wird nicht erzwungen, selbst wenn sie mit einem Ablauf verknüpft ist.

 true Optional
async

Dieses Attribut wurde verworfen.

 false Eingestellte Funktionen

<DisplayName>-Element

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

<DisplayName>Policy Display Name</DisplayName>
Standard

–

Wenn Sie dieses Element weglassen, wird der Wert des Namensattributs name der Richtlinie verwendet.
Präsenz Optional
Typ String

Element <Action>

Die für die Erweiterung zugängliche Aktion, die von der Richtlinie aufgerufen werden soll.

<Action>action-exposed-by-extension</Action>
Standard Keine
Präsenz Erforderlich
Typ String

Jede Erweiterung verfügt über eigene Aktionen, die den Zugriff auf die Funktionen der von der Erweiterung repräsentierten Ressource ermöglichen. Sie können sich eine Aktion als eine Funktion vorstellen, die Sie mit dieser Richtlinie aufrufen und dabei die Argumente der Funktion mithilfe des Inhalts des Elements <Input> angeben. Die Antwort der Aktion wird in der Variablen gespeichert, die Sie mit dem Element <Output> angeben.

Eine Liste der Funktionen der Erweiterung finden Sie in der Referenz für die Erweiterung, die Sie über diese Richtlinie aufrufen.

<Connector>-Element

Der Name der konfigurierten Erweiterung, die verwendet werden soll. Dies ist der umgebungsbezogene Name der Erweiterung bei der Konfiguration für die Bereitstellung in einer Umgebung.

<Connector>name-of-configured-extension</Connector>

Standard Keine
Präsenz Erforderlich
Typ String

Eine Erweiterung hat Konfigurationswerte, die sich möglicherweise von anderen bereitgestellten Erweiterungen unterscheiden, die auf demselben Erweiterungspaket basieren. Diese Konfigurationswerte können wichtige Unterschiede in der Laufzeitfunktion zwischen Erweiterungen darstellen, die über dasselbe Paket konfiguriert wurden. Achten Sie daher darauf, die richtige Erweiterung anzugeben, die aufgerufen werden soll.

Element <Input>

JSON mit dem Anfragetext, der an die Erweiterung gesendet werden soll.

<Input><![CDATA[ JSON-containing-input-values ]]></Input>

Standard Keine
Präsenz Je nach Erweiterung optional oder erforderlich.
Typ String

Dies ist im Wesentlichen ein Argument für die Aktion, die Sie mit dem Element <Action> angeben. Der Wert des Elements <Input> variiert je nach Erweiterung und Aktion, die Sie aufrufen. Weitere Informationen zu den Eigenschaften der einzelnen Aktionen finden Sie in der Dokumentation zum Erweiterungspaket.

Beachten Sie, dass viele <Input>-Elementwerte korrekt funktionieren, ohne dass sie in einen <![CDATA[]]>-Abschnitt eingeschlossen sind. Die Regeln von JSON lassen jedoch Werte zu, die nicht als XML geparst werden können. Als Best Practice sollte das JSON-Format in einen CDATA-Abschnitt eingeschlossen werden, um Laufzeitparsefehler zu vermeiden.

Der Wert des <Input>-Elements ist ein wohlgeformtes JSON-Format, dessen Eigenschaften Werte angeben, die an die aufzurufende Erweiterungsaktion gesendet werden sollen. Für die Aktion log der Erweiterung Google Cloud Logging-Erweiterung werden beispielsweise Werte benötigt, die das Log angeben, in das geschrieben werden soll (logName), Metadaten, die in den Eintrag aufgenommen werden sollen (metadata), und die Lognachricht (data). Hier ein Beispiel:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "This is a test"
}]]></Input>

Flussvariablen in <Input>-JSON verwenden

Der Inhalt von <Input> wird als Nachrichtenvorlage behandelt. Das bedeutet, dass ein Variablenname in geschweiften Klammern zur Laufzeit durch den Wert der referenzierten Variablen ersetzt wird.

Sie könnten beispielsweise den vorhergehenden <Input>-Block so umschreiben, dass die client.ip-Flussvariable verwendet wird, um die IP-Adresse des Clients abzurufen, der den API-Proxy aufruft:

<Input><![CDATA[{
    "logName" : "example-log",
    "metadata" : {
        "resource": {
            "type": "global",
            "labels": {
                "project_id": "my-test"
            }
        }
    },
    "message" : "{client.ip}"
}]]></Input>

Wenn ein Attributwert im JSON-Format zur Laufzeit in Anführungszeichen gesetzt werden soll, müssen Sie im JSON-Code Anführungszeichen verwenden. Dies gilt auch dann, wenn Sie eine Flussvariable als JSON-Attributwert angeben, der zur Laufzeit aufgelöst werden soll.

Das folgende <Input>-Beispiel enthält zwei Verweise auf Flussvariablen:

<Input><![CDATA[{
  "logName" : "example-log",
  "metadata" : {my.log.entry.metadata},
  "message" : "{client.ip}"
}]]></Input>

Während der Laufzeit werden JSON-Attributwerte so aufgelöst:

  • Attributwert logName: das Stringliteral example-log.
  • Attributwert metadata: der Wert der Flussvariablen my.log.entry.metadata ohne umschließende Anführungszeichen. Dies kann nützlich sein, wenn der Wert der Variablen selbst ein JSON-Wert ist und ein Objekt darstellt.
  • Attributwert message: der Wert der Flussvariablen client.ip mit umschließenden Anführungszeichen.

Element <Output>

Name einer Variablen, in der die Antwort der Erweiterungsaktion gespeichert wird.

<Output>variable-name</Output> <!-- The JSON object inside the variable is parsed -->

oder

<Output parsed="false">variable-name</Output>  <!-- The JSON object inside the variable is raw, unparsed -->

Standard Keine
Präsenz Je nach Erweiterung optional oder erforderlich.
Typ Geparstes Objekt oder String, je nach Einstellung für das parsed-Attribut.

Wenn die Antwort empfangen wird, wird der Antwortwert in die hier angegebene Variable eingefügt, wo Sie über einen anderen API-Proxy-Code darauf zugreifen können.

Antwortobjekte der Erweiterung haben das JSON-Format. Es gibt zwei Möglichkeiten, wie die Richtlinie mit JSON umgeht:

  • Geparst (Standardeinstellung): Die Richtlinie parst das JSON-Objekt und generiert automatisch Variablen mit den JSON-Daten. Wenn die JSON-Datei beispielsweise "messageId" : 12345; enthält und Sie die Ausgabevariable extensionOutput nennen, können Sie über die Variable {extensionOutput.messageId} in anderen Richtlinien auf diese Nachrichten-ID zugreifen.
  • Nicht geparst: Die Ausgabevariable enthält die nicht geparste JSON-Rohantwort der Erweiterung. Sie können den Antwortwert aber auch in einem separaten Schritt mithilfe der JavaScript-Richtlinie parsen.

Attribute für <Ausgabe>

Attribut Beschreibung Standard Präsenz
geparst Parst das von der Erweiterung zurückgegebene JSON-Objekt. Dadurch kann auf die Daten im JSON-Objekt von anderen Richtlinien als Variablen zugegriffen werden. true Optional

Ablaufvariablen

Keine.

Fehlercodes

Von Apigee Edge-Richtlinien zurückgegebene Fehler haben ein konsistentes Format, wie in der Richtlinienfehlerreferenz beschrieben.

In diesem Abschnitt werden die Fehlermeldungen und Flussvariablen beschrieben, die festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln für einen Proxy 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.

Fehlername HTTP-Status Ursache
ExecutionFailed 500 Die Erweiterung antwortet mit einem Fehler.

Bereitstellungsfehler

Diese Fehler können auftreten, wenn Sie einen Proxy mit dieser Richtlinie bereitstellen.

Fehlername Tritt auf, wenn Folgendes eintritt Problembehebung
InvalidConnectorInstance Das <Connector>-Element ist leer.
ConnectorInstanceDoesNotExists Die im <Connector>-Element angegebene Erweiterung ist in der Umgebung nicht vorhanden.
InvalidAction Das <Action>-Element in der ExtensionCallout-Richtlinie fehlt oder ist auf einen leeren Wert gesetzt.
AllowExtensionsInPostClientFlow Es ist nicht zulässig, in einem PostClient-Ablauf eine ExtensionCallout-Richtlinie zu verwenden.