Créer une API

Prérequis

Pour pouvoir créer une API sur API Gateway, assurez-vous d'avoir :

• Préparé votre environnement de développement, comme décrit dans la section Configurer votre environnement de développement.

Exigences relatives à l'ID d'API

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

• Doit contenir 63 caractères au maximum.
• 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 API

Pour créer une API :

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

   Si l'ID du projet contient le signe deux-points (:), consultez la section Projets à l'échelle du domaine pour en savoir plus sur la création d'une API dans votre projet.

2. Affichez l'aide de la commande apis create :

   gcloud api-gateway apis create --help

3. Exécutez la commande suivante pour créer l'API :

   gcloud api-gateway apis create API_ID --project=PROJECT_ID

   où :

   • API_ID spécifie l'ID de la nouvelle API. Consultez les exigences concernant les ID d'API pour obtenir des consignes sur l'attribution de noms aux API.
   • PROJECT_ID spécifie l'ID de projet Google Cloud.

   Lors de la création de l'API, la passerelle API 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 nouvelle API :

   gcloud api-gateway apis describe API_ID --project=PROJECT_ID

   Cette commande renvoie les éléments suivants :

   createTime: '2020-02-29T21:52:20.297426875Z'
   displayName: API_ID
   managedService: MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
   name: projects/PROJECT_ID/locations/global/apis/API_ID
   state: ACTIVE
   updateTime: '2020-02-29T21:52:20.647923711Z'

Options gcloud

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 l'API Gateway, vous pouvez définir les options suivantes lors de la création d'une 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 l'API, qui correspond 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 API_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,... : spécifie les libellés associés à la configuration d'API.
• --managed-service : spécifie un service géré préexistant (par exemple, un service Endpoints existant) pour l'API.

Projets à l'échelle du domaine

Si votre projet est à l'échelle de votre domaine, l'ID de projet comprend le nom du domaine suivi par deux points (:) ; par exemple, example.com:my-project. Vous devez fournir un service géré valide lors de la création d'une API dans un projet à l'échelle du domaine.

Si vous utilisez gcloud, indiquez le nom du service géré à l'aide de l'option --managed-service, comme décrit dans gcloud options.

Remarque : La définition de projets à l'échelle d'un domaine est une ancienne fonctionnalité. Il n'est plus possible de créer des projets à l'échelle du domaine.

Répertorier des API

Pour répertorier toutes les API d'un projet, procédez comme suit :

gcloud api-gateway apis list --project=PROJECT_ID

Cette commande renvoie un résultat au format suivant :

NAME                                              DISPLAY_NAME  MANAGED_SERVICE                          STATE
projects/PROJECT_ID/locations/global/apis/API_ID  API_ID        MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog  ACTIVE

Utilisez l'ID du projet et l'ID de l'API pour obtenir des informations détaillées sur l'API :

gcloud api-gateway apis describe API_ID --project=PROJECT_ID

Mettre à jour une API

Après la création, vous pouvez mettre à jour les libellés et le nom à afficher d'une API existante. Utilisez les options gcloud suivantes pour mettre à jour une API existante :

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

Exemple :

gcloud api-gateway apis update 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 apis update --help

Supprimer une API

Pour supprimer une API, vous devez :

• Supprimer les configurations d'API associées à l'API.
• Supprimer l'API.

Remarque : Si vous avez déployé une configuration d'API sur une passerelle, la suppression de l'API interrompt la diffusion du trafic. Toutefois, vous n'êtes pas obligé de supprimer la passerelle. À la place, vous pouvez déployer une configuration d'API d'une autre API vers la passerelle.

Pour supprimer une API :

1. Déterminez la liste des configurations d'API associées à l'API :

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

2. Supprimez chaque configuration d'API associée à l'API :

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

3. Supprimez l'API :

   gcloud api-gateway apis delete API_ID --project=PROJECT_ID

Étape suivante

• Créer une configuration d'API