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.

# Utilisation de mappages d’API pour connecter des étapes d’API REST à un nom de domaine personnalisé
<a name="rest-api-mappings"></a>

Les mappages d’API vous permettent de connecter des étapes d’API à un nom de domaine personnalisé. Ils envoient le trafic à vos API 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 mapper `https://api.example.com/orders` à l’étape `production` 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 de votre nom de domaine personnalisé
<a name="rest-api-mappings-incoming-requests"></a>

Lorsque vous mappez un nom de domaine personnalisé à une étape de votre API, API Gateway supprime le chemin de base entrant. Le chemin de base mappé de l’invocation de l’API est supprimé. Par exemple, si votre chemin de base `https://api.example.com/orders/shop/5` était mappé à l’étape `test` et que vous utilisiez la demande `https://api.example.com/orders/shop/5/hats`, API Gateway invoquerait la ressource `/hats` de l’étape `test` de votre API, et non la ressource `orders/shop/5/hats`.

## Mappage des demandes d’API
<a name="rest-api-mappings-evalutation"></a>

L’exemple suivant explique comment API Gateway évalue les mappages d’API.

Vous pouvez créer un mappage d’API à l’aide de mappages à un niveau, par exemple un mappage d’API entre `orders` et l’étape `beta` d’une API, et un mappage d’API entre `shipping` et l’étape `alpha` d’une API. Pour les noms de domaine personnalisés régionaux avec une politique de sécurité TLS 1.2, API Gateway prend en charge les mappages d’API à plusieurs niveaux. Vous pouvez créer un mappage d’API entre `orders/v1/items` et l’étape `alpha` d’une API, et entre `orders/v2/items` et l’étape `beta` d’une API. Lorsque vous créez un mappage à plusieurs niveaux, API Gateway achemine les demandes vers le mappage d’API au chemin de correspondance 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 celle-ci au chemin vide `(none)`.

Dans cet exemple, le nom de domaine personnalisé `https://api.example.com` possède les mappages d’API suivants.


|  Mappage d’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 demande.


| 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 de votre nom de domaine personnalisé](#rest-api-mappings-incoming-requests). | 
| `https://api.example.com/orders/v1/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 au préfixe de correspondance le plus long.<br />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
<a name="rest-api-mappings-restrictions"></a>
+ Dans un mappage d'API, le nom de domaine personnalisé et les API mappées doivent figurer 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 les mappages d’API à un niveau tels que `/prod`.
+ Vous ne pouvez mapper les API HTTP à un nom de domaine personnalisé régional qu’à l’aide de la politique de sécurité TLS 1.2.
+ Vous ne pouvez pas mapper les WebSocket API au 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
<a name="rest-api-mappings-examples"></a>

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 configuration du 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.

------
#### [ Console de gestion AWS ]

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 **Configuration des mappages d’API**.

1. Saisissez l’**API**, l’**étape** et le **chemin** du mappage.

1. Cliquez sur **Enregistrer**.

------
#### [ AWS CLI ]

La commande [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) suivante 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
```

------