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-Funktionsvorlagen beschrieben: die Dokumenttypen template, feature und proxy sowie alle ihre Felder. Eine konzeptionelle Einführung finden Sie unter Proxy mit YAML konfigurieren. Eine Anleitung finden Sie unter API-Proxy aus einer YAML-Vorlage erstellen.

Konventionen

  • Feldnamen werden in CamelCase geschrieben. Beispiel: schemaVersion, basePath, displayName, faultRules, defaultFaultRule, httpTargetConnection.
  • Das Schema ist streng. Unbekannte Felder führen beim Importieren der Datei zu einem 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.

Häufig verwendete Felder der obersten Ebene

Jedes template-, feature- und proxy-Dokument beginnt mit den folgenden Feldern.

Name Beschreibung Standard Erforderlich/Optional?
gateway Das Zielgateway. 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 Funktionen während der Kompilierung angewendet werden. Niedrigere Zahlen werden zuerst angewendet. 100 Nein

Dokumenttyp: Vorlage

Eine Vorlage ist der Einstiegspunkt, den Sie importieren. Sie setzt sich aus Funktionen zusammen und definiert die Endpunkte und Routen des Proxys. Eine Vorlage enthält keine Richtlinien oder Ressourcen. Diese stammen aus den Funktionen, auf die sie verweist.

Name Beschreibung Standard Erforderlich/Optional?
features Eine Liste der Namen von Feature-Dateien, die in den Proxy aufgenommen werden sollen. Jeder Name muss in eine Datei im selben Verzeichnis wie die Vorlage aufgelöst werden. [] Nein
parameters Eine Liste von Parameter-Werten, die Standardwerte für die Funktionen liefern. [] Nein
endpoints Eine Liste von Endpunkten, die Basispfade und Routen definieren. [] Nein
targets Eine Liste von Zielen, die Backend-Verbindungen definieren. [] Nein

Dokumenttyp: Funktion

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 gemeinsamen Feldern der obersten Ebene hat ein Feature die folgenden Felder.

Name Beschreibung Standard Erforderlich/Optional?
displayName Ein für Menschen lesbarer Anzeigename. – Nein
uid Eine eindeutige Kennung, die zum Namespace der Richtlinien und Ressourcen des Features verwendet wird. Wenn kein Wert angegeben ist, wird name verwendet. – Nein
documentation Erweiterte Dokumentation für die Funktion. – Nein
categories Eine Liste mit Kategorielabels mit freiem Format. [] Nein
parameters Eine Liste der Parameter, die vom Feature definiert werden. [] Nein
defaultEndpoint Ein Proxy-Endpunkt, dessen Abläufe und Standardfehlerregel in jeden Endpunkt des kompilierten Proxys eingefügt werden. Verwenden Sie diese Option, um die Richtlinien eines Features an den Anfrage- oder Antwortablauf anzuhängen. – Nein
defaultTarget Ein Proxy-Ziel, das als Standard-Backend-Verbindung verwendet wird. – Nein
endpoints Eine Liste der Proxy-Endpunkte, die dem Proxy hinzugefügt werden sollen. Ein Endpunkt mit demselben Namen wie ein vorhandener Endpunkt ersetzt diesen. [] Nein
targets Eine Liste der Proxy-Ziele, 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 das Feature bietet. Richtliniennamen werden während der Kompilierung automatisch mit dem uid (oder name) des Features versehen. [] Nein
resources Eine Liste der Ressourcen, die das Feature bereitstellt, z. B. JavaScript- oder Eigenschaftendateien. [] Nein

Dokumenttyp: Proxy

Ein Proxy ist das vollständig aufgelöste Dokument, das von der CLI erstellt wird, wenn sie eine Vorlage mit ihren Funktionen kompiliert. Normalerweise erstellen Sie diesen Typ nicht direkt. Er wird hier beschrieben, weil er die Form des API-Proxy-Bundles ist.

Ein Proxy hat dieselben Felder wie eine Funktion, verwendet jedoch endpoints und targets (nicht defaultEndpoint oder defaultTarget) und stellt immer einen vollständigen, bereitstellbaren Proxy dar. type ist proxy.

Verschachtelte Objekte

Parameter

Ein Parameter liefert einen Wert für ein Feature. Der Wert eines Parameters wird in seinen default aufgelöst.

Name Beschreibung Standard Erforderlich/Optional?
name Der Parametername. Wird in Funktionsinhalten als {name} referenziert. – Ja
displayName Ein für Menschen lesbarer Name. – Nein
description Eine Beschreibung des Parameters. – Nein
default Der Standardwert. Wird in den Strings der Funktion durch {name} ersetzt. – Nein
examples Eine Liste mit Beispielwerten. [] Nein
maps Eine Zuordnung von Wert-Ersetzungen. 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 diesem Release 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 einer Funktion und in einem kompilierten Proxy verwendet. Erweitert endpoint 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 Container für generische Abläufe platziert. [] Nein
postClientFlow Ein einzelner Ablauf, der ausgeführt wird, nachdem die Antwort an den Client gesendet wurde. – Nein
faultRules Eine Liste der Abläufe, 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 Standardanfrage-/Antwortabläufe. – Ja
mode Request oder Response. Legt fest, 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 in einem Ablauf 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 den Ablauf um ein zusätzliches 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 Back-End-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 des Tokens. Gilt, wenn auth festgelegt ist. – Nein

proxyTarget

Wird in den defaultTarget- und targets-Attributen eines Features und in einem kompilierten Proxy verwendet. Erweitert target um die Verarbeitung von Flows und Überschreibungen für Rohverbindungen.

Name Beschreibung Standard Erforderlich/Optional?
flows Eine Liste der Abläufe, die für die Zielanfrage oder -antwort ausgeführt werden. [] Nein
faultRules Eine Liste der Abläufe, die als Fehlerregeln verwendet werden. [] Nein
defaultFaultRule Eine Fehlerregel. – Nein
httpTargetConnection Eine Rohdarstellung des HTTPTargetConnection-Elements für die erweiterte Konfiguration. Wenn dieser Wert festgelegt ist, hat er Vorrang vor url, auth, scopes und aud. – Nein
localTargetConnection Eine Rohdarstellung eines LocalTargetConnection-Elements. Wenn festgelegt, hat sie Vorrang vor einer HTTP-Verbindung. – Nein

Richtlinie

Eine Richtlinie wird in einer Funktion definiert. Die Konfiguration wird unter content mit der in Konvention für Richtlinieninhalte beschriebenen Attribut-/Textkonvention geschrieben.

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 Wörterbuch mit einem Schlüssel, der type entspricht. Der verschachtelte Wert beschreibt das XML der Richtlinie gemäß der Konvention unten. {} Ja

Konvention für Richtlinieninhalte

Apigee-Richtlinien sind XML. In YAML stellen Sie XML in content mit diesen 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 angegeben.
  • Elementtext wird unter einem _text-Schlüssel angegeben. Aus <Foo bar="baz">qux</Foo> wird beispielsweise Foo: {metadata: {bar: "baz"}, _text: "qux"}. Wenn ein Element nur Text und keine Attribute enthält, können Sie den Text direkt als Wert schreiben.
  • Untergeordnete Elemente sind unter ihrem Tag-Namen verschachtelt. Wiederholte Tags werden zu einer Liste.

Beispiel:

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 diesen Richtlinien-XML-Code 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 von einem Modul zum Bundle beigetragen wird, z. B. eine JavaScript-Datei oder eine Properties-Datei.

Name Beschreibung Standard Erforderlich/Optional?
name Der Dateiname, z. B. hello-world.js. Ressourcennamen haben bei der Kompilierung das Präfix uid (oder name) des Features. – Ja
type Der Ressourcentyp, der das Unterverzeichnis im Bundle bestimmt, z. B. jsc (JavaScript) oder properties. – Ja
content Der Rohinhalt der Datei. – Nein

In diesem Release nicht unterstützte Felder

  • paths für einen Parameter (JSONPath). Die Verwendung führt dazu, dass die Kompilierung fehlschlägt.
  • tests in einem beliebigen Dokument. Das Feld wird akzeptiert, aber ignoriert und ist nicht im generierten Bundle enthalten.

Limits

Das generierte API-Proxy-Bundle darf unkomprimiert nicht größer als 10 MiB sein und darf nicht mehr als 256 Dateien enthalten.

Nächste Schritte