Comprendre la modélisation des chemins

Dans API Gateway, il est possible d'acheminer les requêtes entrantes en fonction de la modélisation de chemin d'accès. La modélisation de chemin d'accès comporte trois composants principaux :

• Correspondance exacte
• Correspondance avec un seul caractère générique
• Correspondance avec caractère générique double

Les sections suivantes décrivent chacun de ces composants et leur fonctionnement dans le contexte d'API Gateway.

Mot clé exact

Un chemin modélisé sans segment à caractère générique simple ou double (* ou **) est converti en correspondance exacte du chemin. Par exemple, la spécification OpenAPI de votre configuration d'API de passerelle peut contenir une section semblable à celle-ci :

...
paths:
  /shelves:
    get:
      summary: List shelves
...

Dans cet exemple, la passerelle n'acceptera que les requêtes adressées à /shelves et à aucun autre chemin d'accès.

Remarque : Les barres obliques encodées en URL (%2F) ne seront pas traitées comme des barres obliques réelles, ce qui signifie que %2Fshelves ne correspondra pas à l'opération OpenAPI décrite plus haut dans la spécification.

Mise en correspondance de caractères génériques simples

Si un chemin modélisé contient une variable, un segment générique unique ({var}) ou, dans OpenAPI 2.0 uniquement, un segment générique unique ({var=*}), la passerelle autorise les requêtes entrantes qui respectent les conditions suivantes :

• Les requêtes ne contiennent pas de barre oblique supplémentaire (/), ce qui signifie que la variable ne correspondra qu'à un seul segment de chemin.
• Les demandes contiennent au moins un caractère.
• Les requêtes peuvent contenir une barre oblique supplémentaire à la fin du chemin, le cas échéant.

Remarque : Pour l'expansion des variables, tous les caractères, à l'exception de [-_.~/0-9a-zA-Z], sont encodés en pourcentage.

Par exemple, la spécification OpenAPI de votre configuration d'API de passerelle peut contenir une section semblable à celle-ci :

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

Dans cet exemple, la passerelle accepte les requêtes correspondant à l'expression régulière suivante :

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

Remarque : Si vous utilisez une spécification OpenAPI 3.x, la syntaxe /shelves/{shelf=*}/books/{book=*} n'est pas acceptée et sera rejetée.

Mise en correspondance de caractères génériques doubles

Si un chemin modélisé contient une variable désignée par un double segment générique (par exemple {var=**}), la passerelle autorise les requêtes entrantes qui respectent les conditions suivantes :

• Les requêtes peuvent contenir tous les caractères, y compris les barres obliques (/).
• Les requêtes peuvent contenir zéro caractère ou plus.
• Les requêtes peuvent contenir une barre oblique supplémentaire si elle est présente à la fin du chemin.

Remarque : Si vous utilisez une spécification OpenAPI 3.x, la syntaxe à double caractère générique n'est pas acceptée. Pour les spécifications OpenAPI 2.0, les variables à double caractère générique ne peuvent être utilisées que dans le dernier segment du chemin fourni. Cela signifie que /shelves/{shelf=**}/books/{book=**} n'est pas autorisé, car {shelf=**} n'est pas déclaré dans le dernier segment du chemin d'accès. Pour l'expansion des variables, tous les caractères, à l'exception de [-_.~/0-9a-zA-Z], sont encodés en pourcentage.

Par exemple, la spécification OpenAPI de votre configuration d'API de passerelle peut contenir une section semblable à celle-ci :

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: '**'
...

Dans cet exemple, la passerelle accepte les requêtes dans lesquelles le paramètre book correspond à n'importe quel caractère, y compris les barres obliques. Cela correspond à l'expression régulière suivante :

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

Barres obliques encodées en URL

API Gateway suit la norme RFC 3986, qui ne traite pas les barres obliques encodées en URL (%2F) comme des barres obliques réelles lors de la mise en correspondance des chemins d'URL pour les décisions de routage ou de sécurité. Si des barres obliques encodées en URL sont attendues, votre backend doit gérer ces requêtes en conséquence.

Avertissement : Si votre backend s'attend à ce que les barres obliques encodées en URL (%2F) soient traitées comme des barres obliques réelles lors de la mise en correspondance des modèles de chemin d'accès API Gateway, les requêtes contenant des barres obliques encodées en URL peuvent correspondre à des opérations inattendues et entraîner un accès avec droits trop élevés aux ressources de backend.

Par exemple, considérons les spécifications OpenAPI suivantes :

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: []

Dans cet exemple, l'opération /shelves/{shelf}/books/{book} nécessite une clé API, mais l'opération /shelves/{shelf} n'est pas limitée.

Dans le cas où un utilisateur envoie une requête à /shelves/shelf_1%2Fbooks%2Fbook_2 :

• La passerelle traitera la requête comme une opération GetShelf pour l'ID de rayon shelf_1%2Fbooks%2Fbook_2. Dans ce cas, la vérification de la clé API n'est pas appliquée.
• Si le %2F est normalisé avant toute gestion des requêtes par le backend, la requête peut être traitée comme l'opération GetBook pour l'ID de livre book_2. En d'autres termes, le backend traite /shelves/shelf_1%2Fbooks%2Fbook_2 comme /shelves/shelf_1/books/book_2.

Dans cet exemple, le backend s'attend à ce que l'opération GetBook effectue une vérification de la clé API au niveau de la passerelle. Toutefois, comme la passerelle a lu la requête comme une opération GetShelf, aucune vérification de la clé API n'a été effectuée.

Normalisation de plusieurs barres obliques adjacentes

API Gateway suit la norme RFC 3986, qui stipule que les chemins comportant plusieurs barres obliques adjacentes seront traités comme des chemins différents de ceux comportant une seule barre oblique.

Par exemple, une requête contenant /shelves/// ne sera pas normalisée par la passerelle vers le chemin de requête /shelves/ avant de correspondre à un modèle de chemin d'URI ni lors du transfert vers le backend spécifié.

Avertissement : Si votre backend normalise les chemins d'URL en fusionnant plusieurs barres obliques en une seule, les requêtes contenant plusieurs barres obliques adjacentes peuvent correspondre à des opérations de passerelle inattendues et entraîner un accès avec droits trop élevés à vos ressources backend.