Introducción a Cloud Endpoints en el entorno flexible de App Engine (.NET) con ESP

En este instructivo se muestra cómo configurar y, luego, implementar una API de .NET core de muestra y el Proxy de servicio extensible (ESP) que se ejecutan en una instancia del entorno flexible de App Engine. La API de ejemplo se describe con la especificación de OpenAPI. En el instructivo también se muestra cómo crear una clave de API y usarla en solicitudes a la API.

Para obtener una descripción general de Cloud Endpoints, consulta Acerca de Endpoints y la descripción de la arquitectura de Cloud Endpoints.

Objetivos

Usa la siguiente lista de tareas de alto nivel a medida que avanzas en el instructivo. Todas las tareas son necesarias para enviar solicitudes a la API con éxito.

1. Configura un Google Cloud proyecto, instala el software requerido y crea una aplicación de App Engine. Consulta Antes de comenzar.
2. Descarga el código de muestra. Consulta Cómo descargar el código de muestra.
3. Configura el archivo openapi.yaml, que se usa para configurar Endpoints. Consulta Cómo configurar Endpoints.
4. Implementa la configuración de Endpoints para crear un servicio de este sistema. Consulta Cómo configurar Endpoints.
5. Implementa la API y el ESP de muestra en App Engine. Consulta Implementa el backend de la API.
6. Envía una solicitud a la API. Consulta Enviar una solicitud a la API.
7. Realiza un seguimiento de la actividad de la API. Consulta Cómo realizar un seguimiento de la actividad de la API.
8. Evita que se apliquen cargos a tu cuenta de Google Cloud . Consulta Limpieza.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

• App Engine
• Endpoints

Para obtener una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza una limpieza.

Antes de comenzar

Antes de comenzar

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.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Toma nota del ID del proyecto, ya que será necesario más tarde.
2. Este instructivo requiere el SDK de .NET Core 2.x, que puedes usar con cualquier editor de texto. Aunque no se necesita un entorno de desarrollo integrado (IDE), te recomendamos, para tu comodidad, que uses uno de los IDE que aparecen a continuación:
   • Visual Studio Code, que es compatible con macOS, Linux y Windows. Si usas Visual Studio Code, también debes instalar .NET Core 2.x.
   • Visual Studio 2017 para Windows, que incluye .NET Core 2.x. Si usas Visual Studio 2017, te recomendamos que uses el complemento de Google Tools for Visual Studio, que integra la implementación de App Engine en el IDE.
   • Visual Studio para Mac, que incluye .NET Core 2.x.

3. Necesitas una aplicación para enviar solicitudes a la API de muestra. En este instructivo se proporciona un ejemplo del uso de Invoke-WebRequest, que es compatible con PowerShell 3.0 y versiones posteriores.

4. Descarga Google Cloud CLI.
5. Actualiza gcloud CLI y, luego, instala los componentes de Endpoints.

   gcloud components update

6. Asegúrate de que Google Cloud CLI (gcloud) esté autorizada para acceder a tus datos y servicios en Google Cloud:

   gcloud auth login

   En la nueva pestaña del navegador que se abre, selecciona una cuenta.
7. Configura el proyecto predeterminado con el ID de tu proyecto.

   gcloud config set project YOUR_PROJECT_ID

   Reemplaza YOUR_PROJECT_ID por el ID del proyecto de Google Cloud . Si tienes otros proyectos de Google Cloud y deseas usar gcloud para administrarlos, consulta Cómo gcloud CLI de gcloud.

8. Selecciona la región en la que deseas crear tu aplicación de App Engine. Ejecuta el siguiente comando para obtener una lista de regiones:

   gcloud app regions list

9. Crea una aplicación de App Engine. Reemplaza YOUR_PROJECT_ID por el ID del proyecto de Google Cloudy YOUR_REGION por la región en la que deseas que se cree la aplicación de App Engine.

     gcloud app create \
     --project=YOUR_PROJECT_ID \
     --region=YOUR_REGION
   

Obtén el código de muestra

Para descargar la API de muestra:

1. Descarga el código de muestra como un archivo ZIP.

2. Extrae el archivo ZIP y cambia al directorio dotnet-docs-samples-master\endpoints\getting-started.

3. Abre GettingStarted.sln con Visual Studio, o usa tu editor favorito para editar los archivos en el directorio endpoints\getting-started\src\IO.Swagger.

Configura Endpoints

Debes tener un documento de OpenAPI basado en OpenAPI 2.0 o OpenAPI 3.x que describa la superficie de tus apps y cualquier requisito de autenticación. Para obtener más información, consulta Versiones compatibles de OpenAPI.

También debes agregar un campo específico de Google que contenga la URL de cada app para que ESPv2 tenga la información necesaria para invocar una app. Si es la primera vez que usas OpenAPI, consulta la descripción general de OpenAPI para obtener más información.

OpenAPI 2.0

Para configurar Endpoints con una especificación de OpenAPI 2.0, puedes usar el archivo openapi-appengine.yaml disponible en el directorio dotnet-docs-samples-master\endpoints\getting-started del código de muestra descargado.

El contenido de la especificación de OpenAPI 2.0 debería ser similar al siguiente:

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"

En la línea con el campo host, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto Google Cloud .

OpenAPI 3.x

Para configurar Endpoints con una especificación de OpenAPI 3.x, puedes reemplazar el contenido del archivo openapi-appengine.yaml disponible en el directorio dotnet-docs-samples-master\endpoints\getting-started del código de muestra descargado:

1. Abre openapi-appengine.yaml en tu editor de texto y reemplaza el contenido por lo siguiente:

   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. Guarda el contenido nuevo de openapi.yaml.

Nota: El archivo de ejemplo openapi-appengine.yaml contiene una sección para configurar la autenticación que no se necesita en este instructivo. No necesitas configurar las líneas con YOUR_SERVICE_ACCOUNT_EMAIL y YOUR_CLIENT_ID.

En este instructivo, se usa una extensión específica de Google para la especificación de OpenAPI que te permite configurar el nombre del servicio. El método para especificar el nombre del servicio depende de la versión de la especificación de OpenAPI que uses.

OpenAPI 2.0

Usa el campo host para especificar el nombre del servicio:

host: YOUR_PROJECT_ID.appspot.com

Para configurar Endpoints, haz lo siguiente:

1. Abre el archivo openapi-appengine.yaml.
2. En el campo host, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto Google Cloud .
3. Guarda el archivo openapi-appengine.yaml.

OpenAPI 3.x

Usa el campo url en el objeto servers para especificar el nombre del servicio:

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

Para configurar Endpoints, haz lo siguiente:

1. Abre el archivo openapi-appengine.yaml.
2. Si tu archivo openapi-appengine.yaml tiene un campo host, quítalo.
3. Agrega un objeto servers como se muestra.
4. En el campo url, reemplaza YOUR_PROJECT_ID por el ID de tu proyecto Google Cloud .
5. Guarda el archivo openapi-appengine.yaml.

Nota: Debes incluir x-google-endpoint: {} en el objeto server para especificar la URL correcta que deben usar los servidores. Se pueden incluir otros servidores en esta lista, pero exactamente uno debe tener x-google-endpoint: {} para especificar el correcto. Se ignorarán todas las demás.

Implementa la configuración de Endpoints

Para implementar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa la Administración de servicios para crear un servicio administrado.

Para implementar la configuración de Endpoints, haz lo siguiente:

1. Asegúrate de estar en el directorio en el que se encuentra tu archivo de configuración openapi.yaml.
2. Sube la configuración y crea un servicio administrado.

   gcloud endpoints services deploy openapi.yaml
   

Entonces, el comando gcloud llama a la API de Service Management para crear un servicio administrado con el nombre que especificaste en el campo host o servers.url del archivo openapi.yaml. La Administración de servicios configura el servicio de acuerdo con la configuración del archivo openapi.yaml. Cuando realizas cambios en openapi.yaml, debes volver a implementar el archivo para actualizar el servicio de Endpoints.

Mientras se crea y configura el servicio, la Administración de servicios exporta la información a la terminal. Puedes ignorar sin riesgo las advertencias que indican que las rutas de acceso en el archivo openapi.yaml no requieren una clave de API. Cuando termina de configurarse el servicio, la Administración de servicios muestra un mensaje con el ID de configuración del servicio y el nombre del servicio, de manera similar a este ejemplo:

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

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y example-project-12345.appspot.com es el servicio de Endpoints. El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si implementas el archivo openapi.yaml otra vez el mismo día, el número de revisión aumenta en el ID de configuración del servicio. Puedes ver la configuración del servicio de Endpoints en la página Endpoints > Servicios de la Google Cloud consola.

Si recibes un mensaje de error, consulta Cómo solucionar problemas en la implementación de la configuración de Endpoints.

Verifica los servicios requeridos

Como mínimo, Endpoints y ESP requieren que se habiliten los siguientes servicios de Google:

Name	Título
servicemanagement.googleapis.com	API de Administración de servicios
servicecontrol.googleapis.com	Service Control API

En la mayoría de los casos, el comando de gcloud endpoints services deploy habilita estos servicios obligatorios. Sin embargo, el comando gcloud se completa de manera correcta sin habilitar los servicios requeridos en las circunstancias siguientes:

• Usaste una aplicación de terceros, como Terraform, y no incluiste estos servicios.

• Implementaste la configuración de Endpoints en un proyecto deGoogle Cloud existente en el que estos servicios se inhabilitaron de forma explícita.

Usa el siguiente comando para confirmar que los servicios requeridos están habilitados:

gcloud services list

Si no ves los servicios necesarios que se incluyeron en la lista, habilítalos:

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

También habilita el servicio de Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

Para determinar la variable ENDPOINTS_SERVICE_NAME, puedes hacer lo siguiente:

• Después de implementar la configuración de Endpoints, ve a la página Endpoints en la consola de Cloud. La lista de posibles ENDPOINTS_SERVICE_NAME se muestra en la columna Nombre del servicio.

• Para OpenAPI, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo host de tu especificación de OpenAPI. Para gRPC, el ENDPOINTS_SERVICE_NAME es lo que especificaste en el campo name de tu configuración de Endpoints de gRPC.

Para obtener más información sobre los comandos gcloud, consulta servicios de gcloud.

Cómo implementar el backend de la API

Hasta ahora, implementaste la configuración de OpenAPI en Service Management, pero aún no has implementado el código que entregará el backend de la API. En esta sección se explica cómo implementar el ESP y la API de muestra en App Engine.

Para implementar el backend de la API, sigue estos pasos:

1. Abre el archivo endpoints/getting-started/src/IO.Swagger/app.yaml y agrega el nombre del servicio:
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

Reemplaza ENDPOINTS-SERVICE-NAME por el nombre de tu servicio de Endpoints. Este es el mismo nombre que configuraste en el campo host de tu documento de OpenAPI. Por ejemplo:

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

La opción rollout_strategy: managed configura el ESP para que use la configuración del servicio implementado más reciente. Cuando especificas esta opción, el ESP detecta el cambio y comienza a usarlo automáticamente hasta 5 minutos después de implementar una nueva configuración de servicio. Recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que use el ESP.

2. Guarda el archivo app.yaml.

Debido a que la sección endpoints_api_service se incluye en el archivo app.yaml, el comando gcloud app deploy implementa y configura el ESP en un contenedor separado en tu entorno flexible de App Engine. Todo el tráfico de solicitudes se enruta a través del ESP, y procesa solicitudes y respuestas hacia el contenedor, y desde este, el cual ejecuta el código de servidor de backend.

3. Asegúrate de que estés en el directorio endpoints/getting-started, que es donde se encuentra el archivo de configuración openapi.yaml.
4. Implementa la API y el ESP de muestra en App Engine:

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

   El comando gcloud app deploy crea un registro DNS en el formato YOUR_PROJECT_ID.appspot.com, que se usa cuando envías solicitudes a la API. Te recomendamos que esperes unos minutos antes de enviar solicitudes a tu API mientras App Engine se inicializa del todo.

Si recibes un mensaje de error, consulta Solucionar problemas en la implementación de App Engine Flexible.

Para obtener más información, consulta Implementar el backend de la API.

Cómo enviar solicitudes a la API

Después de implementar la API de muestra, puedes enviarle solicitudes.

Crear una clave de API y configurar una variable del entorno

El código de muestra requiere una clave de API. La solicitud es más simple si configuras una variable de entorno para la clave de API.

1. En el mismo proyecto Google Cloud que usaste para tu API, crea una clave de API en la página de credenciales de la API. Si quieres crear una clave de API en otro proyecto de Google Cloud , consulta Cómo habilitar una API en tu proyecto de Google Cloud .

   Ir a la página Credenciales

2. Haz clic en Crear credenciales y selecciona Clave de API.
3. Copia la clave al portapapeles.
4. Haz clic en Cerrar.
5. En tu computadora local, pega la clave de API para asignarla a una variable de entorno: $Env:ENDPOINTS_KEY="AIza..."

Envía la solicitud

1. En PowerShell, configura una variable de entorno para la URL del proyecto de App Engine. Reemplaza YOUR_PROJECT_ID por el ID del proyecto deGoogle Cloud .

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

2. Prueba una solicitud HTTP mediante las variables de entorno ENDPOINTS_HOST y ENDPOINTS_KEY que configuraste con anterioridad:

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

En el ejemplo anterior, las dos primeras líneas terminan en un acento grave. Cuando pegues el ejemplo en PowerShell, asegúrate de que no quede un espacio después de los acentos graves. Si deseas obtener más información sobre las opciones utilizadas en la solicitud de ejemplo, consulta Invoke-WebRequest en la documentación de Microsoft.

La API repite el mensaje que le enviaste y responde lo siguiente:

{
  "message": "hello world"
}

Si no obtuviste una respuesta correcta, consulta Soluciona errores de respuesta.

¡Acabas de implementar y probar una API en Endpoints!

Nota: Si quieres contarnos qué te gustó de este instructivo, envíanos tus comentarios al final de esta página. Tus comentarios nos ayudarán a mejorar estos instructivos.
Si recibiste un error, únete al grupo de Google google-cloud-endpoints y cuéntanos cuál fue el problema. En este grupo encontrarás respuestas de otros usuarios de Endpoints y de los ingenieros de Google, quienes supervisan el grupo.

Realiza un seguimiento de la actividad de la API

1. Revisa los grafos de actividad de tu API en la página de Endpoints.

   Ir a la página Servicios de Endpoints

   La solicitud puede tardar unos minutos en reflejarse en los gráficos.

2. Revisa los registros de solicitud de tu API en la página del visor de registros.

   Ir a la página Explorador de registros

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Realiza una limpieza

Consulta Borrar una API y las instancias relacionadas para obtener información acerca de cómo detener los servicios que se usan en este instructivo.

¿Qué sigue?

• Compartir API protegidas por claves de API
• Obtener más información sobre la autenticación
• Obtener más información sobre las opciones del servicio de asistencia de la comunidad