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 auftrue
gesetzt.Wenn Sie ein Kunde von Apigee Edge für Private Cloud sind, verwenden Sie die API Organisationsattribute aktualisieren, um das Flag
features.allowExtensionsInPostClientFlow
auftrue
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 Optional können Sie das Element |
– | Erforderlich |
continueOnError |
Legen Sie Legen Sie |
false | Optional |
enabled |
Setzen Sie den Wert auf Legen Sie |
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 |
---|---|
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 Stringliteralexample-log
. - Attributwert
metadata
: der Wert der Flussvariablenmy.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 Flussvariablenclient.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 AusgabevariableextensionOutput
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. |
build |
ConnectorInstanceDoesNotExists |
Die im <Connector> -Element angegebene Erweiterung ist in der Umgebung nicht vorhanden. |
build |
InvalidAction |
Das <Action> -Element in der ExtensionCallout-Richtlinie fehlt oder ist auf einen leeren Wert gesetzt. |
build |
AllowExtensionsInPostClientFlow |
Es ist nicht zulässig, in einem PostClient-Ablauf eine ExtensionCallout-Richtlinie zu verwenden. | build |