API Gateway:Créer une API

Étape 1 : Configurer une API

Connectez-vous à la console API Gateway. Dans le volet de navigation de gauche, choisissez Manage APIs > APIs. Sur la page APIs, cliquez sur Create API pour créer et configurer une API.

1. Configurer les informations de base

   Parameter	Description
   API Group	Unité de gestion de base des API. Avant de créer une API, créez un groupe d'API. La sélection d'un groupe attribue automatiquement une région à l'API.
   API Name	Nom de l'API à créer. Chaque nom d'API doit être unique au sein d'un groupe d'API.
   Security Authentication	Les options Alibaba Cloud App et No Authentication sont prises en charge. Alibaba Cloud App : permet à l'appelant d'utiliser une application authentifiée pour appeler l'API. No Authentication : permet à tout utilisateur connaissant la définition de la requête de l'API d'initier des demandes. API Gateway transfère directement la requête au service backend sans vérifier l'identité de l'appelant. Nous vous déconseillons de définir Security Certification sur No Authentication.
   Signature Algorithm	Algorithme utilisé pour signer les requêtes API. Valeurs possibles : HMAC_SHA256 HMAC_SHA1 et HMAC_SHA256 : la sélection de cette valeur prend en charge les deux algorithmes.
   API Option	Fonctionnalité à activer pour l'API. Valeurs possibles : Anti-replay Protection (X-Ca-Nonce Header Required) Forbid Internet Access Allow API Publish to Alibaba Cloud Marketplace Remarque Si vous sélectionnez Forbid Internet Access et souhaitez demander un nom de domaine VPC, cliquez sur Apply for VPC domain name pour accéder à la console.
   Description	Description de l'API.

2. Configurer les informations de requête

   À l'étape Define API Request, configurez les informations de requête de l'API. Les configurations détaillées incluent Protocol, Request Path, HTTP Method, Request Mode et Request Parameters.

   Parameter	Description
   Protocol	Protocole réseau utilisé pour la requête API. Valeurs possibles : HTTP et HTTPS.
   Request Path	Chemin de requête API correspondant à l'hôte du service. Le chemin de requête peut différer du chemin réel du service backend. Spécifiez un chemin valide et sémantiquement précis. Vous pouvez configurer des paramètres dynamiques dans le chemin de requête, ce qui nécessite de spécifier des paramètres de chemin dans la requête. De plus, les paramètres de chemin peuvent être mappés aux paramètres de requête et d'en-tête reçus par le service backend.
   HTTP Method	Méthode de requête HTTP standard. Valeurs possibles : PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS et ANY.
   Request Mode	Mode de transmission des paramètres de requête. Valeurs possibles : Request Parameter Map (Filter Out Unknown Parameters), Map (Pass-through Unknown Parameters) et Pass-through. Map (Filter Out Unknown Parameters) : spécifie que vous devez configurer les mappages de requête et de réponse pour les paramètres query, path et body form. API Gateway transmet uniquement les paramètres configurés au service backend de manière transparente. Les autres paramètres sont filtrés. Map (Pass-through Unknown Parameters) : spécifie que vous devez configurer les mappages de requête et de réponse pour les paramètres query, path et body form. API Gateway mappe et vérifie uniquement les paramètres de requête configurés et transmet les paramètres inconnus au service backend de manière transparente. Pass-through : spécifie qu'il n'est pas nécessaire de configurer les paramètres query et body form dans la requête. Cependant, vous devez configurer les paramètres de chemin. API Gateway transmet tous les paramètres envoyés par le client au service backend de manière transparente.

   Configurer les paramètres de requête : dans la section Request Parameters, configurez les paramètres de requête de l'API aux emplacements spécifiques. Les emplacements suivants sont pris en charge : Parameter Path, Head et Query. Lorsque vous configurez un paramètre de chemin dynamique, fournissez une description pour ce paramètre. Les types de données suivants sont pris en charge : String, Int et Boolean.

   • Les noms de tous les paramètres doivent être uniques.

   • Utilisez les raccourcis clavier dans la colonne No. pour modifier l'ordre d'affichage des paramètres.

   • Cliquez sur Remove dans la colonne Actions pour supprimer un paramètre inutile.

   Remarque

   Si vous avez configuré un paramètre dynamique dans le chemin de requête, définissez un paramètre portant le même nom et définissez Parameter Location sur Parameter Path.

   Configurer une règle de validation des paramètres : recherchez le paramètre concerné et cliquez sur Advanced Settings dans la colonne Actions. Dans la boîte de dialogue Advanced Settings, configurez les paramètres pertinents, tels que Maximum Length et Enumerated Value. API Gateway pré-valide les requêtes selon les règles de validation. Les requêtes contenant des paramètres invalides ne sont pas envoyées à votre service backend, ce qui réduit considérablement sa charge de travail.

3. Configurer un service backend

   À l'étape Define Backend Service, configurez les mappages de requête et de réponse pour les paramètres et spécifiez les configurations API de votre service backend. Après réception d'une requête, API Gateway convertit le format de la requête selon la configuration du service backend, puis transfère la requête à ce dernier.

   Configure basic information : dans la section Basic Settings for Backend Service, configurez les informations de base du service backend.

   Parameter	Description
   Configuration Mode	Indique si vous souhaitez utiliser un service backend existant ou personnaliser un service backend. Valeurs possibles : Use Existing Backend Service Customize Backend Service
   Backend Service Type	Type de service backend. Valeurs possibles : HTTP/HTTPS Service, VPC, Function Compute, OSS et Mock. HTTP/HTTPS : option sélectionnée par défaut. Elle indique qu'API Gateway accède au service backend via HTTP ou HTTPS. Sélectionnez cette option si API Gateway peut communiquer directement avec le service backend. Si vous souhaitez utiliser un service HTTPS comme service backend, configurez un certificat SSL pour le service HTTPS. Function Compute : si vous souhaitez utiliser Function Compute comme service backend, effectuez préalablement les opérations suivantes : créez une fonction dans la console Function Compute, spécifiez un nom de service et un nom de fonction, puis obtenez le nom de ressource Alibaba Cloud (ARN) du rôle pour Function Compute. VPC : si le service backend est déployé dans un cloud privé virtuel (VPC), sélectionnez cette option. OSS : si Object Storage Service (OSS) est le service backend, sélectionnez cette option. Mock : si vous souhaitez simuler les résultats attendus du service backend HTTP ou HTTPS, sélectionnez cette option. Remarque Vous ne pouvez pas créer de service backend de type HTTP ou OSS dans les régions hors de Chine ni dans la région Chine (Hong Kong).
   VPC Access Name	Si votre service backend est déployé dans un VPC, spécifiez un nom d'autorisation d'accès VPC.
   Backend Service URL	URL hôte du service backend. La valeur peut être un nom de domaine ou une valeur au format http://host:port ou https://host:port. La valeur doit commencer par http:// ou https://.
   Backend Request Path	Chemin de requête réel de votre API sur votre serveur backend. Si vous souhaitez recevoir des paramètres dynamiques dans le chemin du service backend, déclarez les mappages de paramètres en spécifiant les emplacements et les noms des paramètres de requête pertinents.
   HTTP Method	Méthode de requête HTTP standard. Valeurs possibles : PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS et ANY.
   Backend Service Timeout Period	Délai accordé à API Gateway pour envoyer une requête API reçue au service backend et recevoir une réponse. Le temps de réponse commence lorsque API Gateway envoie la requête au service backend et se termine lorsqu'il reçoit la réponse. Le temps de réponse ne peut pas dépasser 30 secondes. Si API Gateway ne reçoit pas de réponse du service backend dans un délai de 30 secondes, il cesse d'accéder au service backend et renvoie un message d'erreur.

   Configurer les paramètres du service backend : dans la section Backend Service Parameters, configurez les mappages de requête et de réponse pour les paramètres. Les mappages de nom et d'emplacement sont pris en charge. API Gateway peut mapper un paramètre de requête path, header, query ou body vers un paramètre de réponse à un emplacement différent. Cela vous permet d'exposer votre service backend sous forme d'API standardisée et professionnelle. Cette partie déclare les mappages entre les paramètres de requête et de réponse.

   Configure constant parameters : dans la section Constant Parameters, configurez les paramètres constants. Les paramètres constants sont invisibles pour vos utilisateurs. Après réception des requêtes, API Gateway ajoute les paramètres constants aux emplacements spécifiés et transfère les requêtes à votre service backend pour répondre à vos besoins métier. Par exemple, pour qu'API Gateway attache le paramètre abc à chaque requête transférée, configurez abc comme paramètre constant. API Gateway ajoutera alors ce paramètre à l'emplacement spécifié avant de transférer la requête.

   Configurer les paramètres système : dans la section System Parameters, configurez les paramètres système pris en charge par API Gateway. Par défaut, API Gateway n'ajoute pas de paramètres système aux requêtes API. Pour obtenir les paramètres système, configurez leurs emplacements et leurs noms. Le tableau suivant répertorie les paramètres système :

   Parameter	Description
   CaClientIp	Adresse IP du client qui envoie une requête API. Si vous avez configuré Web Application Firewall (WAF) ou Content Delivery Network (CDN), le système enregistre l'adresse IP de retour à l'origine. L'adresse IP réelle du client est enregistrée dans X-Forwarded-For.
   CaDomain	Nom de domaine utilisé pour envoyer une requête API.
   CaRequestHandleTime	Heure de la requête en UTC.
   CaRequestId	ID de la requête (RequestId).
   CaApiName	Nom de l'API.
   CaHttpSchema	Protocole utilisé pour appeler l'API. Valeurs possibles : HTTP et HTTPS.
   CaProxy	Proxy utilisé pour traiter une requête API. Définissez la valeur sur AliCloudApiGateway.
   CaClientUa	Agent utilisateur du client qui envoie une requête API.
   CaCloudMarketInstanceId	ID de l'instance correspondant au produit Alibaba Cloud Marketplace acheté pour la première fois.
   CaAppId	ID de l'application utilisée pour appeler l'API.
   CaAppKey	Clé de l'application utilisée pour appeler l'API.
   CaAppExtendInfo	Extensions de l'application.
   CaStage	Environnement dans lequel vous appelez l'API. Valeurs possibles : RELEASE, TEST et PRE.
   CaInstanceId	ID de l'instance à laquelle l'API appartient.
   CaSourceVpcId	VPC auquel l'adresse IP du client appartient.

   Sélectionnez Pass Host Header dans la section Request Header Pass-through Settings de la page des détails du groupe d'API. Après avoir sélectionné Pass Host Header, API Gateway transmet le paramètre d'en-tête Host de la requête au service backend. Si vous ne sélectionnez pas Pass Host Header, API Gateway envoie l'en-tête Host que vous avez spécifié au service backend. L'exemple de code suivant illustre cette différence :

   Par exemple, si vous associez le nom d'hôte xuemeng.XXXX.com à un groupe d'API, le nom d'hôte du service backend des API dans ce groupe est apigatewayXXXXXXalicloudapi.com:8080. Les extraits de code suivants montrent les différents noms d'hôte reçus par votre service backend avant et après l'activation de Pass Host Header.

   Si Pass Host Header est activé, le nom d'hôte suivant est reçu :

Host: xuemeng.XXXX.com

Si Pass Host Header est désactivé, le nom d'hôte suivant est reçu :

Host: apigatewayXXXXXXalicloudapi.com:8080

4. Configurer les informations de réponse

   À l'étape Define Response, configurez Response ContentType, Response Example, Error Response Example et Error Codes.

Étape 2 : Déboguer l'API

Après avoir créé et configuré l'API, déboguez-la sur la page de débogage API afin de vous assurer qu'elle fonctionne comme prévu.

Une fois l'API créée et configurée, vous êtes redirigé vers la page APIs. Sur cette page, effectuez les opérations suivantes pour vérifier si l'API peut être appelée et si l'URL de requête est valide :

1. Recherchez l'API que vous avez créée, puis cliquez sur le nom de l'API ou sur Manage dans la colonne Actions pour accéder à la page Definition.

2. Dans le volet de navigation de gauche, cliquez sur Debug API.

3. Sur la page qui s'affiche, spécifiez les paramètres de requête dans la section Request Parameters et cliquez sur Send Request.

Un résultat s'affiche sur le côté droit de la page.

Si une réponse de succès est renvoyée, l'API est appelée comme prévu.

Si un code d'état HTTP 4XX ou 5XX est renvoyé, une erreur s'est produite lors de l'appel de l'API. Pour plus d'informations, consultez Comment obtenir le message d'erreur et Codes d'erreur.

Étape 3 : Étapes suivantes

Après avoir configuré et débogué l'API, celle-ci est disponible pour les appels. Publiez l'API dans l'environnement de test, de préproduction ou de production pour un débogage supplémentaire ou pour permettre aux utilisateurs de l'appeler. Vous pouvez également ajouter des configurations de sécurité à l'API. Par exemple, vous pouvez attacher une signature à l'API. Pour plus d'informations, consultez Utiliser l'authentification par résumé pour appeler une API.