Cette page vous explique comment déployer une API sur API Gateway pour sécuriser le trafic vers un service de backend.
Suivez les étapes ci-dessous pour déployer une nouvelle API afin d'accéder à un service de backend sur Cloud Functions à l'aide de l'outil de ligne de commande gcloud
. Ce guide de démarrage rapide explique également comment utiliser une clé API pour protéger votre backend contre les accès non autorisés.
Avant de commencer
Dans Cloud Console, accédez à la page Tableau de bord, puis sélectionnez ou créez un projet Google Cloud.
Vérifiez que la facturation est activée sur votre projet.
Vérifiez que le SDK Cloud est téléchargé et installé sur votre ordinateur.
Mettez à jour les composants
gcloud
:gcloud components update
Définissez le projet par défaut. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud.
gcloud config set project PROJECT_ID
Activer les services requis
API Gateway nécessite l'activation des services Google suivants :
Nom | Titre |
---|---|
apigateway.googleapis.com |
API de la passerelle API |
servicemanagement.googleapis.com |
API Service Management |
servicecontrol.googleapis.com |
API Service Control |
Pour confirmer que les services requis sont activés, procédez comme suit :
gcloud services list
Si les services requis ne sont pas répertoriés, activez-les :
gcloud services enable apigateway.googleapis.comgcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Pour en savoir plus sur les services gcloud
, consultez la section Services gcloud
.
Déployer un backend d'API
API Gateway se trouve devant un service de backend déployé et gère toutes les requêtes entrantes. Dans ce guide de démarrage rapide, API Gateway achemine les appels entrants vers un backend de fonction Cloud nommé helloGET
qui contient la fonction illustrée ci-dessous :
/** * HTTP Cloud Function. * This function is exported by index.js, and is executed when * you make an HTTP request to the deployed function's endpoint. * * @param {Object} req Cloud Function request context. * More info: https://expressjs.com/en/api.html#req * @param {Object} res Cloud Function response context. * More info: https://expressjs.com/en/api.html#res */ exports.helloGET = (req, res) => { res.send('Hello World!'); };
Suivez les étapes du Guide de démarrage rapide : utiliser l'outil de ligne de commande gcloud
pour télécharger l'exemple de code Cloud Functions et déployer le service de backend de la fonction Cloud.
Créer une API
Vous êtes maintenant prêt à créer votre API sur API Gateway.
Saisissez la commande suivante, où :
- API_ID spécifie le nom de votre API. Consultez les exigences concernant les ID d'API pour obtenir des consignes sur l'attribution de noms aux API.
- PROJECT_ID est le nom de votre projet Google Cloud.
gcloud api-gateway apis create API_ID --project=PROJECT_ID
Exemple :
gcloud api-gateway apis create my-api --project=my-project
Si l'opération réussit, vous pouvez utiliser la commande suivante pour afficher les détails de la nouvelle API :
gcloud api-gateway apis describe API_ID --project=PROJECT_ID
Exemple :
gcloud api-gateway apis describe my-api --project=my-project
Cette commande renvoie les éléments suivants :
createTime: '2020-02-29T21:52:20.297426875Z' displayName: my-api managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog name: projects/my-project/locations/global/apis/my-api state: ACTIVE updateTime: '2020-02-29T21:52:20.647923711Z'
Notez la valeur de la propriété managedService
. Cette valeur sera utilisée pour activer votre API lors d'une étape ultérieure.
Créer une configuration d'API
Pour que API Gateway puisse être utilisé afin de gérer le trafic vers votre backend API déployé, il a besoin d'une configuration d'API.
Vous pouvez créer une configuration d'API à l'aide d'une spécification OpenAPI contenant des annotations spécialisées pour définir le comportement souhaité pour API Gateway. La spécification OpenAPI utilisée pour ce guide de démarrage rapide contient des instructions de routage vers le backend de la fonction Cloud :
# openapi2-functions.yaml swagger: '2.0' info: title: API_ID optional-string description: Sample API on API Gateway with a Google Cloud Functions backend version: 1.0.0 schemes: - https produces: - application/json paths: /hello: get: summary: Greet a user operationId: hello x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET responses: '200': description: A successful response schema: type: string
Pour importer cette spécification OpenAPI et créer une configuration d'API à l'aide de l'outil gcloud
:
À partir de la ligne de commande, créez un fichier nommé
openapi2-functions.yaml
.Copiez et collez le contenu de la spécification OpenAPI présentée ci-dessus dans le fichier récemment créé.
Modifiez le fichier comme suit :
- Dans le champ
title
, remplacez API_ID par le nom de votre API et optional-string par une brève description de votre choix. La valeur de ce champ est utilisée lors de la génération de clés API qui accordent l'accès à cette API. - Dans le champ
address
, remplacez GCP_REGION par la région GCP de la fonction déployée et PROJECT_ID par le nom de votre projet Google Cloud.
- Dans le champ
Saisissez la commande suivante, où :
- CONFIG_ID spécifie le nom de votre configuration d'API.
- API_ID spécifie le nom de votre API.
- PROJECT_ID est le nom de votre projet Google Cloud.
- SERVICE_ACCOUNT_EMAIL spécifie le compte de service créé explicitement pour la création de configurations d'API. Pour en savoir plus, consultez la section Configurer un compte de service.
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
Exemple :
gcloud api-gateway api-configs create my-config \ --api=my-api --openapi-spec=openapi2-functions.yaml \ --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
Cette opération peut prendre plusieurs minutes, car la configuration de l'API est propagée dans les systèmes en aval. La création d'une configuration d'API complexe peut prendre jusqu'à dix minutes.
Une fois la configuration de l'API créée, vous pouvez en afficher les détails en exécutant la commande suivante :
gcloud api-gateway api-configs describe CONFIG_ID \ --api=API_ID --project=PROJECT_ID
Exemple :
gcloud api-gateway api-configs describe my-config \ --api=my-api --project=my-project
Le résultat affiche les détails de configuration de votre API, y compris le nom et l'état, comme illustré dans l'exemple ci-dessous :
createTime: '2020-02-07T18:17:01.839180746Z' displayName: my-config gatewayConfig: backendConfig: googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com name: projects/my-project/locations/global/apis/my-api/configs/my-config serviceRollout: rolloutId: 2020-02-07r0 state: ACTIVE updateTime: '2020-02-07T18:17:02.173778118Z'
Créer une passerelle
Déployez maintenant la configuration de l'API sur une passerelle. Le déploiement d'une configuration d'API sur une passerelle définit une URL externe que les clients de l'API peuvent utiliser pour accéder à votre API.
Exécutez la commande suivante pour déployer la configuration d'API que vous venez de créer sur API Gateway :
gcloud api-gateway gateways create GATEWAY_ID \ --api=API_ID --api-config=CONFIG_ID \ --location=GCP_REGION --project=PROJECT_ID
où :
- GATEWAY_ID spécifie le nom de la passerelle.
- API_ID spécifie le nom de l'API API Gateway associée à cette passerelle.
- CONFIG_ID spécifie le nom de la configuration d'API déployée sur la passerelle.
GCP_REGION correspond à la région Google Cloud de la passerelle déployée.
PROJECT_ID est le nom de votre projet Google Cloud.
Exemple :
gcloud api-gateway gateways create my-gateway \ --api=my-api --api-config=my-config \ --location=us-central1 --project=my-project
Si l'opération réussit, utilisez la commande suivante pour afficher les détails de la passerelle :
gcloud api-gateway gateways describe GATEWAY_ID \ --location=GCP_REGION --project=PROJECT_ID
Exemple :
gcloud api-gateway gateways describe my-gateway \ --location=us-central1 --project=my-project
Cette commande renvoie les éléments suivants :
apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config createTime: '2020-02-05T13:44:12.997862831Z' defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev displayName: my-gateway name: projects/my-project/locations/us-central1/gateways/my-gateway serviceAccount: email: 0000000000000-compute@developer.gserviceaccount.com state: ACTIVE updateTime: '2020-02-05T13:45:00.844705087Z'
Notez la valeur de la propriété defaultHostname
. Il s'agit de la partie nom d'hôte de l'URL de la passerelle que vous utilisez pour tester votre déploiement à l'étape suivante.
Tester le déploiement de votre API
Vous pouvez désormais envoyer des requêtes à votre API en utilisant l'URL générée lors du déploiement de votre passerelle.
Saisissez la commande curl
suivante, où :
- DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de la passerelle déployée.
hello
est le chemin d'accès spécifié dans votre configuration d'API.
curl https://DEFAULT_HOSTNAME/hello
Exemple :
curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello
Le résultat est :
Hello World!
Vous avez créé et déployé une passerelle API.
Sécuriser l'accès à l'aide d'une clé API
Pour sécuriser l'accès au backend de votre API, générez une clé API associée à votre projet, puis accordez-lui l'accès à votre API. Pour en savoir plus, consultez la page Restreindre l'accès à une API à l'aide de clés API.
Si aucune clé API n'est associée au projet Google Cloud que vous utilisez dans ce guide de démarrage rapide, vous pouvez en ajouter une en suivant les étapes décrites dans la page Créer une clé API.
Pour sécuriser l'accès à votre passerelle à l'aide d'une clé API :
- Activez la compatibilité avec les clés API pour votre service. Saisissez la commande suivante, où :
- MANAGED_SERVICE_NAME spécifie le nom du service géré créé lors du déploiement de l'API. Vous pouvez l'afficher dans la propriété du service géré répertoriée avec la commande
gcloud apige-gateway apis describe
. - PROJECT_ID est le nom de votre projet Google Cloud.
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
Exemple :gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
- MANAGED_SERVICE_NAME spécifie le nom du service géré créé lors du déploiement de l'API. Vous pouvez l'afficher dans la propriété du service géré répertoriée avec la commande
- Modifiez la spécification OpenAPI utilisée pour créer votre configuration d'API afin d'inclure des instructions permettant d'appliquer une règle de sécurité de validation des clés API sur l'ensemble du trafic. Ajoutez le type
security
etsecurityDefinitions
comme indiqué ci-dessous :# openapi2-functions.yaml swagger: '2.0' info: title: API_ID optional-string description: Sample API on API Gateway with a Google Cloud Functions backend version: 1.0.0 schemes: - https produces: - application/json paths: /hello: get: summary: Greet a user operationId: hello x-google-backend: address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET security: - api_key: [] responses: '200': description: A successful response schema: type: string securityDefinitions: # This section configures basic authentication with an API key. api_key: type: "apiKey" name: "key" in: "query"
securityDefinition
configure votre API de sorte qu'elle exige une clé API transmise en tant que paramètre de requête nommékey
lorsque vous demandez l'accès à tous les chemins définis dans les spécifications. - Créez une configuration d'API avec la spécification OpenAPI modifiée à l'aide de la commande suivante :
gcloud api-gateway api-configs create NEW_CONFIG_ID \ --api=API_ID --openapi-spec=NEW_API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
Exemple :gcloud api-gateway api-configs create my-config-key \ --api=my-api --openapi-spec=openapi2-functions.yaml \ --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com
- Exécutez la commande suivante pour mettre à jour votre passerelle existante avec la nouvelle configuration d'API :
gcloud api-gateway gateways update GATEWAY_ID \ --api=API_ID --api-config=NEW_CONFIG_ID \ --location=GCP_REGION --project=PROJECT_ID
Exemple :gcloud api-gateway gateways update my-gateway \ --api=my-api --api-config=my-config-key \ --location=us-central1 --project=my-project
Tester la clé API
Une fois l'API modifiée créée et déployée, essayez d'envoyer une requête.
Saisissez la commande curl
suivante, où :
- DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de la passerelle déployée.
hello
est le chemin d'accès spécifié dans votre configuration d'API.
curl https://DEFAULT_HOSTNAME/hello
Exemple :
curl https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello
L'erreur suivante devrait se produire :
UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.
Saisissez la commande curl
suivante, où :
- DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de la passerelle déployée.
hello
est le chemin d'accès spécifié dans votre configuration d'API.- API_KEY spécifie la clé API que vous avez créée à l'étape précédente.
curl https://DEFAULT_HOSTNAME/hello?key=API_KEY
Vous devriez maintenant voir Hello World!
dans la réponse de votre API.
Félicitations ! Vous avez correctement protégé votre backend d'API avec API Gateway. Vous pouvez maintenant commencer à intégrer de nouveaux clients API en générant des clés API supplémentaires.
Effectuer un nettoyage
Pour éviter que les ressources utilisées dans ce guide de démarrage rapide soient facturées sur votre compte Google Cloud, vous pouvez supprimer l'API et supprimer les passerelles. Vous pouvez également supprimer le projet Google Cloud utilisé dans ce tutoriel.
Étape suivante
- En savoir plus sur API Gateway
- Découvrez comment configurer l'environnement de développement.