À propos des composants d'API
Une API définie sur API Gateway comprend deux composants principaux :
Configuration de l'API : configuration de l'API créée lorsque vous importez une définition d'API. Créez la définition de l'API en tant que spécification OpenAPI. Si votre API gère les services gRPC sur Cloud Run, vous pouvez la définir avec une définition et une configuration de service gRPC.
Chaque fois que vous importez une définition d'API, API Gateway crée une configuration d'API. Autrement dit, vous pouvez créer une configuration d'API, mais vous ne pouvez pas la modifier ultérieurement. Si vous modifiez ultérieurement la définition de l'API dans la spécification OpenAPI ou la définition du service gRPC, puis importez la définition d'API modifiée, vous créez une configuration d'API.
Passerelle : proxy évolutif hautes performances basé sur Envoy qui héberge la configuration d'API déployée. Le déploiement d'une configuration d'API sur une passerelle crée l'URL externe que les clients d'API utilisent pour accéder à l'API.
L'image suivante montre ces composants :
À propos du déploiement d'une configuration d'API sur une passerelle
Vous déployez une configuration d'API sur une passerelle pour rendre votre API accessible à vos clients d'API :
Une passerelle :
Est déployée dans une région GCP spécifique. Une région est une région géographique spécifique sur GCP dans laquelle vous pouvez déployer des ressources.
Doit héberger une configuration d'API. Vous ne pouvez pas créer une passerelle vide, c'est-à-dire sans passerelle API. Toutefois, une fois la passerelle créée, vous pouvez la mettre à jour pour remplacer une configuration d'API par une autre.
Ne peut héberger qu'une seule configuration d'API. Vous ne pouvez pas déployer plusieurs configurations d'API sur la même passerelle.
Vous gérez ensuite chaque passerelle déployée séparément. Pour chaque passerelle, vous pouvez :
- Démarrer/arrêter/supprimer la passerelle
- Afficher les journaux et les métriques
- Afficher les informations de trace
Choisir une région GCP
Chaque passerelle est déployée dans une région géographique spécifique sur GCP. API Gateway est compatible avec les régions GCP suivantes pour le déploiement :
asia-northeast1australia-southeast1europe-west1europe-west2us-east1us-east4us-central1us-west2us-west3us-west4
Les passerelles API Gateway précédemment créées dans asia-east1 ne seront plus compatibles à partir du 1er novembre 2022.
Vous devez examiner les passerelles en cours d'exécution dans asia-east1 et les supprimer ou les recréer dans un nouvel emplacement si nécessaire.
Définir le point de terminaison de la configuration d'API déployée
Lorsque vous déployez une configuration d'API sur une passerelle, API Gateway crée une URL unique pour la passerelle dans le domaine gateway.dev. Vos clients API utilisent ensuite une URL au format ci-dessous pour accéder à la configuration d'API déployée :
https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev
où GATEWAY_ID est le nom de la passerelle, HASH le code de hachage unique généré lors du déploiement de l'API, et REGION_CODE le code de la région GCP où vous avez déployé la passerelle.
Exemple :
my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
Configurer un compte de service pour le déploiement de configurations d'API
Une configuration d'API déployée sur une passerelle s'exécute avec les autorisations associées aux rôles attribués au compte de service utilisé pour créer la configuration d'API. Par conséquent, vous définissez généralement un compte de service distinct pour créer des configurations d'API. Ce compte de service est ensuite attribué uniquement aux rôles nécessaires pour accéder au service de backend. De cette manière, vous pouvez limiter les autorisations associées à la configuration d'API.
Outre les rôles nécessaires pour accéder au service de backend, le compte de service doit disposer des autorisations suivantes :
L'autorisation
iam.serviceAccounts.actAs. Cette autorisation est incluse dans le rôle Utilisateur du compte de service.Les autorisations nécessaires pour accéder à votre service de backend. Par exemple, si votre backend est mis en œuvre en tant que fonction Cloud, le compte de service doit au moins être attribué au rôle Demandeur Cloud Functions. Pour un backend Cloud Run, le rôle est Demandeur Cloud Run. En limitant les autorisations associées à la configuration d'API, vous pouvez mieux sécuriser vos systèmes de backend.
Pour en savoir plus, consultez la page Configurer votre environnement de développement.
À propos du scaling à zéro instance
API Gateway est un service avec scaling à zéro instance. Cela signifie qu'en l'absence de trafic, toutes les instances de passerelle sont supprimées. Lorsque le trafic augmente, des instances sont créées à la demande pour gérer la charge. Le scaling à zéro instance est contrôlé automatiquement par GCP. Vous n'êtes pas obligé de le configurer ou de le gérer.
Utiliser un équilibreur de charge
Chaque passerelle déployée dans une région contient un équilibreur de charge intégré permettant de gérer les requêtes des clients envoyées à l'API déployée sur la passerelle. Il n'est pas nécessaire de créer un équilibreur de charge distinct pour chaque passerelle.
Vous devez créer un équilibreur de charge lorsque vous déployez la même API sur des passerelles situées dans différentes régions. L'équilibreur de charge dirige ensuite les requêtes API vers les différentes régions. Pour en savoir plus, consultez la section Déployer une API sur plusieurs régions ci-dessous.
Configurer l'accès SSL à une API
API Gateway permet l'accès HTTPS à une API déployée sur une passerelle. Étant donné que vos API sont déployées sur le domaine gateway.dev, Google crée et gère le certificat SSL sur l'équilibreur de charge intégré à la passerelle.
Vous n'avez pas besoin de créer ni d'importer votre propre certificat.
Configurer un serveur de noms de domaine
Par défaut, les clients API envoient des requêtes à un domaine gateway.dev pour accéder à une API déployée, comme indiqué ci-dessus.
Les noms de domaine personnalisés sont destinés à API Gateway lorsqu'ils sont utilisés conjointement avec l'équilibrage de charge HTTP(S) pour API Gateway BÊTA. Pour personnaliser le nom de domaine, créez un équilibreur de charge pour utiliser votre nom de domaine personnalisé, puis acheminez les requêtes vers le domaine gateway.dev de l'API déployée. Pour en savoir plus, consultez la section Utiliser un domaine personnalisé avec API Gateway.
Déployer plusieurs configurations d'API dans la même API
Vous ne pouvez déployer qu'une seule configuration d'API sur une passerelle. Toutefois, vous pouvez déployer plusieurs configurations d'API sur plusieurs passerelles au sein de la même API.
Cette section décrit deux scénarios dans lesquels vous pouvez déployer plusieurs configurations d'API sur plusieurs passerelles au sein d'une même API.
Déployer des configurations d'API sur plusieurs passerelles de la même région
Lors de la création d'une API, les développeurs d'API créent souvent des environnements de développement, de préproduction et de production, où :
- L'environnement de développement permet aux développeurs de créer l'API.
- L'environnement de préproduction permet de tester l'API en vue de lancer une version en production.
- L'environnement de production permet à vos clients API externes d'accéder à l'API.
Pour prendre en charge ce type d'environnement de développement, vous devez définir plusieurs configurations d'API. Par exemple, vous pouvez avoir plusieurs configurations d'API en cours de développement, une configuration d'API en cours de test en préproduction et une configuration d'API actuellement déployée en production.
API Gateway vous permet de créer plusieurs configurations d'API au sein d'une même API, puis de déployer chaque configuration d'API sur une passerelle différente :
Dans cet exemple, vous avez trois configurations d'API différentes : dev, stage et prod. Vous allez ensuite déployer chaque configuration d'API sur une passerelle différente, où chaque passerelle définit sa propre URL de point de terminaison unique.
Déployer une configuration d'API dans plusieurs régions
Vous déployez souvent une API dans plusieurs régions GCP. Le déploiement dans plusieurs régions offre plusieurs avantages, y compris une latence réduite des requêtes, car les requêtes sont envoyées à une API exécutée dans une région géographiquement proche du client, et une fiabilité accrue, car une défaillance dans une région n'affecte pas les API exécutées dans d'autres régions.
Pour déployer une API dans plusieurs régions, vous devez déployer une configuration d'API sur une passerelle dans chaque région. Chaque configuration d'API est spécifique à la région déployée, car elle doit faire référence au service de backend dans cette région.
Dans l'image suivante, les API 1 et 2 sont déployées dans une seule région, et l'API 3 est déployée dans plusieurs régions :
Dans cet exemple, chaque configuration d'API déployée sur une passerelle pour l'API 3 possède un point de terminaison d'URL unique, au format suivant :
https://my-gateway1-a12bcd345e67f89g0h.uc.gateway.dev https://my-gateway2-b12cde345f67g89h0i.en.gateway.dev https://my-gateway3-c12bde345g67h89i0j.uw.gateway.dev
Configurez ensuite un équilibreur de charge à l'aide de l'équilibrage de charge HTTP(S) pour API Gateway BÊTA afin de gérer les requêtes adressées à l'API et de les transférer vers la région appropriée. Pour en savoir plus, consultez la page Créer des déploiements multirégionaux pour API Gateway.
Mettre à jour une API
Vous pouvez mettre à jour une API déployée en modifiant la définition de l'API dans la spécification OpenAPI, puis en important la spécification. L'importation d'une nouvelle spécification crée une nouvelle configuration d'API.
API Gateway accepte un modèle de mise à jour sans interruption, ce qui signifie que votre API continue à gérer les requêtes pendant le déploiement de la configuration d'API mise à jour. Cependant, pendant un certain temps se déroule le déploiement de la nouvelle configuration d'API, lorsque certaines requêtes peuvent toujours être traitées par la version précédente de la configuration d'API.
Si vous avez déployé la configuration d'API sur plusieurs régions et passerelles, vous devez redéployer la configuration d'API mise à jour dans chaque région séparément.