Créer une configuration d'API

Prérequis

Avant de créer une configuration d'API, assurez-vous d'avoir :

Exigences concernant l'ID de configuration de l'API

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

  • Ne doit pas comporter plus de 63 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.

Créer une configuration d'API

Utilisez la Google Cloud CLI pour importer votre définition d'API afin de créer une configuration d'API. Lorsque vous importez la définition de l'API, vous devez spécifier le nom de l'API. Si l'API n'existe pas déjà dans API Gateway, cette commande la crée également.

Pour créer une configuration d'API :

  1. Remplacez le répertoire par celui qui contient la définition de votre API.

    Pour en savoir plus sur la création de la spécification OpenAPI pour votre définition d'API, consultez les pages Présentation d'OpenAPI et Guide de démarrage rapide : Déployer une API sur API Gateway.

    Pour en savoir plus sur la création d'une définition de service gRPC et d'une configuration pour votre définition d'API, consultez la page Configurer un service gRPC. et Premiers pas avec API Gateway et Cloud Run pour gRPC.

  2. Validez l'ID de projet renvoyé par la commande suivante, afin de vous assurer que le service est créé 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
  3. Affichez l'aide de la commande api-configs create :

    gcloud api-gateway api-configs create --help
  4. Exécutez la commande suivante pour créer la configuration d'API :

    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

    où :

    • CONFIG_ID spécifie l'ID de la nouvelle configuration d'API.
    • API_ID spécifie l'ID de l'API API Gateway associée à cette configuration d'API. Si l'API n'existe pas encore, cette commande la crée.
    • API_DEFINITION spécifie le nom de la spécification OpenAPI contenant la définition de l'API.
    • PROJECT_ID spécifie l'ID du 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 en savoir plus, consultez la section Configurer un compte de service.

    Lors de la création de l'API et de la configuration d'API, API Gateway génère des informations au terminal. 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'à 10 minutes s'est déroulée correctement. Lorsque vous créez une configuration, n'essayez pas d'en créer une autre pour la même API. Vous ne pouvez créer qu'une seule configuration pour n'importe quelle API à la fois.

  5. Si l'opération réussit, vous pouvez utiliser la commande suivante pour afficher les détails de la nouvelle configuration d'API :

    gcloud api-gateway api-configs describe CONFIG_ID \
      --api=API_ID --project=PROJECT_ID

    Cette commande renvoie les éléments suivants :

    createTime: '2020-02-04T18:33:11.882707149Z'
    displayName: CONFIG_ID
    gatewayConfig:
      backendConfig:
        googleServiceAccount: 1111111@developer.gserviceaccount.com
    labels: ''
    name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
    serviceRollout:
      rolloutId: 2020-02-04r2
    state: ACTIVE
    updateTime: '2020-02-04T18:33:12.219323647Z'
  6. Activez l'API à l'aide de son nom de service géré. Vous trouverez cette valeur dans la colonne "Service géré" de votre API sur la page de destination des API:

    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

    Vous n'avez besoin d'exécuter cette commande qu'une seule fois lorsque vous créez l'API. Si vous modifiez ultérieurement l'API, vous n'avez pas besoin de réexécuter la commande.

La Google Cloud CLI nécessite de nombreuses options, y compris celles décrites dans le document Documentation de référence gcloud De plus, Pour API Gateway, vous pouvez définir les options suivantes lorsque vous créez une configuration d'API:

  • --async : rend le contrôle immédiatement au terminal, sans attendre la fin de l'opération.
  • --display-name=NAME: spécifie le nom à afficher de la configuration d'API, c'est-à-dire le 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 CONFIG_ID.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,... : spécifie les libellés associés à la configuration d'API.

Exemple :

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 \
  --async --display-name=MyConfig --labels=a=1,b=2

Vous pouvez afficher les libellés dans le résultat de la commande describe présentée ci-dessus ou dans la commande list en incluant l'option --format :

gcloud api-gateway api-configs list \
  --api=API_ID --project=PROJECT_ID --format="table(name, labels)"

Configurations de l'API de listing

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

gcloud api-gateway api-configs list --project=PROJECT_ID

Cette commande renvoie les éléments suivants :

NAME                                                                DISPLAY_NAME  ROLLOUT_ID    STATE   CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

Pour répertorier les configurations d'API pour une API spécifique dans un projet :

gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID

Utilisez les ID de projet, d'API et de configuration pour obtenir des informations détaillées sur la configuration d'API :

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

Mettre à jour une configuration d'API

Vous ne pouvez modifier une configuration d'API existante que pour mettre à jour ses libellés et son nom à afficher.

Utilisez le fichier gcloud suivant pour mettre à jour une configuration d'API existante :

  • --display-name
  • --update-labels
  • --clear-labels
  • --remove-labels

Exemple :

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID  --project=PROJECT_ID \
  --update-labels=a=1,b=2

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

gcloud api-gateway api-configs update --help

Supprimer une configuration d'API

Utilisez la commande gcloud suivante pour supprimer une configuration d'API existante :

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

Étape suivante