Configurar Cloud Endpoints

Cloud Endpoints admite APIs descritas con la versión 2.0 de la especificación OpenAPI. Describe la superficie de la API y configura las funciones de Endpoints, como las reglas de autenticación o las cuotas, en un documento de OpenAPI.

Endpoints hace un uso especial de los siguientes campos obligatorios en tu documento OpenAPI:

  • host
  • info.title
  • info.version
  • operationId

En esta página se explica cómo usa Endpoints los campos anteriores. Con esta información, puedes terminar de preparar tu documento de OpenAPI para implementarlo.

Requisitos previos

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

host

Cloud Endpoints usa el nombre que configures en el campo host de tu documento de OpenAPI como nombre de tu servicio.

El nombre de tu servicio de API debe ser único en Google Cloud. Como Endpoints usa nombres compatibles con DNS para identificar servicios, te recomendamos que uses el nombre de dominio o el nombre de subdominio de tu API como nombre de servicio. Con este método, el nombre del servicio que aparece en la página Servicios de puntos finales coincide con el nombre usado en las solicitudes a tu API. Endpoints tiene los siguientes requisitos para el nombre del servicio:

  • La longitud máxima del nombre de dominio es de 253 caracteres.
  • El nombre de dominio debe empezar por una letra minúscula.
  • Cada sección del nombre de dominio, delimitada por puntos, debe cumplir los siguientes requisitos:
    • Debe empezar por una letra minúscula.
    • No puede terminar en un guion.
    • El resto de los caracteres pueden ser letras minúsculas, números o guiones.
    • La longitud máxima es de 63 caracteres.

Puedes registrar tu propio dominio personalizado (como example.com) o usar un dominio gestionado por Google.

Usar un dominio gestionado por Google

Google es el propietario y el administrador de los dominios cloud.goog y appspot.com. Si quieres usar un dominio gestionado por Google, debes usar tuGoogle Cloud ID de proyecto como parte del nombre del servicio. Como los proyectos tienen un ID de proyecto único a nivel global, este requisito asegura que tengas un nombre de servicio único.Google Cloud

El nombre de dominio que uses dependerá del backend que aloje tu API:

  • En el caso de las APIs alojadas en el entorno flexible de App Engine, debes usar el dominio appspot.com y el nombre del servicio debe tener el siguiente formato, donde YOUR_PROJECT_ID es tu ID de proyecto Google Cloud :

    YOUR_PROJECT_ID.appspot.com

    Cuando implementas tu API en App Engine, se crea automáticamente una entrada DNS con un nombre en el formato YOUR_PROJECT_ID.appspot.com.

  • En el caso de las APIs alojadas en Compute Engine, Google Kubernetes Engine o Kubernetes, debe usar el dominio cloud.goog y el nombre del servicio debe tener el siguiente formato, donde YOUR_API_NAME es el nombre de su API:

    YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog

    Para usar este dominio como nombre de dominio de la API, consulta el artículo Configurar el DNS en el dominio cloud.goog.

Usar un dominio personalizado

Si no quieres usar un dominio gestionado por Google, puedes usar un dominio personalizado (por ejemplo, myapi.mycompany.com) para el que tengas autorización. Antes de implementar la configuración de la API, sigue los pasos que se indican en Verificar la propiedad del dominio.

info.title

El campo info.title es un nombre fácil de usar para tu API. En la página Endpoints > Services (Puntos finales > Servicios) de la consola Google Cloud se muestra el texto que configures en el campo info.title. Si tienes más de una API por proyecto, el nombre de la API se mostrará en una lista la primera vez que abras la página. Google Cloud Puede hacer clic en el nombre de la API para abrir otra página que muestre las métricas, el historial de implementaciones y otra información de la API.

info.version

En la página Endpoints > Services (Endpoints > Servicios) de la Google Cloud consola, se muestra el número de versión de tu API. Antes de desplegar la configuración de tu API por primera vez, haz lo siguiente:

  • En el campo info.version,indica el número de versión de la API que corresponda (por ejemplo, 1.0).

  • Asigna al campo basePath el número de versión principal, por ejemplo, /v1.

Para obtener más información sobre el control de versiones de tu API, consulta Gestión del ciclo de vida de las APIs.

operationId

Aunque operationId es un campo opcional en la especificación OpenAPI, Endpoints requiere este campo porque se usa para identificar la operación internamente. La cadena que uses para operationId debe ser única en tu API. Consulta la descripción de operationId en la especificación de OpenAPI para obtener directrices sobre cómo asignar nombres.

Siguientes pasos