Guide de démarrage rapide : déployer une API sur API Gateway avec l'outil de ligne de commande gcloud

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.
Accéder à la page "Tableau de bord"

Remarque : Si vous ne prévoyez pas de conserver les ressources créées au cours de cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.
Vérifiez que la facturation est activée sur votre projet.
Découvrir comment activer la facturation
Vérifiez que le SDK Cloud est téléchargé et installé sur votre ordinateur.
Télécharger le SDK Cloud
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.com
gcloud 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 :
1. 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.
2. 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.
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.
  Remarque : Le compte de service utilisé pour créer une configuration d'API pour un backend Cloud Functions doit disposer du rôle cloudfunctions.invoker.
```
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.

Remarque : Si vous exécutez cette commande et recevez une erreur au format FAILED_PRECONDITION: Service Account ... does not exist, consultez la section Configurer un compte de service pour vous assurer qu'un compte de service est activé pour votre projet.
Remarque : Vous ne pouvez créer qu'une seule configuration d'API à la fois pour une API donnée. Attendez la fin de la création de la configuration avant d'essayer de créer une configuration pour la même API.

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.
Remarque :
Les valeurs autorisées sont les suivantes :
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-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.
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
```

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 et securityDefinitions 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.