Premiers pas avec Cloud Endpoints dans l'environnement flexible App Engine (.NET) avec ESP

Ce tutoriel vous explique comment configurer et déployer un exemple d'API .NET Core et Extensible Service Proxy (ESP) s'exécutant sur une instance de l'environnement flexible App Engine. L'exemple d'API est décrit à l'aide de la spécification OpenAPI. Le tutoriel vous montre également comment créer une clé API et l'utiliser dans les requêtes adressées à l'API.

Pour obtenir une présentation de Cloud Endpoints, consultez les pages À propos de Cloud Endpoints et Architecture Cloud Endpoints.

Objectifs

Tout au long du tutoriel, reportez-vous au récapitulatif des étapes présenté ci-dessous. Toutes les tâches sont nécessaires pour envoyer des requêtes à l'API.

  1. Configurez un projet Google Cloud , installez les logiciels requis et créez une application App Engine. Consultez la section Avant de commencer.
  2. Téléchargez l'exemple de code. Consultez la section Obtenir l'exemple de code.
  3. Configurez le fichier openapi.yaml, utilisé pour configurer Endpoints. Consultez la section Configurer Endpoints.
  4. Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
  5. Déployez l'exemple d'API et ESP sur App Engine. Consultez la section Déployer le backend de l'API.
  6. Envoyez une requête à l'API. Consultez la section Envoyer une requête à l'API.
  7. Suivez l'activité de l'API. Consultez la section Suivre l'activité de l'API.
  8. Pour éviter que des frais ne soient facturés sur votre compte Google Cloud , Consultez la section Effectuer un nettoyage.

Coûts

Dans ce document, vous utilisez les composants facturables de Google Cloudsuivants :

Vous pouvez obtenir une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Avant de commencer

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Notez l'ID de projet, car il sera nécessaire ultérieurement.
  7. Ce tutoriel nécessite le SDK .NET Core 2.x, que vous pouvez utiliser avec n'importe quel éditeur de texte. Bien qu'un environnement de développement intégré (IDE, Integrated Development Environment) ne soit pas requis, nous vous recommandons d'en utiliser un pour des raisons de commodité. Vous pouvez faire votre choix parmi les IDE suivants :
  8. Vous aurez besoin d'une application pour envoyer des requêtes à l'exemple d'API. Ce tutoriel fournit un exemple d'utilisation de Invoke-WebRequest, compatible avec PowerShell 3.0 et versions ultérieures.

  9. Téléchargez Google Cloud CLI.
  10. Mettez à jour gcloud CLI et installez les composants Endpoints.
    gcloud components update
  11. Assurez-vous que la Google Cloud CLI (gcloud) est autorisée à accéder à vos données et services sur Google Cloud :
    gcloud auth login
    Dans le nouvel onglet de navigateur, sélectionnez un compte.
  12. Définissez le projet par défaut sur votre ID de projet.
    gcloud config set project YOUR_PROJECT_ID

    Remplacez YOUR_PROJECT_ID par l'ID du projet Google Cloud . Si vous avez d'autres projets Google Cloud et que vous souhaitez les gérer à l'aide de gcloud, consultez la page Gérer les configurations de gcloud CLI.

  13. Sélectionnez la région dans laquelle vous souhaitez créer votre application App Engine. Exécutez la commande suivante pour obtenir la liste des régions :
    gcloud app regions list
  14. Créez une application App Engine. Remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloudet YOUR_REGION par la région dans laquelle vous souhaitez créer l'application App Engine.
      gcloud app create \
      --project=YOUR_PROJECT_ID \
      --region=YOUR_REGION
    

Obtenir l'exemple de code

Pour télécharger l'exemple d'API, procédez comme suit :

  1. Téléchargez l'exemple de code sous forme de fichier ZIP.

  2. Extrayez le contenu du fichier ZIP et accédez au répertoire dotnet-docs-samples-master\endpoints\getting-started.

  3. Ouvrez GettingStarted.sln avec Visual Studio ou servez-vous de l'éditeur de votre choix pour modifier les fichiers dans le répertoire endpoints\getting-started\src\IO.Swagger.

Configurer Endpoints

Vous devez disposer d'un document OpenAPI basé sur OpenAPI 2.0 ou OpenAPI 3.x décrivant la surface de vos applications, ainsi que les conditions requises pour l'authentification. Pour en savoir plus, consultez Versions OpenAPI compatibles.

Vous devez également ajouter un champ spécifique à Google contenant l'URL de chaque application afin qu'ESPv2 dispose des informations nécessaires pour appeler une application. Si vous débutez avec OpenAPI, consultez la page Présentation d'OpenAPI pour en savoir plus.

OpenAPI 2.0

Pour configurer Endpoints à l'aide d'une spécification OpenAPI 2.0, vous pouvez utiliser le fichier openapi-appengine.yaml disponible dans le répertoire dotnet-docs-samples-master\endpoints\getting-started de l'exemple de code téléchargé.

Le contenu de la spécification OpenAPI 2.0 doit ressembler à ce qui suit :

swagger: "2.0"
info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.0.0"
host: "YOUR_PROJECT_ID.appspot.com"
consumes:
- "application/json"
produces:
- "application/json"
schemes:
- "https"
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      security:
      - api_key: []
  "/auth/info/googlejwt":
    get:
      description: "Returns the requests' authentication information."
      operationId: "auth_info_google_jwt"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authentication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_jwt:
          audiences:
          # This must match the "aud" field in the JWT. You can add multiple
          # audiences to accept JWTs from multiple clients.
          - "echo.endpoints.sample.google.com"
  "/auth/info/googleidtoken":
    get:
      description: "Returns the requests' authentication information."
      operationId: "authInfoGoogleIdToken"
      produces:
      - "application/json"
      responses:
        200:
          description: "Authenication info."
          schema:
            $ref: "#/definitions/authInfoResponse"
      x-security:
      - google_id_token:
          audiences:
          # Your OAuth2 client's Client ID must be added here. You can add
          # multiple client IDs to accept tokens from multiple clients.
          - "YOUR-CLIENT-ID"

definitions:
  echoMessage:
    type: "object"
    properties:
      message:
        type: "string"
  authInfoResponse:
    properties:
      id:
        type: "string"
      email:
        type: "string"

securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
  # This section configures authentication using Google API Service Accounts
  # to sign a json web token. This is mostly used for server-to-server
  # communication.
  google_jwt:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # This must match the 'iss' field in the JWT.
    x-google-issuer: "jwt-client.endpoints.sample.google.com"
    # Update this with your service account's email address.
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR-SERVICE-ACCOUNT-EMAIL"
  # This section configures authentication using Google OAuth2 ID Tokens.
  # ID Tokens can be obtained using OAuth2 clients, and can be used to access
  # your API on behalf of a particular user.
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"

Sur la ligne comportant le champ "host", remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud .

OpenAPI 3.x

Pour configurer Endpoints à l'aide d'une spécification OpenAPI 3.x, vous pouvez remplacer le contenu du fichier openapi-appengine.yaml disponible dans le répertoire dotnet-docs-samples-master\endpoints\getting-started de l'exemple de code téléchargé :

  1. Ouvrez le fichier openapi-appengine.yaml dans votre éditeur de texte et remplacez son contenu par ce qui suit :
    openapi: 3.0.4
    info:
      description: "A simple Google Cloud Endpoints API example."
      title: "Endpoints Example"
      version: "1.0.0"
    servers:
      - url: "https://YOUR_PROJECT_ID.appspot.com"
        x-google-endpoint: {}
    paths:
      "/echo":
        post:
          description: "Echo back a given message."
          operationId: "echo"
          requestBody:
            description: "Message to echo"
            required: true
            content:
              "application/json":
                schema:
                  $ref: "#/components/schemas/echoMessage"
          responses:
            "200":
              description: "Echo"
              content:
                "application/json":
                  schema:
                    $ref: "#/components/schemas/echoMessage"
          security:
            - api_key: []
      "/auth/info/googlejwt":
        get:
          description: "Returns the requests' authentication information."
          operationId: "auth_info_google_jwt"
          responses:
            "200":
              description: "Authenication info."
              content:
                "application/json":
                  schema:
                    $ref: "#/components/schemas/authInfoResponse"
          security:
            - google_jwt: []
      "/auth/info/googleidtoken":
        get:
          description: "Returns the requests' authentication information."
          operationId: "authInfoGoogleIdToken"
          responses:
            "200":
              description: "Authenication info."
              content:
                "application/json":
                  schema:
                    $ref: "#/components/schemas/authInfoResponse"
          security:
            - google_id_token: []
    
    components:
      schemas:
        echoMessage:
          type: "object"
          properties:
            message:
              type: "string"
        authInfoResponse:
          type: "object"
          properties:
            id:
              type: "string"
            email:
              type: "string"
    
      securitySchemes:
        # This section configures basic authentication with an API key.
        api_key:
          type: apiKey
          name: key
          in: query
        # This section configures authentication using Google API Service Accounts
        # to sign a json web token. This is mostly used for server-to-server
        # communication.
        google_jwt:
          type: oauth2
          flows:
            implicit:
              authorizationUrl: ""
              scopes: {}
          x-google-auth:
            issuer: "jwt-client.endpoints.sample.google.com"
            jwksUri: "https://www.googleapis.com/service_accounts/v1/jwk/YOUR_SERVICE_ACCOUNT_EMAIL"
            audiences:
              - "echo.endpoints.sample.google.com"
            # This must match the "aud" field in the JWT. You can add multiple
            # audiences to accept JWTs from multiple clients.
        # This section configures authentication using Google OAuth2 ID Tokens.
        # ID Tokens can be obtained using OAuth2 clients, and can be used to access
        # your API on behalf of a particular user.
        google_id_token:
          type: oauth2
          flows:
            implicit:
              authorizationUrl: ""
              scopes: {}
          x-google-auth:
            issuer: "https://accounts.google.com"
            jwksUri: "https://www.googleapis.com/oauth2/v1/certs"
            audiences:
              - "YOUR_CLIENT_ID"
  2. Enregistrez le nouveau contenu de openapi.yaml.

Ce tutoriel utilise une extension propre à Google pour la spécification OpenAPI qui vous permet de configurer le nom du service. La méthode pour spécifier le nom du service dépend de la version de la spécification OpenAPI que vous utilisez.

OpenAPI 2.0

Utilisez le champ host pour spécifier le nom du service :

host: YOUR_PROJECT_ID.appspot.com

Pour configurer Endpoints :

  1. Ouvrez le fichier openapi-appengine.yaml.
  2. Dans le champ host, remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud .
  3. Enregistrez le fichier openapi-appengine.yaml.

OpenAPI 3.x

Utilisez le champ url dans l'objet servers pour spécifier le nom du service :

servers:
- url: https://YOUR_PROJECT_ID.appspot.com
  x-google-endpoint: {}

Pour configurer Endpoints :

  1. Ouvrez le fichier openapi-appengine.yaml.
  2. Si votre fichier openapi-appengine.yaml comporte un champ host, supprimez-le.
  3. Ajoutez un objet servers comme indiqué.
  4. Dans le champ url, remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud .
  5. Enregistrez le fichier openapi-appengine.yaml.

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, exécutez la commande gcloud endpoints services deploy. Celle-ci crée un service géré à l'aide de Service Management.

Pour déployer la configuration Endpoints :

  1. Assurez-vous de vous trouver dans le répertoire où se trouve votre fichier de configuration openapi.yaml.
  2. Importez la configuration et créez un service géré :
    gcloud endpoints services deploy openapi.yaml
    

La commande gcloud appelle ensuite l'API Service Management pour créer un service géré avec le nom que vous avez spécifié dans le champ host ou servers.url du fichier openapi.yaml. Service Management configure le service en fonction des paramètres du fichier openapi.yaml. Lorsque vous apportez des modifications au fichier openapi.yaml, vous devez le redéployer pour mettre à jour le service Endpoints.

Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Vous pouvez ignorer en toute sécurité les avertissements concernant les chemins du fichier openapi.yaml qui ne nécessitent pas de clé d'API. Une fois la configuration du service terminée, Service Management affiche un message avec l'ID de configuration du service et le nom du service, comme illustré ci-dessous :

Service Configuration [2017-02-13r0] uploaded for service [example-project-12345.appspot.com]

Dans l'exemple ci-dessus, 2017-02-13r0 correspond à l'ID de configuration du service et example-project-12345.appspot.com au service Endpoints. L'ID de configuration du service se compose d'un horodatage, suivi d'un numéro de révision. Si vous déployez à nouveau le fichier openapi.yaml le même jour, le numéro de révision est incrémenté dans l'ID de configuration de service. Vous pouvez afficher la configuration de service Endpoints sur la page Endpoints > Services de la console Google Cloud .

Si vous recevez un message d'erreur, consultez la section Résoudre des problèmes de déploiement de la configuration Endpoints.

Vérifier les services requis

Endpoints et ESP requièrent au minimum l'activation des services Google suivants :
Nom Titre
servicemanagement.googleapis.com API Service Management
servicecontrol.googleapis.com API Service Control

Dans la plupart des cas, la commande gcloud endpoints services deploy permet d'activer ces services requis. Toutefois, bien que la commande gcloud ait abouti, elle n'active pas les services requis dans les cas suivants :

  • Vous avez utilisé une application tierce telle que Terraform et vous n'incluez pas ces services.

  • Vous avez déployé la configuration Endpoints dans un projetGoogle Cloud existant dans lequel ces services étaient explicitement désactivés.

Utilisez la commande suivante pour vérifier que les services nécessaires sont activés :

gcloud services list

Si les services requis ne sont pas répertoriés, activez-les :

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Activez également votre service Endpoints :

gcloud services enable ENDPOINTS_SERVICE_NAME

Pour déterminer la valeur de ENDPOINTS_SERVICE_NAME, vous pouvez effectuer l'une des opérations suivantes :

  • Après avoir déployé la configuration Endpoints, accédez à la page Endpoints de la console Cloud. La liste des valeurs ENDPOINTS_SERVICE_NAME possibles s'affiche dans la colonne Nom du service.

  • Pour OpenAPI, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ host de votre spécification OpenAPI. Pour gRPC, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ name de votre configuration Endpoints gRPC.

Pour en savoir plus sur les commandes gcloud, consultez la page Services gcloud.

Déployer le backend de l'API

Vous avez déployé le document OpenAPI sur Service Management, mais vous n'avez pas encore déployé le code qui diffuse le backend de l'API. Cette section vous guide dans le déploiement des exemples d'API et de proxy ESP sur App Engine.

Pour déployer le backend de l'API :

  1. Ouvrez le fichier endpoints/getting-started/src/IO.Swagger/app.yaml et ajoutez le nom de votre service :
  2. endpoints_api_service:
      # The following values are to be replaced by information from the output of
      # 'gcloud endpoints services deploy openapi-appengine.yaml' command. If you have
      # previously run the deploy command, you can list your existing configuration
      # ids using the 'configs list' command as follows:
      # 'gcloud endpoints configs list --service=[PROJECT-ID].appspot.com'
      # where [PROJECT-ID].appspot.com is your Endpoints service name.
      name: ENDPOINTS-SERVICE-NAME
      rollout_strategy: managed
    

    Remplacez ENDPOINTS-SERVICE-NAME par le nom de votre service Endpoints. Il s'agit du nom que vous avez configuré dans le champ host du document OpenAPI. Exemple :

    endpoints_api_service:
      name: example-project-12345.appspot.com
      rollout_strategy: managed

    L'option rollout_strategy: managed configure le proxy ESP de sorte qu'il utilise la dernière configuration de service déployée. Si cette option est spécifiée, jusqu'à 5 minutes après le déploiement d'une nouvelle configuration de service, ESP détecte la modification et commence à l'utiliser automatiquement. Nous vous recommandons de spécifier cette option plutôt qu'un ID de configuration spécifique à utiliser par ESP.

  3. Enregistrez le fichier app.yaml.
  4. La section endpoints_api_service étant incluse dans le fichier app.yaml, la commande gcloud app deploy déploie et configure ESP dans un conteneur distinct de votre environnement flexible App Engine. L'intégralité du trafic des requêtes est acheminé via ESP, qui sert de proxy pour les requêtes et les réponses envoyées et reçues par le conteneur qui exécute le code du serveur backend.

  5. Assurez-vous que vous vous trouvez dans le répertoire endpoints/getting-started, où se trouve votre fichier de configuration openapi.yaml.
  6. Déployez l'exemple d'API et ESP dans App Engine :

      dotnet restore
        dotnet publish
        gcloud app deploy src\IO.Swagger\bin\Debug\netcoreapp2.0\publish\app.yaml
    

    La commande gcloud app deploy crée un enregistrement DNS au format YOUR_PROJECT_ID.appspot.com qui doit être utilisé lors de l'envoi de requêtes à l'API. Nous vous recommandons d'attendre quelques minutes et la fin de l'initialisation complète d'App Engine avant d'envoyer des requêtes à votre API.

Si vous recevez un message d'erreur, consultez la section Résoudre des problèmes de déploiement dans l'environnement flexible App Engine.

Pour plus d'informations, consultez la section Déployer le backend de l'API.

Envoyer des requêtes à l'API

Après avoir déployé l'exemple d'API, vous pouvez lui envoyer des requêtes.

Créer une clé API et définir une variable d'environnement

L'exemple de code nécessite une clé API. Pour simplifier la requête, définissez une variable d'environnement pour la clé API.

  1. Dans le même projet Google Cloud que celui utilisé pour votre API, créez une clé API sur la page des identifiants de l'API. Si vous souhaitez créer une clé API dans un autre projet Google Cloud , consultez Activer une API dans votre projet Google Cloud .

    Accéder à la page Identifiants

  2. Cliquez sur Créer les identifiants, puis sélectionnez Clé API.
  3. Copiez la clé dans le presse-papier.
  4. Cliquez sur Fermer.
  5. Sur l'ordinateur local, collez la clé API pour l'attribuer à une variable d'environnement : $Env:ENDPOINTS_KEY="AIza..."

Envoyer la requête

  1. Dans PowerShell, définissez une variable d'environnement pour l'URL de votre projet App Engine. Remplacez YOUR_PROJECT_ID par l'ID du projetGoogle Cloud .

    $Env:ENDPOINTS_HOST="https://YOUR_PROJECT_ID.appspot.com"

  2. Envoyez une requête HTTP à l'aide des variables d'environnement ENDPOINTS_HOST et ENDPOINTS_KEY que vous avez définies précédemment :

    Invoke-WebRequest "$ENDPOINTS_HOST/echo?key=$ENDPOINTS_KEY" `
      -Body '{"message": "hello world"}' -Method POST `
      -ContentType "application/json"
    

Dans l'exemple ci-dessus, les deux premières lignes se terminent par un accent grave. Lorsque vous collez l'exemple dans PowerShell, assurez-vous qu'il n'y a pas d'espace après les accents graves. Pour plus d'informations sur les options utilisées dans l'exemple de requête, consultez la page Invoke-WebRequest dans la documentation Microsoft.

L'API renvoie le message que vous avez envoyé et répond avec les éléments suivants :

{
  "message": "hello world"
}

Si vous ne recevez pas de réponse positive, consultez la section Résoudre des problèmes concernant les erreurs de réponse.

Vous venez de déployer et de tester une API dans Endpoints.

Suivre l'activité de l'API

  1. Affichez les graphiques d'activité de votre API sur la page "Endpoints".

    Accédez à la page Services Endpoints

    Il peut s'écouler quelques instants avant que la requête ne soit reflétée dans les graphiques.

  2. Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux.

    Accéder à la page "Explorateur de journaux"

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Effectuer un nettoyage

Pour plus d'informations sur l'arrêt des services utilisés par ce tutoriel, consultez la page Supprimer une API et des instances d'API.

Étapes suivantes