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-ID shelf_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 als GetBook-Vorgang für die Buch-ID book_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.