Mappage des étapes d’API à un nom de domaine personnalisé pour les API HTTP - Amazon API Gateway
Routage des demandes d’APIRestrictionsCréation d’un mappage d’API

Mappage des étapes d’API à un nom de domaine personnalisé pour les API HTTP

Les mappages d’API vous permettent de connecter des étapes d’API à un nom de domaine personnalisé. Après avoir créé un nom de domaine et configuré les enregistrements DNS, vous pouvez utiliser les mappages d’API pour envoyer le trafic vers 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 l’étape production d’une API à https://api.example.com/orders.

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.

Routage des demandes d’API

Vous pouvez configurer des mappages d’API à plusieurs niveaux, par exemple orders/v1/items et orders/v2/items.

Pour les mappages d’API à plusieurs niveaux, API Gateway achemine les demandes vers le mappage d’API dont le chemin d’accès est le plus long. API Gateway prend uniquement en compte les chemins configurés pour les mappages d’API, et non les routes d’API, pour sélectionner l’API à appeler. Si aucun chemin ne correspond à la demande, API Gateway envoie celle-ci à l’API que vous avez mappée au chemin vide (none).

Pour les noms de domaine personnalisés qui utilisent les mappages d’API à plusieurs niveaux, API Gateway achemine les demandes vers le mappage d’API doté du préfixe correspondant le plus long.

Par exemple, imaginons un nom de domaine personnalisé https://api.example.com doté des mappages d’API suivants :

  1. (none) mappé à l’API 1.

  2. orders mappé à l’API 2.

  3. orders/v1/items mappé à l’API 3.

  4. orders/v2/items mappé à l’API 4.

  5. orders/v2/items/categories mappé à l’API 5.

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.

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 les API mappées doivent se trouver sur le même compte AWS.

  • 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.

  • 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 API WebSocket au même nom de domaine personnalisé qu’une API HTTP ou une API REST.

  • 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. 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.

Pour accéder à des exemples de modèles AWS Serverless Application Model qui créent toutes les ressources, consultez Séances avec SAM sur GitHub.

AWS Management Console
Pour créer un mappage d’API

  1. Connectez-vous à la console API Gateway à l’adresse https://console.aws.amazon.com/apigateway.

  2. Choisissez Noms de domaine personnalisés.

  3. Sélectionnez un nom de domaine personnalisé que vous avez déjà créé.

  4. Choisissez Mappages d’API.

  5. Choisissez Configurer les mappages d’API.

  6. Choisissez Ajouter un nouveau mappage.

  7. Entrez une API, une Étape et, éventuellement, un Chemin d’accès.

  8. Choisissez Enregistrer.

AWS CLI

La commande suivante de la AWS CLI 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.

aws apigatewayv2 create-api-mapping \
    --domain-name api.example.com \
    --api-mapping-key v1/orders \
    --api-id a1b2c3d4 \
    --stage test
AWS CloudFormation

L’exemple AWS CloudFormation suivant crée un mappage d’API.

MyApiMapping:
  Type: 'AWS::ApiGatewayV2::ApiMapping'
  Properties:
    DomainName: api.example.com
    ApiMappingKey: 'orders/v2/items'
    ApiId: !Ref MyApi
    Stage: !Ref MyStage