Referenz zur YAML-Konfiguration von API-Proxy

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 gateway und schemaVersion validiert. 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:

  1. Wenn die parameters-Liste der Vorlage einen Eintrag enthält, dessen name übereinstimmt und dessen default nicht leer ist, verwendet die Befehlszeile diesen Wert. Wenn das Feature einen uid festlegt, muss der Name des Vorlageneintrags FEATURE_NAME.UID.PARAMETER_NAME lauten.
  2. Andernfalls verwendet die Befehlszeile den default des Feature-Parameters.
  3. 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 dem type der Richtlinie übereinstimmen muss.
  • Elementattribute werden unter einem metadata-Schlüssel aufgeführt.
  • Elementtext wird unter dem Schlüssel _text angegeben. Aus <Foo bar="baz">qux</Foo> wird beispielsweise Foo: {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

  • paths für einen Parameter (JSONPath). Die Verwendung führt zu einem Kompilierungsfehler.
  • tests fü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.

Nächste Schritte