Implementar la configuración de Endpoints

Después de configurar Cloud Endpoints en un documento de OpenAPI, impleméntalo de modo que Endpoints tenga la información que necesita para administrar la API. La configuración de Endpoints se implementa mediante el comando gcloud endpoints services deploy. Este comando utiliza Service Infrastructure, la plataforma básica de servicios de Google, que usan Endpoints y otros servicios para crear y administrar las API y los servicios. En esta página, se describe cómo implementar un documento de OpenAPI en Endpoints.

Requisitos previos

Como punto de partida, en esta página, se supone que ya realizaste los siguientes pasos:

Cómo preparar el SDK de Cloud para la implementación

Puedes usar la herramienta de línea de comandos de gcloud para implementar la configuración. Consulta la referencia de gcloud para obtener más información acerca de los comandos.

Prepárate para la implementación de la siguiente manera:

  1. Instala y, luego, inicializa el SDK de Cloud.
  2. Actualiza el SDK de Cloud:
    gcloud components update
    
  3. Asegúrate de que el SDK de Cloud esté autorizado para acceder a tus datos y servicios:
    gcloud auth login
    

    Se abrirá una nueva pestaña del navegador y se te solicitará que elijas una cuenta.

  4. Configura el proyecto predeterminado. Reemplaza [YOUR-PROJECT-ID] por el ID de tu proyecto de GCP.
    gcloud config set project [YOUR-PROJECT-ID]
    
  5. Si implementarás el backend de tu API en Kubernetes o Kubernetes Engine, ejecuta el comando siguiente para adquirir credenciales de usuario nuevas y usarlas como las credenciales predeterminadas de la aplicación. Se necesitan las credenciales de usuario para autorizar a kubectl.
    gcloud auth application-default login
    Se abrirá una nueva pestaña del navegador y se te solicitará que elijas una cuenta.

Cómo validar la sintaxis de openapi.json

El archivo del documento de OpenAPI puede estar en formato YAML o JSON. Si está en formato JSON, te recomendamos verificar la sintaxis antes de implementar el archivo. Para comprobar que openapi.json sea un archivo JSON con formato correcto, puedes abrirlo en un editor de texto que valide JSON, como vim, usar un servicio de linter de JSON en línea o usar Python, por ejemplo:

python -m json.tool openapi.json

Para mejorar la legibilidad del archivo JSON, puedes imprimirlo:

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

Reemplaza input.json con la ruta de acceso a tu archivo openapi.json. output.json es la versión impresa del archivo JSON.

Cómo validar tu documento de OpenAPI

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

Para validar tu documento de OpenAPI, sigue estos pasos:

  1. Cambia el directorio a la ubicación que contiene el documento de OpenAPI.

  2. Confirma el proyecto de GCP donde quieres crear el servicio. Si usas un nombre de dominio personalizado (por ejemplo, myapi.example.com), asegúrate de validar el ID del proyecto que muestra el comando siguiente, de modo que el servicio no se cree en el proyecto incorrecto.

    gcloud config list project
    

    Si necesitas cambiar el proyecto predeterminado, ejecuta el comando siguiente y reemplaza [YOUR_PROJECT_ID] por el ID del proyecto de GCP en que quieras crear el servicio.

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. Ejecuta el siguiente comando y reemplaza [YOUR_OPENAPI_DOCUMENT] por el nombre del documento de OpenAPI que describe tu API:

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

La primera vez que ejecutas gcloud endpoints services deploy, Service Management crea un servicio con el nombre que especificaste en el campo host en tu documento de OpenAPI. Cuando especificas la marca --validate-only, se crea un servicio de todos modos, pero la configuración no se implementa. No hay forma de validar tu documento de OpenAPI sin crear un servicio. Si bien puedes borrar el servicio, Service Management te impide crear un servicio con el mismo nombre por un período de unos 30 días.

Cómo implementar el documento de OpenAPI

Cuando implementas la API, la herramienta de línea de comandos de gcloud sube tu configuración de API mediante Service Management para crear un servicio administrado. Después de una implementación exitosa, puedes ver la API en la página Endpoints > Servicios en GCP Console.

Para implementar tu documento de OpenAPI, sigue estos pasos:

  1. Cambia el directorio a la ubicación que contiene el documento de OpenAPI.

  2. Valida el ID del proyecto que muestra el comando siguiente para asegurarte de que el servicio no se cree en el proyecto equivocado.

    gcloud config list project
    

    Si necesitas cambiar el proyecto predeterminado, ejecuta el comando siguiente y reemplaza [YOUR_PROJECT_ID] por el ID del proyecto de GCP en que quieras crear el servicio:

    gcloud config set project [YOUR_PROJECT_ID]
    
  3. Ejecuta el siguiente comando y reemplaza [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 ejecutas el comando anterior, Service Management crea un servicio de Endpoints nuevo en el proyecto predeterminado con un nombre que coincide con el texto que especificaste en el campo host de tu documento de OpenAPI y sube la configuración del servicio.

Mientras se crea y configura el servicio, Service Management exporta la información a la terminal. Cuando el proceso finalice con éxito, verás una línea como la siguiente, que indica el ID de configuración de servicio y el nombre del servicio:

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

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

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

Volver a implementar

Cuando quieras cambiar 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 la API. Si el cambio de configuración no requiere que vuelvas a implementar la API (por ejemplo, si cambias o agregas algo en la sección de seguridad), no necesitas volver a implementar o reiniciar el proxy de servicio extensible (ESP) si ya has implementado el ESP con la opción rollout configurada como managed anteriormente. Esta opción configura el ESP de modo que use la última configuración del servicio implementada. Cuando especificas esta opción, un minuto después de implementar una configuración de servicio nueva, el ESP detecta el cambio y comienza a aplicarlo automáticamente. Te recomendamos que especifiques esta opción en lugar de un ID de configuración específico para que lo utilice el ESP.

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

¿Qué sigue?

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Cloud Endpoints con OpenAPI
Si necesitas ayuda, visita nuestra página de asistencia.