Déployer une API sur une passerelle

Prérequis

Pour pouvoir déployer une configuration d'API sur API Gateway, assurez-vous d'avoir :

Exigences relatives aux ID de passerelle

La plupart des commandes gcloud présentées ci-dessous nécessitent de spécifier l'ID de la passerelle, au format suivant : GATEWAY_ID. API Gateway applique les exigences suivantes pour l'ID de passerelle :

  • Doit contenir au maximum 49 caractères.
  • Ne doit contenir que des lettres minuscules, des chiffres ou des tirets.
  • Il ne doit pas commencer par un tiret.
  • Il ne doit pas contenir de trait de soulignement.

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

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 :

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

Déployer une configuration d'API sur une passerelle

Utilisez l'outil de ligne de commande gcloud pour déployer une configuration d'API sur une passerelle. Lorsque vous déployez la configuration de l'API, vous devez spécifier le nom de l'API. Si la passerelle n'existe pas déjà pour l'API, cette commande la crée également.

Pour déployer une configuration d'API sur une passerelle, procédez comme suit :

  1. Validez l'ID de projet renvoyé par la commande suivante, afin de vous assurer que la passerelle est créée dans le projet correct.

    gcloud config list project

    Si vous devez changer le projet par défaut, exécutez la commande suivante et remplacez PROJECT_ID par l'ID du projet Google Cloud dans lequel vous souhaitez créer le service :

    gcloud config set project PROJECT_ID
  2. Affichez l'aide de la commande gateway create :

    gcloud api-gateway gateways create --help
  3. Exécutez la commande suivante pour déployer la configuration de l'API sur la passerelle :

    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 l'ID de la nouvelle passerelle. Si la passerelle n'existe pas déjà, cette commande la crée.
    • API_ID spécifie l'ID de l'API API Gateway associée à cette passerelle.
    • CONFIG_ID spécifie l'ID de la configuration d'API déployée sur la passerelle. Vous devez spécifier une configuration d'API lors de la création d'une passerelle.
    • GCP_REGION spécifie la région GCP de la passerelle déployée.

    • PROJECT_ID spécifie l'ID de projet Google Cloud.

    Lors de la création de la passerelle, gcloud envoie des informations au terminal.

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

    Cette commande renvoie les éléments suivants :

    apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
    createTime: '2020-02-05T13:44:12.997862831Z'
    defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
    displayName: GATEWAY_ID
    name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
    serviceAccount:
      email: gateway-111111@222222-tp.iam.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. Pour accéder à une configuration d'API déployée sur cette passerelle, utilisez une URL au format suivant :

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

L'outil de ligne de commande gcloud propose de nombreuses options, y compris celles décrites dans la documentation de référence sur gcloud. De plus, pour API Gateway, vous pouvez définir les options suivantes lors de la création d'une passerelle :

  • --async : rend le contrôle immédiatement au terminal, sans attendre la fin de l'opération.
  • --display-name=NAME : nom à afficher de la passerelle, correspondant au nom affiché dans l'interface utilisateur. N'utilisez pas d'espaces dans le nom. Utilisez plutôt des traits d'union et des traits de soulignement. La valeur par défaut est GATEWAY_ID.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,... : spécifie les libellés associés à la passerelle.

Répertorier les passerelles

Pour répertorier les passerelles d'un projet spécifique, procédez comme suit :

gcloud api-gateway gateways list --project=PROJECT_ID

Cette commande renvoie un résultat au format suivant :

NAME                                                          DISPLAY_NAME  STATE
projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID  GATEWAY_ID    ACTIVE

Pour répertorier les passerelles d'un projet et d'une région spécifiques, procédez comme suit :

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

Utilisez une expression filter pour répertorier les passerelles associées à une API spécifique :

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

Vous pouvez également utiliser cette filter pour répertorier les passerelles pour une configuration d'API spécifique :

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

Utilisez les ID de projet, de région et de passerelle pour obtenir des informations détaillées sur la passerelle, y compris l'identité de la configuration d'API déployée sur la passerelle :

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

Mettre à jour une passerelle

Mettez à jour une passerelle pour :

  • Déployer une autre configuration d'API sur la passerelle
  • Mettre à jour le nom à afficher
  • Mettre à jour les étiquettes.

Utilisez la commande gcloud suivante pour mettre à jour une passerelle existante :

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID  

Par exemple, pour mettre à jour la configuration d'API déployée sur la passerelle :

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID 

NEW_CONFIG_ID spécifie la nouvelle configuration d'API à déployer sur la passerelle.

Pour mettre à jour le nom à afficher, utilisez l'option --display-name. Pour mettre à jour les libellés, exécutez la commande suivante :

  • --update-labels=KEY=VALUE,...
  • --clear-labels
  • --remove-labels=KEY,...

Utilisez la commande suivante pour afficher toutes les options de mise à jour :

gcloud api-gateway gateways update --help

Supprimer une passerelle

Utilisez la commande gcloud suivante pour supprimer une passerelle existante :

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

Étape suivante