Comprendre la modélisation de chemin d'accès
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 générique unique
- Correspondance avec un 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 d'accès modélisé sans segment avec caractère générique unique ou double (*
ou **
) est converti en correspondance exacte.
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'accepte que les requêtes envoyées à /shelves
et à aucun autre chemin.
Mise en correspondance de caractères génériques unique
Si un chemin modélisé contient une variable, un segment générique unique (par exemple, {var}
ou {var=*}
), ou les deux, 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 requêtes contiennent au moins un caractère.
- Les requêtes peuvent contenir une barre oblique supplémentaire si elle se trouve à la fin du chemin.
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}: # Equivalent to /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/[^/]+/?$
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 ou plusieurs caractères.
- Les requêtes peuvent contenir une barre oblique supplémentaire si elle se trouve à la fin du chemin.
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/.*/?$
Barres obliques encodées sous forme d'URL
API Gateway respecte la norme RFC 3986, qui ne traite pas les barres obliques encodées au format URL (%2F
) comme de véritables barres obliques lors de la mise en correspondance des chemins d'URL pour des décisions de routage ou de sécurité. Si des barres obliques encodées au format URL sont attendues, votre backend doit gérer ces requêtes en conséquence.
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 restreinte.
Dans le cas où un utilisateur envoie une requête à /shelves/shelf_1%2Fbooks%2Fbook_2
:
- La passerelle traitera la requête en tant qu'opération
GetShelf
pour l'ID d'étagèreshelf_1%2Fbooks%2Fbook_2
. Dans ce cas, la vérification des clés API n'est pas appliquée. - Si le
%2F
est normalisé avant tout traitement de requête par le backend, la requête peut être traitée à la place en tant qu'opérationGetBook
pour l'ID de livrebook_2
. En d'autres termes, le backend traite/shelves/shelf_1%2Fbooks%2Fbook_2
en tant que/shelves/shelf_1/books/book_2
.
Dans cet exemple, le backend s'attend à ce que l'opération GetBook
effectue une vérification des clés API au niveau de la passerelle. Cependant, comme la passerelle a lu la requête comme une opération GetShelf
, aucune vérification de clé API n'a été effectuée.
Normalisation de plusieurs barres obliques adjacentes
API Gateway suit le document RFC 3986, qui stipule que les chemins comportant plusieurs barres obliques adjacentes seront traités comme un chemin différent de ceux contenant des barres obliques singuliers.
Par exemple, une requête contenant /shelves///
ne sera pas normalisée par la passerelle vers le chemin de requête /shelves/
avant de faire correspondre un modèle de chemin d'URI nor lors de son transfert vers le backend spécifié.