Cette page a été traduite par l'API Cloud Translation.

Sécuriser le trafic vers un service avec la gcloud CLI

Cette page explique comment déployer une API sur API Gateway pour sécuriser le trafic vers un service de backend.

Suivez les étapes ci-dessous pour déployer une nouvelle API afin d'accéder à un service de backend sur des fonctions Cloud Run à l'aide de la Google Cloud CLI. Ce guide de démarrage rapide explique également comment utiliser une clé API pour protéger votre backend contre les accès non autorisés.

Avant de commencer

Dans la console Google Cloud, 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 au cours de cette procédure, 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.
Vérifiez que la facturation est activée sur votre projet.
Découvrir comment activer la facturation
Assurez-vous que la Google Cloud CLI est téléchargée et installée sur votre ordinateur.
Télécharger la gcloud CLI
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
```

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.

Déployer un backend d'API

API Gateway se situe devant un service de backend déployé et gère toutes les requêtes entrantes. Dans ce guide de démarrage rapide, API Gateway achemine les appels entrants vers un backend de fonction Cloud Run nommé helloGET qui contient la fonction illustrée ci-dessous :

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Suivez les étapes de la section Démarrage rapide: utiliser la Google Cloud CLI pour télécharger l'exemple de code des fonctions Cloud Run et déployer le service de backend de la fonction Cloud Run.

Créer une API

Vous êtes maintenant prêt à créer votre API sur API Gateway.

Saisissez la commande suivante, où :
- API_ID spécifie le nom de votre API. Consultez la section Exigences concernant les ID d'API pour connaître les consignes de dénomination des API.
- PROJECT_ID est le nom de votre projet Google Cloud.
```
gcloud api-gateway apis create API_ID --project=PROJECT_ID
```
Exemple :
```
gcloud api-gateway apis create my-api --project=my-project
```

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

Exemple :

gcloud api-gateway apis describe my-api --project=my-project

Cette commande renvoie les éléments suivants :

  createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

Notez la valeur de la propriété managedService. Cette valeur est utilisée pour activer votre API lors d'une étape ultérieure.

Créer une configuration d'API

Pour que API Gateway puisse être utilisé afin de gérer le trafic vers votre backend API 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 la passerelle API. La spécification OpenAPI utilisée pour ce guide de démarrage rapide contient des instructions de routage vers le backend de notre fonction Cloud Run :

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Pour importer cette spécification OpenAPI et créer une configuration d'API à l'aide de la gcloud CLI:

Sur la ligne de commande, créez un fichier nommé openapi2-functions.yaml.
Copiez et collez le contenu de la spécification OpenAPI ci-dessus dans le fichier que vous venez de créer.
Modifiez le fichier comme suit :
1. Dans le champ title, remplacez API_ID par le nom de votre API et optional-string par une brève description de votre choix. La valeur de ce champ est utilisée lors de la génération des clés API qui accordent l'accès à cette API.
2. Dans le champ address, remplacez GCP_REGION par la région GCP de la fonction déployée et PROJECT_ID par le nom de votre projet Google Cloud.
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.
- API_DEFINITION spécifie le nom de fichier de la spécification OpenAPI.
- PROJECT_ID est le nom de votre projet Google Cloud.
- SERVICE_ACCOUNT_EMAIL spécifie le compte de service utilisé pour signer les jetons des backends sur lesquels l'authentification est configurée. Pour en savoir plus, consultez la section Configurer un compte de service.
  Remarque : Le rôle cloudfunctions.invoker doit être attribué au compte de service utilisé pour créer une configuration d'API pour un backend de fonctions Cloud Run.
```
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
```
Exemple :
```
gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
```
Cette opération peut prendre plusieurs minutes, car la configuration de l'API est propagée vers systèmes en aval. La création d'une configuration d'API complexe peut prendre jusqu'à 10 minutes s'est déroulée correctement.

Remarque : Si vous exécutez cette commande et que vous recevez un message d'erreur au format FAILED_PRECONDITION: Service Account ... does not exist, consultez la section Configurer un compte de service pour vous assurer qu'un compte de service est activé pour votre projet.
Remarque : Vous ne pouvez créer qu'une seule configuration d'API à la fois pour une API donnée. Attendre tant que la configuration n'a pas été créée. pour la même API.

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

Exemple :

gcloud api-gateway api-configs describe my-config \
  --api=my-api --project=my-project

Le résultat affiche les détails de configuration de votre API, y compris le nom et l'état, comme illustré dans l'exemple ci-dessous :

createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

Créer une passerelle

Déployez maintenant la configuration de l'API sur une passerelle. Le déploiement d'une configuration d'API sur une passerelle définit une URL externe que les clients 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
PROJECT_ID est le nom de votre projet Google Cloud.

Exemple :

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1 --project=my-project

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

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

Exemple :

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1 --project=my-project

Cette commande renvoie les éléments suivants :

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.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 que vous utiliserez pour tester votre déploiement à l'étape suivante.

Tester le déploiement de votre 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.

Saisissez la commande curl suivante, où :

DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de votre passerelle déployée.
hello est le chemin d'accès spécifié dans la configuration de l'API.

curl https://DEFAULT_HOSTNAME/hello

Exemple :

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

Le résultat est :

Hello World!

Vous avez réussi à créer et à déployer une passerelle API.

Sécuriser l'accès avec une clé API

Pour sécuriser l'accès au backend de votre API, générez une clé API associée à votre projet et accordez-lui l'accès nécessaire pour appeler votre API. Pour en savoir plus, consultez Restreindre l'accès à une API à l'aide de clés API.

Si aucune clé API n'est associée au projet Google Cloud que vous utilisez dans ce guide de démarrage rapide, vous pouvez en ajouter une en suivant la procédure décrite dans Créer une clé API.

Pour sécuriser l'accès à votre passerelle à l'aide d'une clé API :

Activez la prise en charge des clés API pour votre service. Saisissez la commande suivante, où:
- MANAGED_SERVICE_NAME spécifie le nom du service géré créé lors du déploiement de l'API. Vous pouvez afficher cette information dans la propriété de service géré répertoriée à l'aide de la commande gcloud apigee-gateway apis describe.
- PROJECT_ID est le nom de votre projet Google Cloud.
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
Par exemple:
```
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
```

Modifiez la spécification OpenAPI utilisée pour créer la configuration de votre API afin d'inclure des instructions permettant d'appliquer une stratégie de sécurité pour la validation des clés API à tout le trafic. Ajoutez le type security et securityDefinitions comme indiqué ci-dessous :

  # openapi2-functions.yaml
  swagger: '2.0'
  info:
    title: API_ID optional-string
    description: Sample API on API Gateway with a Google Cloud Functions backend
    version: 1.0.0
  schemes:
    - https
  produces:
    - application/json
  paths:
    /hello:
      get:
        summary: Greet a user
        operationId: hello
        x-google-backend:
          address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/helloGET
        security:
        - api_key: []
        responses:
          '200':
            description: A successful response
            schema:
              type: string
  securityDefinitions:
    # This section configures basic authentication with an API key.
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"

Le securityDefinition configure votre API pour qu'elle exige une clé API transmis en tant que paramètre de requête nommé key lors de la demande d'accès tous les chemins d'accès définis dans la spécification.

Créez une configuration d'API avec la spécification OpenAPI modifiée à l'aide de la commande suivante :

gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Par exemple:

gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com

Exécutez la commande suivante pour mettre à jour votre passerelle existante avec la nouvelle configuration d'API :

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

Par exemple:

gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1 --project=my-project

Tester votre clé API

Une fois que vous avez créé et déployé l'API modifiée, envoyez-lui une requête.

Saisissez la commande curl suivante, où :

DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de votre passerelle déployée.
hello est le chemin d'accès spécifié dans la configuration de l'API.

curl https://DEFAULT_HOSTNAME/hello

Exemple :

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

L'erreur suivante devrait se produire :

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Saisissez la commande curl suivante, où :

DEFAULT_HOSTNAME spécifie la partie nom d'hôte de l'URL de votre passerelle déployée.
hello est le chemin d'accès spécifié dans la configuration de l'API.
API_KEY spécifie la clé API que vous avez créée à l'étape précédente.

curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Vous devriez maintenant voir Hello World! dans la réponse de votre API.

Félicitations ! Vous avez réussi à protéger le backend de votre API avec une passerelle API. Vous pouvez maintenant commencer à intégrer de nouveaux clients API en générant d'autres clés API.

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:

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

Étape suivante

En savoir plus sur API Gateway
Suivez la procédure Configurer l'environnement de développement.
Découvrez comment s'authentifier entre différents services.