Informationen zu Pfadvorlagen

In API Gateway ist es möglich, eingehende Anfragen basierend auf Pfadvorlagen weiterzuleiten. Pfadvorlagen haben drei Hauptkomponenten:

  • Genaue Übereinstimmung
  • Einzelner Platzhalterabgleich
  • Doppelter Platzhalterabgleich

In den folgenden Abschnitten werden die einzelnen Komponenten und ihre Funktionsweise im Kontext von API Gateway beschrieben.

Genaue Übereinstimmung

Ein Vorlagenpfad ohne einzelne oder doppelte Platzhaltersegmente (* 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 Anfrage enthält mindestens ein Zeichen.
  • Die Anfragen können einen zusätzlichen abschließenden Schrägstrich enthalten, wenn sie am Ende des Pfads vorhanden sind.

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 dem folgenden regulären Ausdruck entsprechen:

^/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ägstriche (/).
  • Die Anfragen können 0 oder mehr Zeichen enthalten.
  • Die Anfragen können einen zusätzlichen abschließenden Schrägstrich enthalten, wenn sie am Ende des Pfads vorhanden sind.

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 dem folgenden regulären Ausdruck entsprechen:

^/shelves/[^/]+/books/.*/?$

URL-codierte Schrägstriche

API Gateway folgt RFC 3986, das beim URL-Pfad für Routing- oder Sicherheitsentscheidungen keine URL-codierten Schrägstriche (%2F) 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 uneingeschränkt.

Für den Fall, dass ein Nutzer eine Anfrage an /shelves/shelf_1%2Fbooks%2Fbook_2 sendet, gilt Folgendes:

  • Das Gateway verarbeitet die Anfrage als GetShelf-Vorgang für die Shelf-ID shelf_1%2Fbooks%2Fbook_2. In diesem Fall wird eine API-Schlüsselprüfung nicht erzwungen.
  • Wenn %2F normalisiert wurde, bevor eine Anfrage vom Back-End verarbeitet 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 eine API-Schlüsselprüfung am Gateway durchführt. Da das Gateway die Anfrage jedoch als GetShelf-Vorgang gelesen hat, wurde keine API-Schlüsselprüfung durchgeführt.

Normalisierung mehrerer angrenzender Schrägstriche

API Gateway folgt RFC 3986. Dies bedeutet, dass Pfade mit mehreren angrenzenden Schrägstrichen als ein anderer Pfad behandelt werden als Pfade mit einzelnen Schrägstrichen. Beispielsweise wird eine Anfrage mit /shelves/// vom Gateway weder vor dem Abgleich mit einer URI-Pfadvorlage, noch bei der Weiterleitung an das angegebene Back-End in den Anfragepfad /shelves/ normalisiert.