Informationen zu Pfadvorlagen

In API Gateway können eingehende Anfragen basierend auf Pfad-Templates weitergeleitet werden. Pfadvorlagen haben drei Hauptkomponenten:

  • Genaue Übereinstimmung
  • Einzelne Platzhalterübereinstimmung
  • Doppelter Platzhalter

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 einen genau übereinstimmenden Pfad umgewandelt. 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.

Übereinstimmung mit einem einzelnen Platzhalter

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 am Ende des Pfads enthalten, wenn 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 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ägstrichen (/).
  • Die Anfragen können null oder mehr Zeichen enthalten.
  • Die Anfragen können einen zusätzlichen Schrägstrich am Ende des Pfads enthalten, wenn 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 dem folgenden regulären Ausdruck entsprechen:

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

URL-codierte Schrägstriche

API Gateway folgt RFC 3986, in dem URL-codierte Schrägstriche (%2F) beim Abgleich von URL-Pfaden für Routing- oder Sicherheitsentscheidungen nicht als tatsächliche Schrägstriche behandelt werden. Wenn URL-codierte Schrägstriche erwartet werden, sollte Ihr Backend 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 Vorgang /shelves/{shelf}/books/{book} ein API-Schlüssel erforderlich, der Vorgang /shelves/{shelf} ist jedoch uneingeschrä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 Regal-ID shelf_1%2Fbooks%2Fbook_2. In diesem Fall wird die API-Schlüsselprüfung nicht erzwungen.
  • Wenn die %2F vor der Anfragebearbeitung durch das Backend normalisiert wird, wird die Anfrage möglicherweise als GetBook-Vorgang für die Buch-ID book_2 verarbeitet. Mit anderen Worten: Das Backend verarbeitet /shelves/shelf_1%2Fbooks%2Fbook_2 als /shelves/shelf_1/books/book_2.

In diesem Beispiel erwartet das Backend, 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 benachbarter Schrägstriche

API Gateway folgt RFC 3986, in dem festgelegt ist, dass Pfade mit mehreren aufeinanderfolgenden Schrägstrichen als ein anderer Pfad als Pfade mit einzelnen Schrägstrichen behandelt werden. Eine Anfrage, die /shelves/// enthält, wird beispielsweise nicht vom Gateway normalisiert zum Anfragepfad /shelves/, bevor sie mit einer URI-Pfadvorlage abgeglichen wird, noch bei der Weiterleitung an das angegebene Backend.