Diese Seite gilt für Apigee und Apigee Hybrid.
Apigee Edge-Dokumentation aufrufen
Auf dieser Seite wird das YAML-Format für Apigee-Featurevorlagen beschrieben: die Dokumenttypen template, feature und proxy sowie alle zugehörigen Felder. Eine konzeptionelle Einführung finden Sie unter Proxy mit YAML konfigurieren. Eine Schritt-für-Schritt-Anleitung finden Sie unter API-Proxy aus einer YAML-Vorlage erstellen.
Konventionen
- Feldnamen verwenden camelCase. Beispiel:
schemaVersion,basePath,displayName,faultRules,defaultFaultRule,httpTargetConnection. - Das Schema ist strikt. Unbekannte Felder verursachen beim Importieren der Datei einen Fehler.
- Pflichtfelder. Beim Parsen einer Datei werden nur
gatewayundschemaVersionvalidiert. Andere Felder, die in den folgenden Tabellen mit Ja gekennzeichnet sind, sind in der Praxis erforderlich, um einen funktionierenden API-Proxy zu erstellen.
Allgemeine Felder auf oberster Ebene
Jedes template-, feature- und proxy-Dokument beginnt mit den folgenden Feldern.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
gateway |
Das Ziel-Gateway. Muss apigee lauten. |
– | Ja |
schemaVersion |
Die Schemaversion des Dokuments. Muss 1.0.0 lauten. |
– | Ja |
name |
Der Name des Dokuments. Bei einer Vorlage oder einem Proxy ist dies der API-Proxy-Name, der in das Bundle geschrieben wird. | – | Ja |
type |
Der Dokumenttyp: template, feature oder proxy. |
– | Ja |
description |
Eine menschenlesbare Beschreibung. | – | Nein |
priority |
Eine Ganzzahl, die die Reihenfolge steuert, in der Features während der Kompilierung angewendet werden. Niedrigere Nummern werden zuerst angewendet. | 100 |
Nein |
Dokumenttyp: Vorlage
Eine Vorlage ist der Einstiegspunkt, den Sie importieren. Sie stellt Features zusammen und definiert die Endpunkte und Routen des Proxys. Eine Vorlage enthält keine Richtlinien oder Ressourcen. Diese stammen aus den Features, auf die sie verweist.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
features |
Eine Liste von Featuredateien, die im Proxy zusammengestellt werden sollen. Jeder Eintrag ist ein Pfad zu einer Featuredatei, relativ zum Verzeichnis, das die Vorlage enthält (z. B. ./features/spike-arrest.yaml). |
[] |
Nein |
parameters |
Eine Liste von Parametern, die Werte für die Parameter der Features festlegen. Der default eines Eintrags überschreibt den default des Feature-Parameters mit demselben name. Siehe Parameter. |
[] |
Nein |
endpoints |
Eine Liste von Endpunkten, die Basispfade und Routen definieren. | [] |
Nein |
targets |
Eine Liste von Zielen, die Backend-Verbindungen definieren. | [] |
Nein |
Dokumenttyp: Feature
Ein Feature ist eine wiederverwendbare Konfigurationseinheit, die Sie in eine Vorlage einfügen. Ein Feature enthält Richtlinien und Ressourcen und kann Abläufe, Endpunkte und Ziele zum kompilierten Proxy beitragen. Zusätzlich zu den allgemeinen Feldern auf oberster Ebene hat ein Feature die folgenden Felder.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
displayName |
Ein menschenlesbarer Anzeigename. | – | Nein |
uid |
Eine eindeutige Kennung, die die Richtlinien und Ressourcen des Features voneinander trennt, wenn eine Vorlage das Feature mehrmals enthält. Wenn das Feature ein uid festlegt, stellt die Befehlszeile jedem Richtlinien- und Ressourcennamen UID- voran und aktualisiert die Verweise darauf. Wenn für das Feature kein uid festgelegt ist, verwendet die Befehlszeile die Namen so, wie sie geschrieben sind. |
– | Nein |
documentation |
Erweiterte Dokumentation für die Funktion. | – | Nein |
categories |
Eine Liste mit Kategorielabels im freien Format. | [] |
Nein |
parameters |
Eine Liste der Parameter, die das Feature definiert. | [] |
Nein |
defaultEndpoint |
Ein Proxy-Endpunkt, dessen Abläufe und Standardfehlerregel in jeden Endpunkt des kompilierten Proxys zusammengeführt werden. Verwenden Sie diese Option, um die Richtlinien eines Features an den Anfrage- oder Antwortablauf anzuhängen. | – | Nein |
defaultTarget |
Ein Proxyziel, das als Standard-Backend-Verbindung verwendet wird. | – | Nein |
endpoints |
Eine Liste von Proxy-Endpunkten, die dem Proxy hinzugefügt werden sollen. Ein Endpunkt mit demselben Namen wie ein vorhandener Endpunkt ersetzt diesen. | [] |
Nein |
targets |
Eine Liste von Proxy-Zielen, die dem Proxy hinzugefügt werden sollen. Ein Ziel mit demselben Namen wie ein vorhandenes Ziel ersetzt dieses. | [] |
Nein |
policies |
Eine Liste der Richtlinien, die die Funktion bietet. Wenn das Feature einen uid festlegt, stellt die Befehlszeile jedem Richtliniennamen während der Kompilierung UID- voran, z. B. sa1-SA-SpikeArrest. Andernfalls verwendet die Befehlszeile die Richtliniennamen so, wie sie geschrieben sind. |
[] |
Nein |
resources |
Eine Liste der Ressourcen, die das Feature bereitstellt, z. B. JavaScript- oder Attributdateien. | [] |
Nein |
Dokumenttyp: Proxy
Ein Proxy ist das vollständig aufgelöste Dokument, das die Befehlszeile erzeugt, wenn sie eine Vorlage mit ihren Features kompiliert. Normalerweise erstellen Sie diesen Typ nicht direkt. Er wird hier beschrieben, weil er die Form ist, die zum API-Proxy-Bundle wird.
Ein Proxy hat dieselben Felder wie ein Feature, verwendet jedoch endpoints und targets (nicht defaultEndpoint oder defaultTarget) und stellt immer einen vollständigen, bereitstellbaren Proxy dar. Der type ist proxy.
Verschachtelte Objekte
Parameter
Ein Parameter liefert einen Wert für ein Feature. Ein Feature deklariert seine Parameter und eine Vorlage kann deren Werte in ihrer eigenen parameters-Liste festlegen. Wenn die Befehlszeile eine Vorlage kompiliert, wird jeder Featureparameter so aufgelöst:
- Wenn die
parameters-Liste der Vorlage einen Eintrag enthält, dessennameübereinstimmt und dessendefaultnicht leer ist, verwendet die Befehlszeile diesen Wert. Wenn das Feature einenuidfestlegt, muss der Name des VorlageneintragsFEATURE_NAME.UID.PARAMETER_NAMElauten. - Andernfalls verwendet die Befehlszeile den
defaultdes Feature-Parameters. - Wenn weder das eine noch das andere einen Wert festlegt, wird der Parameter zu einem leeren String aufgelöst. Die Befehlszeile meldet keinen Fehler.
Es gibt kein Befehlszeilen-Flag, um Parameterwerte beim Import festzulegen. Wenn Sie einen Wert ändern möchten, bearbeiten Sie die Vorlage.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Parametername. In Empfohlene Inhalte als {name} referenziert. |
– | Ja |
displayName |
Ein menschenlesbarer Name. | – | Nein |
description |
Eine Beschreibung des Parameters. | – | Nein |
default |
In einem Feature der Wert, der verwendet wird, wenn in der Vorlage kein Wert festgelegt ist. In einer Vorlage der Wert für den Featureparameter mit demselben Namen. Die Befehlszeile ignoriert einen leeren Wert. Die Befehlszeile ersetzt den aufgelösten Wert für {name} in den Strings des Features. |
– | Nein |
examples |
Eine Liste mit Beispielwerten. | [] |
Nein |
maps |
Eine Zuordnung von Wertersetzungen. Wenn der aufgelöste Wert ein Schlüssel in der Zuordnung ist, wird er durch den zugeordneten Wert ersetzt. | – | Nein |
paths |
Eine Liste von JSONPath-Ausdrücken. In dieser Version nicht unterstützt – die Verwendung führt zu einem Fehler. | – | Nein |
endpoint
Wird in der endpoints-Liste einer Vorlage verwendet.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Name des Endpunkts. | – | Ja |
basePath |
Der Basispfad, den Clients zum Aufrufen des Proxys verwenden, z. B. /v1/gemini. |
– | Nein |
routes |
Eine Liste von Routen, die Anfragen Zielen zuordnen. | [] |
Nein |
proxyEndpoint
Wird in der defaultEndpoint und endpoints eines Features sowie in einem kompilierten Proxy verwendet. Erweitert den Endpunkt um die Ablaufverarbeitung.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
flows |
Eine Liste von Abläufen. Abläufe mit dem Namen PreFlow oder PostFlow werden dem entsprechenden Apigee-Ablauf zugeordnet. Alle anderen Namen werden im generischen Ablaufcontainer platziert. |
[] |
Nein |
postClientFlow |
Ein einzelner Ablauf, der ausgeführt wird, nachdem die Antwort an den Client gesendet wurde. | – | Nein |
faultRules |
Eine Liste von Abläufen, die als Fehlerregeln verwendet werden. | [] |
Nein |
defaultFaultRule |
Eine Fehlerregel, die ausgeführt wird, wenn keine andere Fehlerregel übereinstimmt. | – | Nein |
Route
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Routenname. | – | Ja |
target |
Der Name des Zielendpunkts, an den weitergeleitet werden soll. | – | Nein |
condition |
Eine Bedingung, die erfüllt sein muss, damit diese Route angewendet wird. | – | Nein |
Arbeitsfluss
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Name des Ablaufs. Verwenden Sie PreFlow oder PostFlow für die Standard-Anfrage-/Antwortabläufe. |
– | Ja |
mode |
Request oder Response. Bestimmt, ob die Schritte für die Anfrage oder die Antwort ausgeführt werden. |
Request |
Nein |
condition |
Eine Bedingung, die erfüllt sein muss, damit der Ablauf ausgeführt wird. | – | Nein |
steps |
Eine sortierte Liste von Schritten (Richtlinienaufrufen). | [] |
Nein |
Schritt
In einem Schritt wird eine Richtlinie innerhalb eines Ablaufs ausgeführt.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Name der auszuführenden Richtlinie. Verwenden Sie innerhalb eines Features den lokalen Namen der Richtlinie. Der Compiler schreibt ihn in den Namespace-Namen um. | – | Ja |
condition |
Eine Bedingung, die erfüllt sein muss, damit der Schritt ausgeführt wird. | – | Nein |
faultRule
Erweitert flow um ein zusätzliches Feld.
Das Feld mode, das von flow übernommen wird, gilt nicht für eine Fehlerregel. Da eine Fehlerregel nach dem Fehlschlagen einer Anfrage ausgeführt wird, hat sie keine Anfrage- oder Antwortphase. Ihre Schritte werden immer direkt ausgeführt. Wenn Sie mode für eine Fehlerregel festlegen, protokolliert das Tool eine Warnung und ignoriert das Feld.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
alwaysEnforce |
Wenn true, wird die Standardfehlerregel immer erzwungen. |
false |
Nein |
Ziel
Wird in der targets-Liste einer Vorlage verwendet.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Name des Ziels. Wird von der target einer Route referenziert. |
– | Ja |
url |
Die Backend-URL. | – | Nein |
auth |
Das Authentifizierungsschema für ein Google Cloud-Backend, z. B. GoogleAccessToken oder GoogleIDToken. |
– | Nein |
scopes |
Eine Liste der anzufordernden OAuth-Bereiche. Gilt, wenn auth festgelegt ist. |
[] |
Nein |
aud |
Die Zielgruppe für das Token. Gilt, wenn auth festgelegt ist. |
– | Nein |
proxyTarget
Wird in den defaultTarget und targets eines Features und in einem kompilierten Proxy verwendet. Erweitert target um die Verarbeitung von Abläufen und Überschreibungen für Rohverbindungen.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
flows |
Eine Liste von Abläufen, die für die Zielanfrage oder -antwort ausgeführt werden. | [] |
Nein |
faultRules |
Eine Liste von Abläufen, die als Fehlerregeln verwendet werden. | [] |
Nein |
defaultFaultRule |
Eine Fehlerregel. | – | Nein |
httpTargetConnection |
Eine Rohdarstellung des HTTPTargetConnection-Elements für die erweiterte Konfiguration. Wenn festgelegt, hat es Vorrang vor url, auth, scopes und aud. |
– | Nein |
localTargetConnection |
Eine Rohdarstellung eines LocalTargetConnection-Elements.
Wenn diese Option festgelegt ist, hat sie Vorrang vor einer HTTP-Verbindung. |
– | Nein |
Richtlinie
Eine Richtlinie wird in einem Feature definiert. Die Konfiguration wird unter content mit der Attribut-/Textkonvention geschrieben, die unter Konvention für Richtlinieninhalte beschrieben wird.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Richtlinienname. | – | Ja |
type |
Der Apigee-Richtlinientyp, z. B. VerifyAPIKey, SpikeArrest oder Javascript. Muss mit dem einzelnen Schlüssel der obersten Ebene in content übereinstimmen. |
– | Ja |
content |
Ein Dictionary mit einem einzelnen Schlüssel, der type entspricht. Der verschachtelte Wert beschreibt die XML der Richtlinie gemäß der folgenden Konvention. |
{} |
Ja |
Konvention für Richtlinieninhalte
Apigee-Richtlinien sind XML-Dateien. In YAML stellen Sie diese XML-Datei in content mit den folgenden Regeln dar:
- Das
content-Wörterbuch hat genau einen Schlüssel, der mit demtypeder Richtlinie übereinstimmen muss. - Elementattribute werden unter einem
metadata-Schlüssel aufgeführt. - Elementtext wird unter dem Schlüssel
_textangegeben. Aus<Foo bar="baz">qux</Foo>wird beispielsweiseFoo: {metadata: {bar: "baz"}, _text: "qux"}. Wenn ein Element nur Text und keine Attribute hat, können Sie den Text direkt als Wert schreiben. - Untergeordnete Elemente sind unter ihrem Tag-Namen verschachtelt. Wiederholte Tags werden zu einer Liste.
Beispiel für eine Feature-Richtlinie:
policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
wird in diese Richtlinien-XML kompiliert:
<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey"> <APIKey ref="request.header.x-api-key"></APIKey> <DisplayName>VA-VerifyAPIKey</DisplayName> </VerifyAPIKey>
Ressource
Eine Ressource ist eine Datei, die ein Feature zum Bundle beiträgt, z. B. eine JavaScript-Datei oder eine Attributdatei.
| Name | Beschreibung | Standard | Erforderlich/Optional? |
|---|---|---|---|
name |
Der Dateiname, z. B. hello-world.js. Wenn das Feature ein uid festlegt, stellt die Befehlszeile dem Ressourcennamen während der Kompilierung UID- voran. Andernfalls verwendet die Befehlszeile den Namen so, wie er geschrieben ist. |
– | Ja |
type |
Der Ressourcentyp, der das Unterverzeichnis im Bundle bestimmt, z. B. jsc (JavaScript) oder properties. |
– | Ja |
content |
Der Inhalt der Rohdatei. | – | Nein |
Felder, die in dieser Version nicht unterstützt werden
pathsfür einen Parameter (JSONPath). Die Verwendung führt zu einem Kompilierungsfehler.testsfür ein beliebiges Dokument. Das Feld wird akzeptiert, aber ignoriert und nicht in das generierte Bundle aufgenommen.
Limits
Das generierte API-Proxy-Bundle darf unkomprimiert nicht größer als 10 MiB sein und nicht mehr als 256 Dateien enthalten.