ExtensionCallout-Richtlinie

Sie lesen gerade die Dokumentation zu Apigee Edge.
Apigee X-Dokumentation aufrufen. info

Mit der ExtensionCallout-Richtlinie können Sie eine Erweiterung in einen API-Proxy einbinden.

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

Eine Übersicht über Erweiterungen finden Sie unter Was sind Erweiterungen? Eine Einführungsanleitung 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.

Beispiele

Unten sehen Sie ein Beispiel für eine Richtlinie, die mit der Cloud Logging-Erweiterung verwendet werden kann:

<?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 über Erweiterungen.

Informationen zur ExtensionCallout-Richtlinie

Verwenden Sie die ExtensionCallout-Richtlinie, wenn Sie über einen API-Proxy mit einer konfigurierten Erweiterung auf eine externe Ressource zugreifen 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 spezifisch für die Ressource. Wenn die Richtlinie beispielsweise auf Ihre Cloud Firestore-Datenbank zugreifen soll, müssen Sie den Namen der Sammlung und des Dokuments kennen, die Sie erstellen oder auf die Sie zugreifen möchten. In der Regel verwenden Sie ressourcenspezifische Informationen, um die Anfrage- und Antwortverarbeitung dieser Richtlinie zu konfigurieren.
• Eine Erweiterung, die der Umgebung, in der Ihr API-Proxy bereitgestellt wird, hinzugefügt, konfiguriert und bereitgestellt wurde. Wenn Sie also mit dieser Richtlinie auf einen bestimmten Google Cloud-Dienst zugreifen möchten, muss in Ihrer Umgebung eine bereitgestellte Erweiterung für diesen Dienst vorhanden sein. Die Konfigurationsdetails enthalten in der Regel erforderliche Informationen zum Einschränken des Zugriffs auf die Ressource, z. B. eine Projekt-ID oder einen Kontonamen.

ExtensionCallout-Richtlinie in einem PostClientFlow verwenden

Sie können die ExtensionCallout-Richtlinie über den PostClientFlow eines API-Proxys aufrufen. Der PostClientFlow wird ausgeführt, nachdem die Antwort an den anfragenden Client gesendet wurde. So sind alle Messwerte für die Protokollierung verfügbar. 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 Apigee Edge for Public Cloud-Kunde sind, ist das Flag features.allowExtensionsInPostClientFlow standardmäßig auf true gesetzt.

• Wenn Sie Apigee Edge for Private Cloud-Kunde sind, verwenden Sie die API Update organization properties, um das Flag features.allowExtensionsInPostClientFlow auf true zu setzen.

Alle Einschränkungen für den Aufruf der MessageLogging-Richtlinie aus dem PostClientFlow gelten auch für die ExtensionCallout-Richtlinie. Weitere Informationen finden Sie unter Hinweise zur Nutzung.

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:

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

<Action>-Element

Die von der Richtlinie aufzurufende, von der Erweiterung bereitgestellte Aktion.

<Action>action-exposed-by-extension</Action>

Jede Erweiterung bietet eine eigene Reihe von Aktionen, die Zugriff auf die Funktionen der Ressource ermöglichen, die die Erweiterung repräsentiert. Eine Aktion ist wie eine Funktion, die Sie mit dieser Richtlinie aufrufen. Die Argumente der Funktion werden mit dem Inhalt des Elements <Input> angegeben. 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 der Erweiterung zugewiesen wurde, als sie für die Bereitstellung in einer Umgebung konfiguriert wurde.

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

Eine Erweiterung hat Konfigurationswerte, die sich von einer anderen bereitgestellten Erweiterung unterscheiden können, die auf demselben Erweiterungspaket basiert. Diese Konfigurationswerte können wichtige Unterschiede in der Laufzeitfunktionalität zwischen Erweiterungen darstellen, die aus demselben Paket konfiguriert wurden. Geben Sie daher unbedingt die richtige Erweiterung an, die aufgerufen werden soll.

<Input>-Element

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

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

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

Viele <Input>-Elementwerte funktionieren auch ohne Einbettung in einen <![CDATA[]]>-Abschnitt korrekt. Die JSON-Regeln lassen jedoch Werte zu, die nicht als XML geparst werden. Als Best Practice sollten Sie den JSON-Code in einen CDATA-Abschnitt einschließen, um Laufzeit-Parsing-Fehler zu vermeiden.

Der Wert des Elements <Input> ist wohlgeformtes JSON, dessen Eigenschaften Werte angeben, die an die aufzurufende Erweiterungsaktion gesendet werden sollen. Die Aktion log der Google Cloud Logging Extension-Erweiterung verwendet beispielsweise Werte, die das Log angeben, in das geschrieben werden soll (logName), Metadaten, die im Eintrag enthalten sein sollen (metadata), und die Log-Nachricht (data). Hier ist ein Beispiel:

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

Ablaufvariablen in <Input>-JSON verwenden

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

Sie könnten den vorherigen <Input>-Block beispielsweise so umschreiben, dass die Ablaufvariable client.ip 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-Code zur Laufzeit in Anführungszeichen gesetzt werden soll, müssen Sie Anführungszeichen in Ihrem JSON-Code verwenden. Das gilt auch, wenn Sie eine Ablaufvariable als JSON-Attributwert angeben, der zur Laufzeit aufgelöst werden soll.

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

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

Zur Laufzeit werden JSON-Attributwerte so aufgelöst:

• logName-Property-Wert – das Stringliteral example-log.
• metadata-Eigenschaftswert: Der Wert der my.log.entry.metadata-Ablaufvariablen ohne umschließende Anführungszeichen. Das kann nützlich sein, wenn der Wert der Variablen selbst JSON ist, das ein Objekt darstellt.
• message-Property-Wert – der Wert der Ablaufvariablen client.ip mit einschließenden Anführungszeichen.

<Output>-Element

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

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

Antwortobjekte für Erweiterungen sind im JSON-Format. Es gibt zwei Möglichkeiten, wie die Richtlinie das JSON verarbeitet:

• Geparsed (Standard): 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 Ihre Ausgabevariable extensionOutput nennen, können Sie in anderen Richtlinien mit der Variablen {extensionOutput.messageId} auf diese Nachrichten-ID zugreifen.
• Nicht geparst: Die Ausgabevariable enthält die rohe, ungeparste JSON-Antwort der Erweiterung. Bei Bedarf können Sie den Antwortwert in einem separaten Schritt mit der JavaScript-Richtlinie parsen.

<Output>-Attribute

Ablaufvariablen

Keine.

Fehlercodes

Fehler, die von Apigee Edge-Richtlinien zurückgegeben werden, folgen einem einheitlichen Format, das in der Richtlinienfehlerreferenz beschrieben wird.

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.

Bereitstellungsfehler

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