Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Envoyez du trafic vers vous APIs via votre nom de domaine personnalisé dans API Gateway
Lorsque vous configurez le mode de routage pour votre nom de domaine personnalisé, vous définissez la manière dont le trafic entrant est dirigé vers votre APIs. Vous envoyez du trafic à votre adresse à APIs l'aide de règles de routage, de mappages d'API ou de règles de routage et de mappages d'API. La section suivante explique quand utiliser des règles de routage et des mappages d’API, et comment définir le mode de routage de votre nom de domaine personnalisé.
## Quand utiliser des règles de routage
Lorsque vous utilisez des règles de routage, vous dirigez les demandes entrantes répondant à certaines conditions vers des APIs étapes REST spécifiques. Par exemple, une règle peut acheminer une demande vers l’étape `production` de votre API REST `users` si elle contient l’en-tête `version:v1` et le chemin de base `/users`. Utilisez les règles de routage pour créer des topologies de routage dynamiques avancées qui prennent en charge des cas d'utilisation tels que le A/B test ou l'augmentation de l'utilisation des nouvelles versions de votre APIs.
Lorsque vous acheminez le trafic vers une API REST, nous vous recommandons d’utiliser des règles de routage pour votre nom de domaine personnalisé. Vous pouvez recréer n’importe quel mappage d’API à l’aide de règles de routage. Pour de plus amples informations, veuillez consulter [Recréation d’un mappage d’API à l’aide de règles de routage](rest-api-routing-rules-recreate-api-mapping.md).
Pour REST APIs, vous pouvez également utiliser conjointement des règles de routage et des mappages d'API. Le cas échéant, API Gateway évalue toujours les règles de routage avant les mappages d’API. Utilisez conjointement des règles de routage et des mappages d’API pour migrer vos noms de domaine personnalisés actuels ou pour explorer les règles de routage.
### Considérations relatives aux règles de routage
Les considérations suivantes peuvent avoir un impact sur votre utilisation des règles de routage :
+ WebSocket ou le protocole HTTP APIs ne sont pas pris en charge comme cible APIs pour les règles de routage.
+ Si votre nom de domaine personnalisé comporte des mappages d'API à la fois vers REST et HTTP APIs, les règles de routage ne sont pas prises en charge.
+ Pour un domaine personnalisé privé, vous pouvez créer une règle de routage vers une API REST privée. Pour un domaine public personnalisé, vous pouvez créer une règle de routage vers une API régionale ou optimisée pour la périphérie.
+ Pour un domaine personnalisé privé, vous ne pouvez pas créer de règle de routage vers une API privée. Pour un nom de domaine personnalisé privé, vous ne pouvez pas créer de règle de routage vers une API publique.
## Choix entre les règles de routage et les mappages d’API
Nous vous recommandons d’utiliser les règles de routage dans la mesure du possible. Utilisez uniquement les mappages d'API pour envoyer du trafic vers un HTTP ou une WebSocket API.
# Définition du mode de routage de votre nom de domaine personnalisé
Vous pouvez choisir le mode de routage qu'API Gateway utilise pour acheminer le trafic vers votre APIs. Pour de plus amples informations, veuillez consulter [Envoyez du trafic vers vous APIs via votre nom de domaine personnalisé dans API Gateway](rest-api-routing-mode.md). Cette section décrit les modes de routage des noms de domaine personnalisés. Vous devez définir un mode de routage pour votre nom de domaine personnalisé afin d'acheminer le trafic vers votre APIs. Les modèles de routage pris en charge sont les suivants :
+ **ROUTING\$1RULE\$1THEN\$1 API\$1MAPPING** — Utilisez ce mode pour envoyer du trafic vers vous APIs avec des règles de routage et des mappages d'API. Dans ce mode, toutes les règles de routage ont la priorité sur les mappages d’API. Pour voir un exemple de ce mode, consultez [Exemple 2 : règles de routage et mappages d’API](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings).
+ **ROUTING\$1RULE\$1ONLY — Utilisez ce mode pour autoriser uniquement** les règles de routage à envoyer du trafic vers votre. APIs Lorsque votre nom de domaine personnalisé utilise ce mode, vous ne pouvez pas créer de mappage d'API, mais vous pouvez utiliser la [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html)commande pour les afficher. Les appelants de l’API ne peuvent pas utiliser de mappages d’API pour accéder à ce nom de domaine.
+ **API\$1MAPPING\$1ONLY** — Utilisez ce mode pour autoriser uniquement les mappages d'API à envoyer du trafic vers votre. APIs Si votre nom de domaine personnalisé utilise ce mode, vous ne pouvez pas créer de règles de routage, mais vous pouvez utiliser la commande `list-routing-rules` pour les afficher. Les appelants de l’API ne peuvent pas utiliser de règles de routage pour accéder à ce nom de domaine.
Il s’agit du mode de routage par défaut pour tous vos noms de domaine existants et pour tous les nouveaux noms de domaine que vous créez.
Lorsque vous créez un nom de domaine personnalisé avec `apigateway`, `API_MAPPING_ONLY` est appelé `BASE_PATH_MAPPING_ONLY` et `ROUTING_RULE_THEN_API_MAPPING` est appelé `ROUTING_RULE_THEN_BASE_PATH_MAPPING`. Ce comportement n'est présent que pour AWS CLI CloudFormation, ou aucun SDKs, pas dans le AWS Management Console.
La procédure suivante montre comment modifier le mode de routage d’un nom de domaine personnalisé existant. Lorsque vous modifiez le mode de routage de votre nom de domaine personnalisé, les appelants de l’API ne peuvent pas accéder à votre nom de domaine en utilisant des modes de routage non pris en charge.
------
#### [ AWS Management Console ]
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Noms de domaine personnalisés** dans le volet de navigation principal.
1. Choisissez un nom de domaine personnalisé.
1. Sous **Détails du domaine**, choisissez **Modifier**.
1. Pour le **mode de routage**, choisissez **API\$1MAPPINGROUTING\$1RULE\$1THEN\$1**.
1. Choisissez **Enregistrer**.
Si vous remplacez le mode de routage par `ROUTING_RULE_ONLY` ou `API_MAPPING_ONLY`, les mappages d’API ou les règles de routage que vous avez créés sont supprimés de la page Informations de nom de domaine de la console. Si vous modifiez le mode de routage pour prendre en charge soit des règles de routage soit des mappages d’API, ces ressources seront renvoyées.
------
#### [ AWS CLI - apigatewayv2 ]
La [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)commande suivante met à jour un nom de domaine pour utiliser le mode de routage `ROUTING_RULE_THEN_API_MAPPING` :
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
Le résultat se présente comme suit :
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
La [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html)commande suivante met à jour un nom de domaine personnalisé privé pour utiliser le mode de routage `ROUTING_RULE_THEN_BASE_PATH_MAPPING` :
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
Le résultat se présente comme suit :
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# Règles de routage pour connecter les étapes de l'API à un nom de domaine personnalisé pour REST APIs
Une règle de routage est un ensemble de conditions qui invoquent une action lorsqu’elles sont réunies. Par exemple, une règle peut acheminer une demande entrante d’un nom de domaine personnalisé qui contient l’en-tête `Hello:World` et le chemin de base `users` vers l’étape `production` d’une API REST.
Les règles sont évaluées par ordre de priorité. Si vous définissez le mode de routage sur `ROUTING_RULE_THEN_API_MAPPING`, API Gateway évalue toujours toutes les règles de routage avant de passer aux mappages d’API. La liste suivante décrit les conditions, les actions et les priorités d’une règle de routage.
**Conditions**
Lorsque les conditions d'une règle sont satisfaites, ses actions sont effectuées. API Gateway prend en charge jusqu’à deux conditions d’en-tête et une condition de chemin. API Gateway évalue conjointement les conditions d’en-tête et les conditions de chemin de base.
Vous pouvez créer une règle sans condition. Lorsqu’API Gateway évalue cette règle, l’action est toujours exécutée. Vous pouvez créer une règle sans condition comme règle fourre-tout.
Pour plus d’informations sur les conditions d’en-tête, consultez [Correspondance des conditions d’en-tête](#rest-api-routing-rules-condition-headers). Pour plus d’informations sur les conditions de chemin, consultez [Correspondance des conditions de chemin de base](#rest-api-routing-rules-condition-path).
**Actions**
Les actions sont le résultat de la correspondance entre les conditions et la règle de routage. Actuellement, la seule action prise en charge consiste à invoquer une étape d’une API REST.
Chaque règle peut comporter une action.
**Priority**
La priorité détermine l’ordre d’évaluation des règles, de la valeur la plus basse à la valeur la plus élevée. Les règles ne peuvent pas avoir la même priorité.
Vous pouvez définir la priorité entre 1 et 1 000 000. Si une règle a une priorité de 1, API Gateway l’évalue en premier. Lorsque vous créez une règle, nous vous recommandons d’ajouter des espaces entre les priorités. Vous pourrez ainsi modifier la priorité des règles et en ajouter de nouvelles. Pour de plus amples informations, veuillez consulter [Modification de la priorité d’une règle de routage](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority).
Pour voir des exemples d’évaluation des règles de routage par API Gateway, consultez [Exemples d’évaluation de règles de routage par API Gateway](rest-api-routing-rules-examples.md).
## Types de conditions des règles de routage API Gateway
La section suivante décrit les types de conditions des règles de routage. API Gateway applique une règle que si toutes les conditions sont réunies.
### Correspondance des conditions d’en-tête
Lorsque vous créez une condition d’en-tête, vous pouvez faire correspondre le nom de l’en-tête et la valeur globale de l’en-tête, par exemple `Hello:World`. API Gateway utilise une correspondance littérale pour valider les conditions de correspondance des en-têtes. Votre condition peut utiliser jusqu’à deux en-têtes, séparés par `AND`. Par exemple, votre condition peut être remplie si une demande entrante comprend `Hello:World` et `x-version:beta`.
La correspondance du nom de l’en-tête n’est pas sensible à la casse, mais la valeur globale de l’en-tête l’est. `Hello:World` correspond à `hello:World`, mais pas `Hello:world`.
Pour connaître la liste des valeurs d’en-tête restreintes, consultez [Restrictions](#rest-api-routing-rules-restrictions).
#### Utilisation de caractères génériques avec des conditions d’en-tête
Les caractères génériques ne peuvent être utilisés que dans la valeur globale de l’en-tête, et doivent être `*prefix-match`, `suffix-match*` ou `*contains*`. Le tableau suivant présente des exemples d’utilisation des caractères génériques pour la correspondance des conditions d’en-tête.
| Conditions d’en-tête | Demandes conformes à la règle de routage | Demandes non conformes à la règle de routage |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` et `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` et `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | Aucune |
Si vous créez des conditions pour plusieurs valeurs d’en-tête, par exemple `Accept:application/json,text/xml`, nous vous recommandons d’utiliser `*contains*` pour vos conditions d’en-tête et d’éviter de créer des conditions à l’aide de la virgule (`,`).
Étant donné qu’API Gateway fait correspondre littéralement les conditions d’en-tête, les correspondances sémantiques peuvent être acheminées différemment. Le tableau suivant montre les différence de résultat des règles de routage.
| Conditions d’en-tête | Demandes conformes à la règle de routage | Demandes non conformes à la règle de routage |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/rest-api-routing-rules.html) | Aucune |
### Correspondance des conditions de chemin de base
Lorsque vous créez une condition de chemin de base, si la demande entrante contient le chemin que vous avez spécifié, la règle correspond. La correspondance étant sensible à la casse, le chemin `New/Users` ne correspondra pas à `new/users`.
Vous ne pouvez créer une condition de chemin de base que pour un seul chemin de base.
Pour obtenir la liste des restrictions des conditions de chemin de base, consultez [Restrictions](#rest-api-routing-rules-restrictions).
#### Suppression du chemin de base avec les conditions du chemin de base
Lorsque vous créez une condition de trajectoire de base, vous pouvez choisir de supprimer la trajectoire de base. Lorsque vous supprimez le chemin de base, API Gateway supprime le chemin de base entrant correspondant lorsqu’il invoque l’API cible. C’est le même comportement que lorsque vous utilisez un mappage d’API. Si vous ne supprimez pas le chemin de base, API Gateway transmet l’intégralité du chemin de base à l’API cible. Nous vous recommandons de supprimer le chemin de base uniquement lorsque vous recréez un mappage d’API.
Le tableau suivant présente des exemples d’évaluation de la condition de suppression du chemin de base par API Gateway.
| Condition | Suppression du chemin de base | Demande entrante | Résultat |
| --- | --- | --- | --- |
| Si le chemin de base contient `PetStoreShopper/dogs` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway appelle la méthode `GET` de la ressource `/`. |
| Si le chemin de base contient `PetStoreShopper/dogs`. | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway appelle la méthode `GET` de la ressource `PetStoreShopper/dogs`. |
| Si le chemin de base contient `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway appelle la méthode `GET` de la ressource `dogs`. |
| Si le chemin de base contient `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway appelle la méthode `GET` de la ressource `PetStoreShopper/dogs`. |
| Si le chemin de base contient `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway appelle la méthode `GET` de la ressource `/` avec le paramètre de chaîne de requête `birds=available`. |
| Si le chemin de base contient `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway appelle la méthode `GET` de la ressource `/PetStoreShopper` avec le paramètre de chaîne de requête `birds=available`. |
## Restrictions
+ L'API cible et le nom de domaine personnalisé doivent se trouver dans le même AWS compte.
+ Chaque règle peut comporter une API cible.
+ Pour un nom de domaine personnalisé privé, vous ne pouvez créer une règle de routage que vers une API privée. Pour un nom de domaine personnalisé public, vous ne pouvez créer une règle de routage que vers une API publique. Vous ne pouvez pas mélanger des ressources publiques et privées.
+ Si votre nom de domaine personnalisé comporte des mappages d'API à la fois vers REST et HTTP APIs, les règles de routage ne sont pas prises en charge.
+ La priorité maximale est de 1 000 000.
+ Restrictions applicables aux en-têtes :
+ Chaque condition `anyOf` ne peut contenir qu’une seule valeur d’en-tête.
+ Les seuls caractères autorisés pour les noms d’en-tête et les valeurs globales des en-têtes sont spécifiés par [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230), à savoir `a-z`, `A-Z`, `0-9` et les caractères spéciaux suivants : `*?-!#$%&'.^_`|~`.
+ Vous pouvez utiliser un caractère générique dans la valeur globale de l’en-tête, mais celui-ci doit être `*prefix-match`, `suffix-match*` ou `*contains*`. Vous ne pouvez pas utiliser `*` au milieu d’une valeur globale d’en-tête.
+ Les noms d’en-tête génériques ne sont pas pris en charge.
+ Le nom de l’en-tête doit contenir moins de 40 caractères.
+ La valeur globale de l’en-tête doit être inférieure à 128 caractères.
+ La valeur globale de l’en-tête pour une correspondance infixe doit être inférieure à 40 caractères.
+ Les en-têtes suivants ne sont pas pris en charge en tant que conditions :
+ `access-control-*`
+ `apigw-*`
+ `Authorization`
+ `Connection`
+ `Content-Encoding`
+ `Content-Length`
+ `Content-Location`
+ `Forwarded`
+ `Keep-Alive`
+ `Origin`
+ `Proxy-Authenticate`
+ `Proxy-Authorization`
+ `TE`
+ `Trailers`
+ `Transfer-Encoding`
+ `Upgrade`
+ `x-amz-*`
+ `x-amzn-*`
+ `x-apigw-api-id`
+ `X-Forwarded-For`
+ `X-Forwarded-Host`
+ `X-Forwarded-Proto`
+ `x-restAPI`
+ `Via`
+ Restrictions applicables aux chemins de base :
+ Le nom du chemin de base doit contenir moins de 128 caractères.
+ Le chemin de base ne doit contenir que des lettres, des chiffres et les caractères suivants : `$-_.+!*'()/`.
Ces caractères ne sont pas pris en charge pour les expressions régulières.
+ Le chemin de base ne peut ni commencer ni se terminer par une barre oblique inversée (`\`).
# Exemples d’évaluation de règles de routage par API Gateway
La section suivante présente quatre exemples d’évaluation de règles de routage et de mappages d’API par API Gateway.
## Exemple 1 : règles de routage uniquement
Dans cet exemple, le mode de routage du nom de domaine personnalisé `https://petstore.example.com` est défini sur `ROUTING_RULE_ONLY`, et ce dernier possède les règles et priorités de routage suivantes.
| ID de la règle | Priority | Conditions | Action |
| --- | --- | --- | --- |
| `abc123` | 10 | Si la demande contient l’en-tête `Hello:World` | API cible 1 |
| `zzz000` | 50 | Si la demande contient les en-têtes `Accept:image/webp` et `Pet:Dog-*`, et si le chemin de base contient `PetStoreShopper` | API cible 2 |
| `efg456` | 100 | Aucune | API cible 3 |
Le tableau suivant montre comment API Gateway applique les règles de routage précédentes à des exemples de demande.
| Requête | API sélectionnée | Explication |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | API cible 1 | La demande correspond à la règle de routage `abc123`. |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | API cible 1 | API Gateway évalue toutes les règles de routage par ordre de priorité. La règle de routage `abc123` a la priorité la plus élevée et les conditions correspondent. API Gateway invoque donc l’API cible 1. Bien que les conditions de la demande correspondent également à la règle de routage `zzz000`, API Gateway n’évalue aucune autre règle de routage après avoir identifié une correspondance. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | API cible 2 | La demande correspond à la règle de routage `zzz000`. Il y a correspondance, car `Pet:Dog-Bella` correspond à la chaîne `Pet:Dog-*` |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | API cible 3 | La demande ne correspond pas à la règle de routage `abc123`. La demande ne correspond pas à la règle de routage `zzz000`, car tous les en-têtes requis ne sont pas présents. La règle de priorité suivante correspond à toutes les demandes entrantes. API Gateway invoque donc l’API cible 3. |
## Exemple 2 : règles de routage et mappages d’API
Dans cet exemple, le mode de routage du nom de domaine personnalisé `https://petstore.diagram.example.com` est défini sur `ROUTING_RULE_THEN_API_MAPPING`, et ce dernier possède les règles de routage et mappages d’API suivants.
| ID de la règle | Priority | Conditions | Action |
| --- | --- | --- | --- |
| `abc123` | 1 | Si la demande contient `pets` | Invoquer l’étape `Prod` de l’API `PetStore`. |
| `000zzz` | 5 | Si la demande contient l’en-tête `Cookie`:`*ux=beta*` et si le chemin de base contient `/refunds` | Invoquer l’étape `Beta` de l’API `Refunds`. |
Le tableau suivant présente les mappages d’API pour `https://petstore.backup.example.com`.
| Mappage d’API | API sélectionnée |
| --- | --- |
| `/refunds` | Invoquer l’étape `Prod` de l’API `Refunds`. |
| `(none)` | Invoquer l’étape `Prod` de l’API `Search`. |
Le schéma suivant montre comment API Gateway applique les règles de routage et les mappages d’API précédents à des exemples de demande. Ces exemples sont résumés dans le tableau qui suit ce schéma.
![\[Schéma d’application des règles de routage et des mappages d’API précédents par API Gateway.\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/rr-diagram.png)
Le tableau suivant montre comment API Gateway applique les règles de routage et les mappages d’API précédents à des exemples de demande.
| Requête | API sélectionnée | Explication |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | Étape `Prod` de l’API `PetStore`. | La demande correspond à la règle de routage `abc123`. |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | Étape `Beta` de l’API `Refunds`. | La demande correspond à la règle de routage `000zzz`. L’en-tête `Cookie` contient la bonne correspondance `*contains*` et le bon chemin de base pour cette condition. |
| `https://petstore.diagram.example.com/refunds` | Étape `Prod` de l’API `Refunds`. | La demande ne possède pas les en-têtes requis pour correspondre à la règle de routage `zzz000`. Si API Gateway ne parvient pas à identifier de correspondance avec la règle de routage, il passe aux mappages d’API. API Gateway peut mapper le chemin de base à l’étape `Prod` de l’API `Refunds`. |
| `https://petstore.diagram.example.com/` | Étape `Prod` de l’API `Search`. | La demande correspond au mappage de l’API vers le chemin vide `(none)`. |
## Exemple 3 : règles de routage et mappages d’API à plusieurs niveaux
Dans cet exemple, le mode de routage du nom de domaine personnalisé `https://petstore.backup.example.com` est défini sur `ROUTING_RULE_THEN_API_MAPPING`, et ce dernier possède les règles de routage et mappages d’API suivants.
Le tableau suivant présente les règles de routage pour `https://petstore.backup.example.com`.
| ID de la règle | Priority | Conditions | Action |
| --- | --- | --- | --- |
| `abc123` | 10 | Si la demande contient l’en-tête `Hello:World` | API cible 1 |
| `000zzz` | 50 | Si la demande contient les en-têtes `Accept`:`image/webp` et `Pet:Dog-*`, et si le chemin de base contient `PetStoreShopper` | API cible 2 |
Le tableau suivant présente les mappages d’API pour `https://petstore.backup.example.com`.
| Mappage d’API | API sélectionnée |
| --- | --- |
| `PetStoreShopper` | API cible 3 |
| `PetStoreShopper/cats` | API cible 4 |
Le tableau suivant montre comment API Gateway applique les règles de routage et les mappages d’API précédents à des exemples de demande.
| Requête | API sélectionnée | Explication |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | API cible 3 | La demande ne possède pas les en-têtes requis pour correspondre à la règle de routage `zzz000`. Si API Gateway ne parvient pas à identifier de correspondance avec la règle de routage, il passe aux mappages d’API. API Gateway peut mapper le chemin de base à l’API cible 3. |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | API cible 1 | La demande correspond à la règle de routage `abc123`. Si le mode de routage est défini sur `ROUTING_RULE_THEN_API_MAPPING`, les règles de routage ont toujours la priorité sur les mappages d’API. |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | Aucune | La demande ne correspond à aucune règle de routage ni à aucun mappage d’API. En l’absence de règle de routage par défaut, API Gateway rejette l’appel et envoie à l’appelant le code d’état `403 Forbidden`. |
## Exemple 4 : règles de routage pour les noms de domaine génériques
Dans cet exemple, le nom de domaine personnalisé `https://*.example.com` est un nom de domaine générique. Le caractère générique prend en charge tous les sous-domaines renvoyant vers le même domaine. Les exemples de règles de routage suivants modifient ce comportement pour permettre aux sous-domaines d'être acheminés vers une cible différente à l'aide APIs de l'`Host`en-tête.
Le tableau suivant présente les règles de routage pour `https://*.example.com`.
| ID de la règle | Priority | Conditions | Action |
| --- | --- | --- | --- |
| `abc123` | 10 | Si la demande contient l’en-tête `Host:a.example.com` | API cible 1 |
| `000zzz` | 50 | Si la demande contient l’en-tête `Host:b.example.com` | API cible 2 |
| `efg456` | 500 | Aucune | API cible 3 |
Le tableau suivant montre comment API Gateway applique les règles de routage précédentes à des exemples de demande.
| Requête | API sélectionnée | Explication |
| --- | --- | --- |
| `https://a.example.com` | API cible 1 | L’en-tête `Host` est `a.example.com`. Cette demande correspond à la règle de routage `abc123`. |
| `https://b.example.com` | API cible 2 | L’en-tête `Host` est `b.example.com`. Cette demande correspond à la règle de routage `000zzz`. |
| `https://testing.example.com` | API cible 3 | Cette demande correspond à la règle de routage fourre-tout `efg456`. |
# Méthodes d’utilisation des règles de routage
Vous pouvez créer une règle de routage à l'aide du AWS Management Console SDK ou de n'importe quel autre AWS SDK. AWS CLI Après avoir créé une règle, vous pouvez modifier sa priorité.
## Création d’une règle de routage
La procédure suivante explique comment créer une règle de routage pour un nom de domaine personnalisé avec un mode de routage défini sur `ROUTING_RULE_THEN_API_MAPPING` ou `ROUTING_RULE_ONLY`.
------
#### [ AWS Management Console ]
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Noms de domaine personnalisés** dans le volet de navigation principal.
1. Choisissez un nom de domaine personnalisé.
1. Dans l’onglet **Détails du routage**, choisissez **Ajouter une règle de routage**.
1. Choisissez **Ajouter une nouvelle condition** pour ajouter une nouvelle condition.
Vous pouvez ajouter une condition d’en-tête ou de chemin de base. Pour faire correspondre toutes les demandes entrantes à votre nom de domaine personnalisé, n’ajoutez pas de condition.
1. Sous **Action**, utilisez le menu déroulant pour sélectionner votre API et votre étape cibles.
1. Choisissez **Suivant**.
1. Dans le champ Priorité, saisissez un nombre pour votre priorité.
API Gateway évalue les règles par ordre de priorité, de la valeur la plus basse à la valeur la plus élevée.
Si vous créez une règle sans condition, nous vous recommandons d’utiliser une priorité élevée.
1. Choisissez **Créer une règle de routage**.
------
#### [ AWS CLI ]
La [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html)commande suivante crée une règle de routage avec une priorité de 50. Dans cet exemple, API Gateway achemine toutes les demandes entrantes contenant les en-têtes `Hello:World` et `x-version:beta`, ainsi que le chemin de base `PetStoreShopper` vers l’API cible `a1b2c3`.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
Le résultat se présente comme suit :
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## Modification de la priorité d’une règle de routage
Vous pouvez modifier la priorité d’une règle de routage. Cette modification prend effet immédiatement et peut avoir un impact sur la manière dont les utilisateurs d’API invoquent vos noms de domaine personnalisés. Lorsque vous définissez les priorités de vos règles de routage, nous vous recommandons de laisser des espaces entre les règles.
Par exemple, imaginons que vous définissiez deux règles de routage, une règle `abc123` avec une priorité de 50 et une règle `zzz000` avec une priorité de 150. Pour modifier leur priorité des règle afin qu’API Gateway évalue la règle `zzz000` en premier, vous pouvez définir la priorité de la règle `zzz000` sur 30.
------
#### [ AWS Management Console ]
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Noms de domaine personnalisés** dans le volet de navigation principal.
1. Choisissez un nom de domaine personnalisé.
1. Sous l’onglet **Détails du routage**, choisissez votre règle de routage, puis sélectionnez **Modifier**.
1. Choisissez **Suivant**.
1. Sous Priorité, saisissez la nouvelle priorité.
1. Sélectionnez **Enregistrer les modifications**.
------
#### [ AWS CLI ]
La [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html)commande suivante modifie la priorité d'une règle de routage`abc123`.
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
Le résultat se présente comme suit :
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# Recréation d’un mappage d’API à l’aide de règles de routage
Vous pouvez recréer un mappage d’API à l’aide de règles de routage. Pour recréer un mappage d’API, assurez-vous d’activer la suppression du chemin de base. Cela préserve le comportement des mappages d’API. Pour de plus amples informations, veuillez consulter [Suppression du chemin de base avec les conditions du chemin de base](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split).
Le tutoriel suivant explique comment recréer le mappage d’API `https:// api.example.com/orders/v2/items/categories/5` en tant que règle de routage, et comment mettre à jour vos journaux d’accès pour enregistrer l’ID de la règle de routage utilisée par API Gateway pour envoyer le trafic à votre API.
------
#### [ AWS Management Console ]
**Pour définir le mode de routage sur ROUTING\$1RULE\$1THEN\$1 API\$1MAPPING**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Noms de domaine personnalisés** dans le volet de navigation principal.
1. Choisissez votre nom de domaine personnalisé.
1. Sous **Détails du domaine**, choisissez **Modifier**.
1. Pour le **mode de routage**, choisissez **API\$1MAPPINGROUTING\$1RULE\$1THEN\$1**.
1. Choisissez **Enregistrer**.
Après avoir défini le mode de routage, vous allez créer la règle de routage.
**Pour créer la règle de routage**
1. Dans l’onglet **Détails du routage**, choisissez **Ajouter une règle de routage**.
1. Choisissez **Ajouter une condition**, puis **Chemin**.
1. Sous **Chemin**, saisissez **orders/v2/items/categories/5**.
1. Sous **Chemin de base de la bande**, choisissez **Actif**.
1. Sous **API cible**, choisissez votre API cible.
1. Sous **Étape cible**, choisissez votre étape cible.
1. Choisissez **Suivant**.
1. Sous Priorité, saisissez une priorité.
Même si vous conservez votre mappage d’API, API Gateway utilisera toujours la nouvelle règle de routage, car les règles de routage ont toujours la priorité sur les mappages d’API.
1. Sélectionnez **Enregistrer les modifications**.
Après avoir créé la règle de routage, mettez à jour le format du journal d’accès pour votre étape, ou créez un journal afin de vérifier qu’API Gateway utilise votre règle de routage pour envoyer le trafic à votre API.
**Pour mettre à jour vos journaux d’accès**
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Choisissez votre API.
1. Dans le volet de navigation principal, choisissez **Étapes**.
1. Sous **Journaux et traçage**, choisissez **Modifier**.
Si vous n’avez pas de groupe de journaux, consultez [Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway](set-up-logging.md).
1. Ajoutez **\$1context.customDomain.routingRuleIdMatched** à votre format de journal.
Ce groupe de journaux enregistre l’ID de la règle de routage utilisée par API Gateway pour envoyer le trafic à votre API. Pour de plus amples informations, veuillez consulter [Je ne peux pas dire comment API Gateway a envoyé du trafic à mon APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
1. Choisissez **Enregistrer**.
Après avoir mis à jour vos journaux d’accès, invoquez votre nom de domaine personnalisé. Voici un exemple de commande curl permettant d’invoquer le nom de domaine personnalisé `https://api.example.com` avec le chemin de base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
Après avoir invoqué avec succès votre nom de domaine personnalisé, vérifiez que CloudWatch Logs affiche le`routingRuleIdMatched`. Pour savoir comment utiliser la console CloudWatch Logs pour afficher un groupe de journaux, consultez[Afficher les événements du journal d'API Gateway dans la CloudWatch console](view-cloudwatch-log-events-in-cloudwatch-console.md).
------
#### [ AWS CLI ]
1. Utilisez la [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html)commande suivante pour mettre à jour le nom de domaine `api.example.com` afin d'utiliser le mode de routage`ROUTING_RULE_THEN_API_MAPPING`.
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. Utilisez la [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html)commande suivante pour créer une nouvelle règle de routage afin de recréer le mappage `https://api.example.com/orders/v2/items/categories/5` d'API.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. Utilisez la commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) suivante pour mettre à jour le format des journaux d’accès afin qu’il inclut la variable `$context.customDomain.routingRuleIdMatched`. Cette variable enregistre l’ID de la règle de routage utilisée par API Gateway pour envoyer le trafic à votre API. Vous allez utilisez ce journal pour vérifier qu’API Gateway utilise votre règle de routage pour envoyer le trafic à votre API. Pour de plus amples informations, veuillez consulter [Je ne peux pas dire comment API Gateway a envoyé du trafic à mon APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
Si vous n’avez pas de groupe de journaux, consultez [Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway](set-up-logging.md).
1. Utilisez l’exemple de commande curl suivant pour invoquer votre nom de domaine personnalisé à l’aide du chemin de base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. Utilisez la [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html)commande suivante pour obtenir les événements du journal à partir du groupe de journaux `access-log-group-orders` contenant l'ID de règle de routage`abc123`.
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
Vous avez la confirmation qu’API Gateway a utilisé la règle de routage pour envoyer le trafic à votre API.
------
# Résolution des problèmes liés aux règles de routage
Les conseils suivants peuvent vous aider à résoudre les problèmes liés à votre règles de routage.
## Je ne peux pas dire comment API Gateway a envoyé du trafic à mon APIs
Vous pouvez utiliser les journaux d’accès de l’étape de votre API REST afin d’enregistrer et de résoudre les problèmes liés à vos règles de routage. Vous pouvez consulter l’ID de la règle de routage utilisée par API Gateway pour envoyer le trafic à votre API à l’aide de la variable `$context.customDomain.routingRuleIdMatched`. Pour afficher le mappage d’API utilisé par API Gateway pour envoyer le trafic à votre API, utilisez la variable `$context.customDomain.basePathMatched`.
Pour enregistrer vos règles de routage, vous devez configurer [un ARN de rôle CloudWatch Logs approprié](set-up-logging.md#set-up-access-logging-permissions) pour votre compte et créer un groupe de journaux.
L’exemple de groupe de journaux d’accès suivant récupère les informations pertinentes pour résoudre les problèmes liés aux règles de routage et aux mappages d’API. API Gateway renseigne uniquement la variable context correspondant au mécanisme de routage utilisé. Sinon, la variable context est `-`.
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
Nous vous recommandons également de vérifier le mode de routage de votre nom de domaine personnalisé. Pour de plus amples informations, veuillez consulter [Définition du mode de routage de votre nom de domaine personnalisé](set-routing-mode.md).
## Je ne parviens pas à activer les règles de routage de mon nom de domaine personnalisé
API Gateway peut vous envoyer l’erreur suivante :
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
Vous recevrez cette erreur si vous avez ou avez eu une politique IAM qui refuse l'accès à [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies)ou [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies). Lorsque vous activez les règles de routage d’un nom de domaine personnalisé, même si votre politique continue de refuser l’accès à `BasePathMapping` ou `ApiMapping`, celle-ci peut être utilisée pour accéder à `RoutingRule`. L’utilisateur peut ainsi modifier le comportement de routage de votre nom de domaine personnalisé.
Par exemple, si vous aviez une politique comme suit :
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
Si vous activez les règles de routage pour `example.com`, cette politique continuera à refuser l’accès à la création d’un `ApiMapping`, mais ne refusera pas l’accès à la création d’une `RoutingRule`.
Nous vous recommandons d’auditer les politiques IAM de votre compte. L’exemple de politique suivant refuse l’accès à la création d’un `ApiMapping`, d’un `BasePathMapping` et d’une `RoutingRule` :
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
Après avoir vérifié que toutes vos politiques ont été mises à jour, vous pouvez mettre à jour les paramètres au niveau du compte de votre API afin d’activer les règles de routage pour une région.
Utilisez la commande [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) suivante pour mettre à jour les paramètres au niveau du compte de votre API pour une région :
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
Après avoir mis à jour les paramètres au niveau du compte de votre API, vous pouvez modifier le mode de routage de votre nom de domaine personnalisé. Vous pouvez également continuer à utiliser des politiques IAM pour refuser l’accès aux `RoutingRules`, au `ApiMapping` ou au `BasePathMapping`.
# Utilisez les mappages d'API pour connecter les étapes d'API à un nom de domaine personnalisé pour REST APIs
Les mappages d’API vous permettent de connecter des étapes d’API à un nom de domaine personnalisé. Cela vous envoie du trafic APIs via votre nom de domaine personnalisé.
Un mappage d’API spécifie une API, une étape et éventuellement un chemin à utiliser pour le mappage. Par exemple, vous pouvez `https://api.example.com/orders` mapper le `production` stade d'une API.
Vous pouvez mapper les étapes d’API HTTP et REST au même nom de domaine personnalisé.
Avant de créer un mappage d’API, vous devez disposer d’une API, d’une étape et d’un nom de domaine personnalisé. Pour plus d’informations sur la création d’un nom de domaine personnalisé, consultez [Configuration d’un nom de domaine personnalisé régional dans API Gateway](apigateway-regional-api-custom-domain-create.md).
## Demandes entrantes adressées à votre nom de domaine personnalisé
Lorsque vous mappez un nom de domaine personnalisé à une étape de votre API, API Gateway supprime le chemin de base entrant. Cela supprime le chemin de base mappé depuis l'appel vers l'API. Par exemple, si votre mappage de chemin de base était destiné `https://api.example.com/orders/shop/5` à l'`test`étape et que vous utilisiez la requête suivante`https://api.example.com/orders/shop/5/hats`, API Gateway invoquerait la `/hats` ressource de l'`test`étape de votre API, et non la `orders/shop/5/hats` ressource.
## Mappage des demandes d'API
Ce qui suit explique comment API Gateway évalue les mappages d'API.
Vous pouvez créer un mappage d'API à l'aide de mappages à un seul niveau, tels qu'un mappage `orders` d'API depuis le `beta` stade d'une API et un mappage d'API depuis `shipping` le `alpha` stade d'une API. Pour les noms de domaine personnalisés régionaux dotés de la politique de sécurité TLS 1.2, API Gateway prend en charge les mappages d'API à plusieurs niveaux. Vous pouvez créer un mappage `orders/v1/items` d'API depuis le `alpha` stade d'une API et `orders/v2/items` vers le `beta` stade d'une API. Lorsque vous créez un mappage à plusieurs niveaux, API Gateway envoie des demandes au mappage d'API dont le chemin correspondant est le plus long.
Vous pouvez créer un mappage d'API vers le chemin vide`(none)`. Si aucun chemin ne correspond à la demande, API Gateway envoie la demande au chemin vide`(none)`.
Dans cet exemple, le nom de domaine personnalisé `https://api.example.com` possède les mappages d'API suivants.
| Cartographie des API | API sélectionnée |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
Le tableau suivant montre comment API Gateway applique les mappages d'API précédents à des exemples de demandes.
| Requête | API sélectionnée | Explication |
| --- | --- | --- |
| `https://api.example.com/orders` | API 2 | La demande correspond exactement à ce mappage d’API. |
| `https://api.example.com/orders/v1/items` | API 3 | La demande correspond exactement à ce mappage d’API. |
| `https://api.example.com/orders/v2/items` | API 4 | La demande correspond exactement à ce mappage d’API. |
| `https://api.example.com/orders/v1/items/123` | API 3 | API Gateway choisit le mappage d’API dont le chemin d’accès est le plus long. La présence de `123` à la fin de la demande n’affecte pas la sélection. Consultez [Demandes entrantes adressées à votre nom de domaine personnalisé](#rest-api-mappings-incoming-requests). |
| `https://api.example.com/orders/v2/items/categories/5` | API 5 | API Gateway choisit le mappage d’API dont le chemin d’accès est le plus long. |
| `https://api.example.com/customers` | API 1 | API Gateway utilise le mappage vide comme fourre-tout. |
| `https://api.example.com/ordersandmore` | API 2 | API Gateway choisit le mappage d’API doté du préfixe correspondant le plus long. Pour un nom de domaine personnalisé configuré avec des mappages à un seul niveau, tels que `https://api.example.com/orders` et `https://api.example.com/` uniquement, API Gateway choisirait `API 1`, car il n’y a pas de chemin correspondant avec `ordersandmore`. |
## Restrictions
+ Dans un mappage d'API, le nom de domaine personnalisé et le nom de domaine mappé APIs doivent se trouver dans le même AWS compte.
+ Les mappages d’API ne doivent contenir que des lettres, des chiffres et les caractères suivants : `$-_.+!*'()/`.
+ La longueur maximale du chemin d’un mappage d’API est de 300 caractères.
+ Vous pouvez disposer de 200 mappages d’API à plusieurs niveaux pour chaque nom de domaine. Cette limite n'inclut pas le mappage d'API avec des niveaux uniques, tels que`/prod`.
+ Vous ne pouvez APIs mapper HTTP à un nom de domaine personnalisé régional qu'avec la politique de sécurité TLS 1.2.
+ Vous ne pouvez pas WebSocket APIs mapper vers le même nom de domaine personnalisé qu'une API HTTP ou une API REST.
+ Après avoir créé vos mappages d’API, vous devez créer ou mettre à jour l’enregistrement de ressource de votre fournisseur DNS pour le mapper au point de terminaison de votre API.
+ Si vous créez un mappage d’API à plusieurs niveaux, API Gateway convertit tous les noms d’en-tête en minuscules.
## Création d’un mappage d’API
Pour créer un mappage d’API, vous devez d’abord créer un nom de domaine personnalisé, une API et une étape. Le mode de routage de votre nom de domaine personnalisé doit être défini sur `ROUTING_RULE_THEN_API_MAPPING` ou`API_MAPPING_ONLY`. Pour plus d'informations sur la façon de définir le mode de routage, consultez[Définition du mode de routage de votre nom de domaine personnalisé](set-routing-mode.md).
Pour des exemples AWS Serverless Application Model de modèles qui créent toutes les ressources, voir [Sessions avec SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) activé GitHub.
------
#### [ AWS Management Console ]
1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Sélectionnez **Noms de domaine personnalisés** dans le volet de navigation principal.
1. Choisissez un nom de domaine personnalisé.
1. Dans l'onglet **Détails du routage**, choisissez **Configurer les mappages d'API**.
1. Saisissez l’**API**, l’**étape** et le **chemin** du mappage.
1. Choisissez **Enregistrer**.
------
#### [ AWS CLI ]
La commande suivante de la [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) crée un mappage d’API. Dans cet exemple, API Gateway envoie des demandes `api.example.com/v1/orders` à l’API et à l’étape spécifiés.
**Note**
Pour créer des mappages d’API à plusieurs niveaux, vous devez utiliser `apigatewayv2`.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
L' CloudFormation exemple suivant crée un mappage d'API.
**Note**
Pour créer des mappages d’API à plusieurs niveaux, vous devez utiliser `AWS::ApiGatewayV2`.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------