Premiers pas avec API Gateway et Cloud Run

Cette page vous explique comment configurer API Gateway pour gérer et sécuriser un service de backend Cloud Run.

Liste de tâches

Tout au long du tutoriel, reportez-vous à la liste de tâches présentée ci-dessous. Toutes les tâches sont requises pour déployer une passerelle API pour votre service de backend Cloud Run.

Créez ou sélectionnez un projet Google Cloud.
Si vous n'avez pas déployé votre propre environnement Cloud Run, déployez un exemple de service. Reportez-vous à l'étape 8 de la page Avant de commencer.
Activez les services API Gateway requis.
Créez une spécification OpenAPI décrivant votre API, puis configurez les routes vers votre service de backend Cloud Run. Consultez la section Créer une configuration d'API.
Déployez une passerelle API à l'aide de la configuration de votre API. Consultez la section Déployer une passerelle API.
Suivez l'activité de vos services. Consultez la section Suivre l'activité de l'API.
Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Effectuer un nettoyage.

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 dans ce tutoriel, 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.
Assurez-vous que la facturation est activée pour votre projet.
Découvrir comment activer la facturation
Notez l'ID de projet que vous souhaitez utiliser pour ce tutoriel. Sur le reste de cette page, cet ID est appelé PROJECT_ID.
Téléchargez et installez le SDK Cloud.
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
```
Si vous n'avez pas encore déployé votre propre service Cloud Run, suivez la procédure décrite dans le guide Démarrage rapide : Déployer un exemple de conteneur prédéfini pour sélectionner ou créer un projet Google Cloud, et déployer un exemple de backend. Notez l'URL de l'application, ainsi que la région et l'ID du projet dans lequel vos applications sont déployées.

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.

Créer une configuration d'API

Pour que API Gateway puisse être utilisé afin de gérer le trafic vers votre backend Cloud Run 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. Vous devez ajouter un champ spécifique à Google contenant l'URL de chaque application Cloud Run afin qu'API Gateway dispose des informations nécessaires pour appeler une application.

Créez un fichier texte intitulé openapi2-run.yaml. Pour des raisons de commodité, cet article utilise ce nom de fichier pour désigner la spécification OpenAPI, mais vous pouvez le nommer autrement si vous préférez.

Répertoriez chacune de vos applications dans la section paths du fichier openapi2-run.yaml, comme indiqué ci-dessous :

# openapi2-run.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: APP_URL
paths:
  /assets/{asset}:
    get:
      parameters:
        - in: path
          name: asset
          type: string
          required: true
          description: Name of the asset.
      summary: Assets
      operationId: getAsset
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /hello:
    get:
      summary: Cloud Run hello world
      operationId: hello
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Dans le champ title, remplacez API_ID par le nom de votre API et optional-string par une brève description de votre choix. Si votre API n'existe pas déjà, la commande permettant de créer la configuration d'API créera également l'API avec le nom que vous spécifiez. La valeur du champ title est utilisée lors de la génération de clés API qui accordent l'accès à cette API. Consultez les exigences concernant les ID d'API pour obtenir des consignes sur l'attribution de noms aux API.
Dans le champ address de la section x-google-backend, remplacez APP_URL par l'URL réelle de votre service Cloud Run.
Remarque : Si vous prévoyez d'utiliser des tags de révision pour gérer le backend de votre service Cloud Run, vous devez spécifier le champ jwt_audience sous address dans la section x-google-backend. La valeur du champ jwt_audience doit être l'URL du service Cloud Run. Exemple :
```
...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...
```
Si le champ jwt_audience n'est pas présent, l'extension x-google-backend utilise par défaut la valeur du champ address pour la revendication d'audience JWT. Cela peut entraîner une revendication d'audience JWT inattendue pour Cloud Run si l'URL du tag de révision est utilisée pour address et qu'aucun élément jwt_audience n'est spécifié.
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. Si l'API n'existe pas déjà, cette commande la crée.
- 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 plus d'informations, consultez la section Créer un compte de service.
  Remarque : Le compte de service utilisé pour créer une configuration d'API pour un backend Cloud Run doit disposer du rôle run.invoker.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=openapi2-run.yaml \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
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
```

Déployer une passerelle API

Vous pouvez maintenant déployer votre API sur API Gateway. Le déploiement d'une API sur API Gateway définit également 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.

Si l'opération réussit, vous pouvez utiliser la commande suivante pour afficher les détails de la passerelle :

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Notez la valeur de la propriété defaultHostname dans le résultat de cette commande. 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.

Dans votre navigateur Web, saisissez l'URL 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.

https://DEFAULT_HOSTNAME/hello

Exemple :

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Vous devriez voir votre conteneur Cloud Run exécuter votre application dans le navigateur.

Opération réussie. Votre passerelle API gère l'accès à votre service de backend Cloud Run.

Suivre l'activité de l'API

Consultez les graphiques d'activité de votre API sur la page API Gateway dans Cloud Console. Cliquez sur votre API pour afficher ses graphiques d'activité sur la page Overview (Présentation). Les requêtes n'apparaissent pas immédiatement dans les graphiques.
Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux. Un lien vers la page Explorateur de journaux est disponible sur la page API Gateway de Cloud Console.
Accéder à la page API Gateway
Une fois sur la page API Gateway :
1. Sélectionnez l'API à afficher.
2. Cliquez sur l'onglet Détails.
3. Cliquez sur le lien sous Logs (Journaux).

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.