ExtensionCallout-Richtlinie

<ph type="x-smartling-placeholder"></ph> Sie sehen die Dokumentation zu Apigee Edge.
Gehen Sie zur Apigee X-Dokumentation. Weitere Informationen

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

Eine Erweiterung bietet Zugriff auf eine bestimmte Ressource außerhalb von Apigee Edge. Bei der Ressource kann es sich um Google Cloud Platform-Dienste wie Cloud Storage oder Cloud Speech-to-Text handeln. 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: Erweiterungen hinzufügen und verwenden.

Bevor Sie über die ExtensionCallout-Richtlinie auf eine Erweiterung zugreifen, 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 eine Beispielrichtlinie für die 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>

Siehe Anleitung: Erweiterungen verwenden für ein vollständiges Tutorial zur Verwendung der Cloud Logging-Erweiterung.

Beispiele für alle verfügbaren Erweiterungen finden Sie unter Referenz für Erweiterungen.

ExtensionCallout-Richtlinie

Verwenden Sie die Richtlinie „ExtensionCallout“, wenn Sie mithilfe einer konfigurierten Erweiterung von einem API-Proxy aus auf eine externe Ressource zugreifen möchten.

Für die Verwendung dieser Richtlinie 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, die Sie erstellen oder auf die Sie zugreifen möchten. In der Regel verwenden Sie ressourcenspezifische Informationen, um die Verarbeitung von Anfragen und Antworten dieser Richtlinie zu konfigurieren.
• Eine Erweiterung hinzugefügt, konfiguriert und bereitgestellt in der Umgebung, in der Ihr API-Proxy bereitgestellt wird. Mit anderen Worten: wenn Sie mit dieser Richtlinie auf einen bestimmten Google Cloud-Dienst zugreifen, dann muss eine bereitgestellte Erweiterung für diesen Dienst in Ihrer Umgebung vorhanden sein. Die Konfigurationsdetails enthalten in der Regel erforderliche Informationen zum Eingrenzen Zugriff 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. PostClientFlow wird ausgeführt, nachdem die Antwort an den anfordernden Client gesendet wurde, Dadurch sind alle Messwerte für das Logging verfügbar. Weitere Informationen zur Verwendung von PostClientFlow finden Sie in der API-Proxy-Konfigurationsreferenz.

Wenn Sie die Google Cloud Logging-Erweiterung mithilfe der Richtlinie „ExtensionCallout“ aufrufen möchten aus einem PostClientFlow, und achten Sie darauf, dass das Flag features.allowExtensionsInPostClientFlow ist in Ihrer Organisation auf true festgelegt.

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

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

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

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>

&lt;ConnectorCallout&gt; 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>

&lt;Action&gt; Unterelement

Die durch die Erweiterung sichtbare Aktion, die die Richtlinie aufrufen soll.

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

Jede Erweiterung bietet einen eigenen Satz von Aktionen, die 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, indem Sie den Inhalt des Elements <Input> verwenden, um die Argumente der Funktion anzugeben. 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.

<Anschluss> Unterelement

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

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

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

&lt;Input&gt; Unterelement

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

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

Dies ist im Wesentlichen ein Argument für die Aktion, die Sie mit dem Element <Action> angeben. Der Wert des <Input>-Elements hängt von der Erweiterung und der Aktion ab, die du aufrufst. Weitere Informationen zu den Eigenschaften der einzelnen Aktionen finden Sie in der Dokumentation zu Erweiterungspaketen.

Obwohl viele <Input>-Elementwerte korrekt funktionieren, ohne in einen <![CDATA[]]>-Abschnitt eingeschlossen zu werden, lassen die JSON-Regeln Werte zu, die nicht als XML geparst werden können. Als Best Practice empfiehlt es sich, die JSON-Datei als CDATA-Abschnitt einzuschließen, um Laufzeit-Parsing-Fehler zu vermeiden.

Der Wert des <Input>-Elements ist ein wohlgeformtes JSON-Format, dessen Eigenschaften Werte angeben die an die aufzurufende Erweiterungsaktion gesendet wird. Beispiel: Der Parameter Google Cloud Logging-Erweiterung Die Aktion log der Erweiterung verwendet Werte, die das Protokoll angeben, in das geschrieben werden soll (logName), Metadaten, die in den Eintrag (metadata) enthalten sein sollen, 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 behandelt als E-Mail-Vorlage. Das bedeutet, dass ein Variablenname in geschweiften Klammern zur Laufzeit durch den Wert der referenzierten Variablen ersetzt wird.

Sie können beispielsweise den vorherigen <Input>-Block so umschreiben, dass mit der Flussvariablen client.ip die IP-Adresse des Clients abgerufen wird, 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 in der JSON-Datei 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-Eigenschaftswert angeben, der zur Laufzeit aufgelöst werden soll.

Das folgende <Input>-Beispiel enthält zwei Flussvariablenverweise:

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

Zur Laufzeit werden JSON-Attributwerte so aufgelöst:

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

&lt;Output&gt; Unterelement

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. Dort können Sie von anderem API-Proxy-Code darauf zugreifen.

Antwortobjekte der Erweiterung haben das JSON-Format. Es gibt zwei Optionen für die Verarbeitung von JSON durch die Richtlinie:

• 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 mithilfe der Variablen {extensionOutput.messageId} in anderen Richtlinien auf diese Nachrichten-ID zugreifen.
• Unparsed: Die Ausgabevariable enthält die unbearbeitete, nicht geparste JSON-Antwort der Erweiterung. Wenn Sie möchten, können Sie den Antwortwert mithilfe der JavaScript-Richtlinie trotzdem in einem separaten Schritt parsen.

&lt;Output&gt; Attribute

Ablaufvariablen

Keine.

Fehlercodes

Von Apigee Edge-Richtlinien zurückgegebene Fehler haben ein konsistentes Format, wie in der Referenz zu Richtlinienfehlern 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.

Bereitstellungsfehler

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