Premiers pas avec API Gateway et Cloud Run

Cette page 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 API Gateway pour votre service de backend Cloud Run.

  1. Créez ou sélectionnez un projet Google Cloud .
  2. Si vous n'avez pas déployé votre propre service Cloud Run, déployez un exemple de service. Consultez l'étape 7 de la section Avant de commencer.
  3. Activez les services API Gateway requis.
  4. Créez une description OpenAPI qui décrit votre API, puis configurez les routes vers votre service de backend Cloud Run. Consultez Créer une configuration d'API.
  5. Déployez une passerelle d'API à l'aide de votre configuration d'API. Consultez Déployer une passerelle d'API.
  6. Suivez l'activité de vos services. Consultez la section Suivre l'activité de l'API.
  7. Éviter que des frais ne soient facturés sur votre compte Google Cloud Consultez Effectuer un nettoyage.

Avant de commencer

  1. Dans la console Google Cloud , accédez à la page Tableau de bord, puis sélectionnez ou créez un projet Google Cloud .

    Accéder à Google Dashboard

  2. Assurez-vous que la facturation est activée pour votre projet.

    Activer la facturation

  3. Notez l'ID du projet que vous souhaitez utiliser pour ce tutoriel. Dans la suite de cette page, cet ID de projet est désigné par PROJECT_ID.

  4. Téléchargez et installez la Google Cloud CLI.

    Télécharger la gcloud CLI

  5. Mettez à jour les composants gcloud :

    gcloud components update

  6. Définissez le projet par défaut. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud .

    gcloud config set project PROJECT_ID

  7. Si vous n'avez pas déployé votre propre service Cloud Run, suivez les étapes de la section Guide de 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 Cloud suivants :

Nom Nom du service
API API Gateway apigateway.googleapis.com
API Service Management servicemanagement.googleapis.com
API Service Control servicecontrol.googleapis.com

Pour activer les services requis :

Console Google Cloud

  1. Dans la console Google Cloud , accédez à la page API et services > Bibliothèque d'API.

    Accéder à la bibliothèque d'API

  2. Sur la page Bibliothèque d'API, saisissez le nom de l'API requise dans la barre de recherche.
  3. Dans les résultats de recherche, sélectionnez la page de l'API.
  4. Sur la page de l'API, cliquez sur Activer.
  5. Répétez ces étapes pour chacun des services listés dans le tableau précédent.

Google Cloud CLI

Exécutez les commandes suivantes pour activer les services :

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 description OpenAPI contenant des annotations spécialisées pour définir le comportement d'API Gateway choisi. 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.

Pour en savoir plus sur les extensions OpenAPI compatibles, consultez les ressources suivantes :

Pour créer votre configuration d'API :

  1. Créez un fichier texte intitulé openapi-run.yaml. Pour plus de commodité, cette page fait référence à la description OpenAPI par ce nom de fichier, mais vous pouvez lui donner un autre nom si vous le souhaitez.
  2. Copiez le contenu du fichier suivant dans votre fichier openapi-run.yaml :

    OpenAPI 2.0

    # openapi-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 encore, la commande de création de 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 création de clés API qui accordent l'accès à cette API. Consultez Exigences concernant l'ID d'API pour connaître les consignes de dénomination des API.
    • Dans le champ address de la section x-google-backend, remplacez APP_URL par l'URL réelle de votre service Cloud Run (le chemin d'accès complet de l'API appelée). Exemple : https://hello-abc1def2gh-uc.a.run.app

    OpenAPI 3.x

    # openapi-run.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Cloud Run backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    cloudrun_backend:
      address: APP_URL
      deadline: 30.0
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: cloudrun_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        "200":
          description: A successful response
          content:
            application/json:
              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 encore, la commande de création de 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 création de clés API qui accordent l'accès à cette API. Consultez Exigences concernant l'ID d'API pour connaître les consignes de dénomination des API.
    • Dans le champ address, remplacez APP_URL par l'URL réelle de votre service Cloud Run (le chemin d'accès complet de l'API appelée). Par exemple : https://hello-687541448612.us-central1.run.app.
  3. 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 spécifie le nom de votre projet Google Cloud .
    • SERVICE_ACCOUNT_EMAIL spécifie le compte de service utilisé pour signer les jetons des backends pour lesquels l'authentification est configurée. Pour plus d'informations, consultez la section Créer un compte de service. 
    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 aux systèmes en aval. La création d'une configuration d'API complexe peut prendre jusqu'à dix minutes.

  4. 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

Déployer une passerelle API Gateway

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 permettant aux clients API d'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 est la Google Cloud région de la passerelle déployée.

  • PROJECT_ID spécifie 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 utiliserez pour tester votre déploiement à l'étape suivante.

Tester le déploiement de l'API

Vous pouvez maintenant envoyer des requêtes à votre API à l'aide de 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 votre passerelle déployée.
  • hello correspond au chemin d'accès spécifié dans la configuration de votre API.
https://DEFAULT_HOSTNAME/hello

Exemple :

https://my-gateway-687541448612.us-central1.run.app/hello

Votre conteneur Cloud Run exécutant votre application doit s'afficher dans le navigateur.

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

Suivre l'activité de l'API

  1. Affichez les graphiques d'activité de votre API sur la page API Gateway de la consoleGoogle Cloud . Cliquez sur votre API pour afficher ses graphiques d'activité sur la page Présentation. Les requêtes n'apparaissent pas immédiatement dans les graphiques.

  2. 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 la consoleGoogle Cloud .

    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 Journaux.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce guide de démarrage rapide ne soient facturées sur votre compte Google Cloud , vous pouvez :

Vous pouvez également supprimer le projet Google Cloud utilisé pour ce tutoriel.