Desplegar la configuración de Endpoints

Después de configurar Cloud Endpoints en un documento OpenAPI, debes implementarlo para que Endpoints tenga la información que necesita para gestionar tu API. Para desplegar la configuración de Endpoints, usa el comando gcloud endpoints services deploy. Este comando usa Service Infrastructure, la plataforma de servicios básica de Google que utilizan Endpoints y otros servicios para crear y gestionar APIs y servicios. En esta página se describe cómo desplegar un documento OpenAPI en Endpoints.

Requisitos previos

Para empezar, en esta página se presupone que tienes lo siguiente:

Preparar Google Cloud CLI para el despliegue

Para implementar la configuración, usa la herramienta de línea de comandos gcloud. Consulta la referencia de gcloud para obtener más información sobre los comandos.

Para preparar la implementación, haz lo siguiente:

  1. Instala e inicializa gcloud CLI.
  2. Actualiza gcloud CLI: 
    gcloud components update
  3. Asegúrate de que la CLI de gcloud tenga autorización para acceder a tus datos y servicios: 
    gcloud auth login

    Se abre una nueva pestaña del navegador y se te pide que elijas una cuenta.

  4. Define el proyecto predeterminado. Sustituye [YOUR-PROJECT-ID] por el ID de tu proyecto de GCP. 
    gcloud config set project [YOUR-PROJECT-ID]
  5. Si vas a implementar tu backend de API en Kubernetes o Kubernetes Engine, ejecuta el siguiente comando para obtener nuevas credenciales de usuario que puedas usar con las credenciales predeterminadas de la aplicación. Se necesitan las credenciales del usuario para autorizar kubectl. 
    gcloud auth application-default login
     Se abre una nueva pestaña del navegador y se te pide que elijas una cuenta.

Validar la sintaxis de openapi.json

El archivo de documento OpenAPI puede estar en formato YAML o JSON. Si está en formato JSON, le recomendamos que verifique la sintaxis antes de implementar el archivo. Para comprobar que tu openapi.json es un archivo JSON con un formato correcto, puedes abrirlo en un editor de texto que valide JSON, como vim, usar un servicio online de linter JSON o usar Python, por ejemplo:

python -m json.tool openapi.json

Para mejorar la legibilidad, puedes aplicar un formato de impresión bonito al archivo JSON:

python -m json.tool input.json > output.json

Sustituye input.json por la ruta a tu archivo openapi.json. output.json es el archivo JSON con formato.

Validar un documento OpenAPI

No todas las estructuras de OpenAPI son compatibles con Cloud Endpoints. Antes de implementar, puedes validar tu documento de OpenAPI.

Para validar tu documento de OpenAPI, sigue estos pasos:

  1. Cambia al directorio que contiene tu documento de OpenAPI.

  2. Confirma el Google Cloud proyecto en el que quieres crear el servicio. Si usas un nombre de dominio personalizado (por ejemplo, myapi.example.com), valida el ID de proyecto devuelto por el siguiente comando para que el servicio no se cree en el proyecto incorrecto.

    gcloud config list project

    Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y sustituye [YOUR_PROJECT_ID] por el Google Cloud ID del proyecto en el que quieras crear el servicio:

    gcloud config set project [YOUR_PROJECT_ID]

  3. Ejecuta el siguiente comando y sustituye [YOUR_OPENAPI_DOCUMENT] por el nombre del documento de OpenAPI que describe tu API:

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only

El comando gcloud llama a la API Service Management para crear un servicio gestionado con el nombre que has especificado en el campo host de tu documento OpenAPI. Si especificas la marca --validate-only, se creará un servicio, pero no se desplegará la configuración. No hay forma de validar tu documento de OpenAPI sin crear un servicio. Aunque puedes eliminar el servicio, la gestión de servicios te impide crear un servicio con el mismo nombre durante un periodo de aproximadamente 30 días.

Desplegar el documento OpenAPI

Cuando tengas todo listo para desplegar tu API, ejecuta la CLI de Google Cloud, que usa Service Management para subir la configuración de tu API y crear (o actualizar) un servicio gestionado.

Para implementar tu documento de OpenAPI, sigue estos pasos:

  1. Cambia al directorio que contiene tu documento de OpenAPI.

  2. Valida el ID del proyecto devuelto por el siguiente comando para asegurarte de que el servicio no se ha creado en el proyecto incorrecto.

    gcloud config list project

    Si necesitas cambiar el proyecto predeterminado, ejecuta el siguiente comando y sustituye [YOUR_PROJECT_ID] por el Google Cloud ID del proyecto Google Cloud en el que quieras crear el servicio:

    gcloud config set project [YOUR_PROJECT_ID]

  3. Ejecuta el siguiente comando y sustituye [YOUR_OPENAPI_DOCUMENT] por el nombre del documento de OpenAPI que describe tu API:

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]

La primera vez que ejecutes el comando anterior, Service Management creará un servicio de Endpoints en el proyecto predeterminado con un nombre que coincida con el texto que hayas especificado en el campo host de tu documento OpenAPI y subirá la configuración del servicio.

Mientras crea y configura el servicio, Gestión de servicios muestra información en la terminal. Si se completa correctamente, verás una línea como la siguiente que muestra el ID de configuración del servicio y el nombre del servicio:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

En el ejemplo anterior, 2017-02-13r0 es el ID de configuración del servicio y echo-api.endpoints.example-project-12345.cloud.goog es el nombre del servicio.

Una vez que se haya completado la implementación, puedes ver la API en la página Endpoints > Services de la consola de Google Cloud .

Si aparece un mensaje de error, consulta Solucionar problemas de configuración e implementación de endpoints.

Volviendo a desplegar

Cada vez que cambies algo en tu documento de OpenAPI, asegúrate de volver a implementarlo para que Endpoints tenga la versión más reciente de la configuración de servicio de tu API. No es necesario que vuelvas a implementar ni reiniciar ESP si ya lo has hecho con la opción rollout definida como managed. Esta opción configura ESP para que use la última configuración de servicio implementada. Si especifica esta opción, el ESP detectará el cambio y empezará a usarlo automáticamente en un plazo de 5 minutos después de que implemente una nueva configuración de servicio. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo use ESP.

Después de la implementación de la configuración inicial de Endpoints, puedes conceder a un usuario, una cuenta de servicio o un grupo un rol que les permita volver a implementar la configuración de Endpoints. Consulta Conceder y revocar el acceso a la API para obtener más información.

Siguientes pasos