Pfadvorlagen

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

  • Genaue Übereinstimmung
  • Einzelne Platzhalterübereinstimmung
  • Doppelte Platzhalterübereinstimmung

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 exakte Pfadübereinstimmung 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.

Abgleich mit einem einzelnen Platzhalter

Wenn ein Vorlagenpfad eine Variable, ein einzelnes Platzhaltersegment ({var}) oder nur in OpenAPI 2.0 ein einzelnes Platzhaltersegment ({var=*}) 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 nachgestellten Schrägstrich 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/[^/]+/?$

Abgleich mit doppelten Platzhaltern

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 nachgestellten Schrägstrich 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:

OpenAPI 2.0

...
paths:
  /shelves/{shelf=*}/books/{book=**}:
    get:
      summary: Retrieve a book
...

OpenAPI 3.x

...
paths:
  /shelves/{shelf}/books/{book}:
    get:
      summary: Retrieve a book
      parameters:
      - name: shelf
        in: path
        schema:
          type: string
      - name: book
        in: path
        schema:
          type: string
        x-google-parameter:
          pattern: '**'
...

In diesem Beispiel akzeptiert das Gateway Anfragen, bei denen der Parameter book mit beliebigen Zeichen übereinstimmt, einschließlich Schrägstrichen. Das entspricht dem folgenden regulären Ausdruck:

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

URL-codierte Schrägstriche

API Gateway folgt RFC 3986, in der 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 Ablage-ID shelf_1%2Fbooks%2Fbook_2. In diesem Fall wird keine API-Schlüsselprüfung erzwungen.
  • Wenn %2F vor der Anfragebearbeitung durch das Back-End normalisiert wird, kann die Anfrage stattdessen als GetBook-Vorgang für die Buch-ID book_2 verarbeitet werden. Das bedeutet, dass das Backend /shelves/shelf_1%2Fbooks%2Fbook_2 als /shelves/shelf_1/books/book_2 verarbeitet.

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 angrenzender Schrägstriche

API Gateway folgt RFC 3986, in der festgelegt ist, dass Pfade mit mehreren angrenzenden Schrägstrichen als ein anderer Pfad als Pfade mit einzelnen Schrägstrichen behandelt werden.

Eine Anfrage mit /shelves/// wird beispielsweise nicht vom Gateway normalisiert, bevor sie mit einer URI-Pfadvorlage abgeglichen oder an das angegebene Backend weitergeleitet wird./shelves/