Informationen zu Pfadvorlagen
In API Gateway können eingehende Anfragen anhand von Pfadvorlagen weitergeleitet werden. Pfadvorlagen bestehen aus drei Hauptkomponenten:
- Genaue Übereinstimmung
- Übereinstimmung mit einem Platzhalter
- Doppelter Platzhalter
In den folgenden Abschnitten werden die einzelnen Komponenten und ihre Funktionsweise im Kontext von API Gateway beschrieben.
Genaue Übereinstimmung
Ein Vorlagenpfad ohne ein oder doppeltes Platzhaltersegment (*
oder **
) wird in eine genaue Pfadübereinstimmung konvertiert.
Die OpenAPI-Spezifikation für Ihre Gateway-API-Konfiguration kann beispielsweise einen Abschnitt wie den folgenden enthalten:
...
paths:
/shelves:
get:
summary: List shelves
...
In diesem Beispiel akzeptiert das Gateway nur Anfragen an /shelves
und keine anderen Pfade.
Einzelner Platzhalterabgleich
Wenn ein Vorlagenpfad eine Variable, ein einzelnes Platzhaltersegment (z. B. {var}
oder {var=*}
) oder beides enthält, erlaubt das Gateway eingehende Anfragen, die Folgendes erfüllen:
- Die Anfragen enthalten keinen zusätzlichen Schrägstrich (
/
), d. h., die Variable entspricht nur einem einzelnen Pfadsegment. - Die Anfragen enthalten mindestens ein Zeichen.
- Die Anfragen können einen zusätzlichen Schrägstrich enthalten, sofern dieser am Ende des Pfads vorhanden ist.
Die OpenAPI-Spezifikation für Ihre Gateway-API-Konfiguration kann beispielsweise einen Abschnitt wie den folgenden enthalten:
...
paths:
/shelves/{shelf}/books/{book}: # Equivalent to /shelves/{shelf=*}/books/{book=*}
get:
summary: Retrieve a book
...
In diesem Beispiel akzeptiert das Gateway Anfragen, die mit dem folgenden regulären Ausdruck übereinstimmen:
^/shelves/[^/]+/books/[^/]+/?$
Doppelter Platzhalterabgleich
Wenn ein Vorlagenpfad eine Variable enthält, die durch ein doppeltes Platzhaltersegment gekennzeichnet ist (z. B. {var=**}
), erlaubt das Gateway eingehende Anfragen, die Folgendes erfüllen:
- Die Anfragen können alle Zeichen enthalten, einschließlich Schrägstrichen (/).
- Die Anfragen können 0 oder mehr Zeichen enthalten.
- Die Anfragen können einen zusätzlichen Schrägstrich enthalten, sofern dieser am Ende des Pfads vorhanden ist.
Die OpenAPI-Spezifikation für Ihre Gateway-API-Konfiguration kann beispielsweise einen Abschnitt wie den folgenden enthalten:
...
paths:
/shelves/{shelf=*}/books/{book=**}:
get:
summary: Retrieve a book
...
In diesem Beispiel akzeptiert das Gateway Anfragen, die mit dem folgenden regulären Ausdruck übereinstimmen:
^/shelves/[^/]+/books/.*/?$
URL-codierte Schrägstriche
API Gateway entspricht RFC 3986. In diesem Fall werden URL-codierte Schrägstriche (%2F
) beim Abgleich von URL-Pfaden für Routing- oder Sicherheitsentscheidungen nicht als tatsächliche Schrägstriche behandelt. Wenn URL-codierte Schrägstriche erwartet werden, sollte Ihr Back-End diese Anfragen entsprechend verarbeiten.
Betrachten Sie beispielsweise die folgende OpenAPI-Spezifikation:
securityDefinitions:
api_key:
type: "apiKey"
name: "key"
in: "query"
paths:
/shelves/{shelf}:
get:
parameters:
- in: path
name: shelf
type: string
required: true
description: Shelf ID.
summary: List shelves
operationId: GetShelf
responses:
'200':
description: A successful response
schema:
type: string
/shelves/{shelf}/books/{book}:
get:
parameters:
- in: path
name: shelf
type: string
required: true
description: Shelf ID.
- in: path
name: book
type: string
required: true
description: Book ID
summary: Retrieve a book
operationId: GetBook
responses:
'200':
description: A successful response
schema:
type: string
security:
- api_key: []
In diesem Beispiel ist für den /shelves/{shelf}/books/{book}
-Vorgang ein API-Schlüssel erforderlich. Der /shelves/{shelf}
-Vorgang ist jedoch nicht eingeschränkt.
Wenn ein Nutzer eine Anfrage an /shelves/shelf_1%2Fbooks%2Fbook_2
sendet:
- Das Gateway verarbeitet die Anfrage als
GetShelf
-Vorgang für die Shelf-IDshelf_1%2Fbooks%2Fbook_2
. In diesem Fall wird die Prüfung des API-Schlüssels nicht erzwungen. - Wenn
%2F
vor der Verarbeitung von Anfragen durch das Back-End normalisiert wird, kann die Anfrage stattdessen alsGetBook
-Vorgang für die Buch-IDbook_2
verarbeitet werden. Mit anderen Worten, das Back-End verarbeitet/shelves/shelf_1%2Fbooks%2Fbook_2
als/shelves/shelf_1/books/book_2
.
In diesem Beispiel erwartet das Back-End, dass der Vorgang GetBook
am Gateway eine Prüfung des API-Schlüssels durchführt. Da das Gateway die Anfrage jedoch als GetShelf
-Vorgang gelesen hat, wurde keine API-Schlüsselprüfung durchgeführt.
Normalisierung mehrerer benachbarter Schrägstriche
API Gateway entspricht RFC 3986. Dieser besagt, dass Pfade mit mehreren angrenzenden Schrägstrichen als ein anderer Pfad behandelt werden als Pfade mit einzelnen Schrägstrichen.
Beispielsweise wird eine Anfrage, die /shelves///
enthält, nicht vom Gateway normalisiert auf den Anfragepfad /shelves/
vor dem Abgleich einer URI-Pfadvorlage nor bei der Weiterleitung an das angegebene Back-End.