Agrega la administración de la API

Cloud Endpoints Frameworks proporciona características de administración de API que se asimilan a las características que proporciona el proxy de servicio extensible (ESP) a Cloud Endpoints. Endpoints Frameworks incluye una puerta de enlace de API integrada que intercepta todas las solicitudes y realiza las verificaciones necesarias (por ejemplo, la autenticación) antes de reenviar la solicitud al backend de la API. Tras la respuesta desde el backend, se informa y recopila la telemetría en Endpoints Frameworks. Puedes ver las métricas de tus API en la página Endpoints > Servicios en Google Cloud Console.

Las características de administración de API disponibles en Endpoints Frameworks incluyen lo siguiente:

Para que Endpoints administre tu API, debes implementar un documento de OpenAPI en el que se describa que tu API usa la versión 2.0 de OpenAPI Specification. En esta página, se describe cómo generar y, luego, implementar un documento de OpenAPI con el que se habilita Endpoints para administrar tu API.

Si no agregas la administración de API, tu API continúa entregando solicitudes, pero no aparece en la página Endpoints  > Servicios de Cloud Console y la funcionalidad que ofrece Endpoints, como el registro, la supervisión y la configuración de cuotas, no está disponible.

Para agregar la administración de API a tu API, sigue estos pasos:

  1. Configura tu archivo de Maven pom.xml o tu archivo de Gradle build.gradle como se describe en Configura los archivos de compilación.

  2. Asegúrate de configurar el ID del proyecto de Google Cloud en los archivos de compilación.

    Maven

    Busca <endpoints.project.id> y reemplaza YOUR_PROJECT_ID por el ID del proyecto de Google Cloud. Por ejemplo:

    <endpoints.project.id>example-project-12345</endpoints.project.id>

    <endpoints.project.id>YOUR_PROJECT_ID</endpoints.project.id>

    Gradle

    1. Busca def projectId y reemplaza YOUR_PROJECT_ID por el ID del proyecto de Google Cloud. Por ejemplo:

      def projectId = 'example-project-12345'

    2. Asegúrate de que tu archivo build.gradle contenga la tarea replaceProjectId, que establece el ID del proyecto en los archivos appengine-web.xml y web.xml.

      task replaceProjectId(type: Copy) {
          from 'src/main/webapp/WEB-INF/'
          include '*.xml'
          into "build/exploded-${archivesBaseName}/WEB-INF"
          expand(endpoints:[project:[id:projectId]])
          filteringCharset = 'UTF-8'
      }

  3. En el archivo web.xml de tu proyecto de API, agrega la configuración del filtro de servlet de administración de API:

    <!-- Add a filter that fetches the service config from service management. -->
    <filter>
        <filter-name>endpoints-api-configuration</filter-name>
        <filter-class>com.google.api.control.ServiceManagementConfigFilter</filter-class>
    </filter>
    
    <!-- Add a filter that performs Endpoints logging and monitoring. -->
    <filter>
        <filter-name>endpoints-api-controller</filter-name>
        <filter-class>com.google.api.control.extensions.appengine.GoogleAppEngineControlFilter</filter-class>
        <init-param>
            <param-name>endpoints.projectId</param-name>
            <param-value>${endpoints.project.id}</param-value>
        </init-param>
        <init-param>
            <param-name>endpoints.serviceName</param-name>
            <param-value>${endpoints.project.id}.appspot.com</param-value>
        </init-param>
    </filter>
    
    <filter-mapping>
        <filter-name>endpoints-api-configuration</filter-name>
        <servlet-name>EndpointsServlet</servlet-name>
    </filter-mapping>
    
    <filter-mapping>
        <filter-name>endpoints-api-controller</filter-name>
        <servlet-name>EndpointsServlet</servlet-name>
    </filter-mapping>
  4. Modifica la configuración de compilación de tu proyecto de API:

    Maven

    1. Agrega las dependencias de administración de API:

      <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-management-control-appengine-all</artifactId>
        <version>1.0.14</version>
      </dependency>
    2. Incluye el complemento que puedes usar para generar bibliotecas cliente y el documento de OpenAPI, openapi.json:

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>endpoints-framework-maven-plugin</artifactId>
        <version>2.0.1</version>
        <configuration>
          <!-- plugin configuration -->
          <hostname>${endpoints.project.id}.appspot.com</hostname>
        </configuration>
      </plugin>

    Gradle

    1. Agrega las dependencias de administración de API:

      compile 'com.google.endpoints:endpoints-management-control-appengine:1.0.12'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.12'
    2. Declara la dependencia externa para que el complemento se recupere de Maven Central:

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.0.1'
    3. Usa el complemento de Gradle para Endpoints Frameworks del servidor, que genera el documento de OpenAPI:

      apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
    4. Configura el nombre de tu servicio de Endpoints:

      endpointsServer {
        // Endpoints Framework Plugin server-side configuration
        hostname = "${projectId}.appspot.com"
      }
  5. Después de modificar las dependencias, limpia tu proyecto y, luego, compila tu API:

    Maven

        mvn clean
        mvn package

    Gradle

        gradle clean
        gradle build
  6. Genera el documento de OpenAPI, openapi.json:

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs
  7. Implementa el documento de OpenAPI:

     gcloud endpoints services deploy openapi.json
    

    La primera vez que implementes openapi.json, se creará un nuevo servicio de Endpoints con el nombre YOUR_PROJECT_ID.appspot.com. Una vez completado de forma correcta, una línea similar a la siguiente muestra el ID de configuración del servicio y el nombre del servicio:

    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. El ID de configuración de servicio consiste en una marca de fecha seguida de un número de revisión. Si vuelves a implementar openapi.json, el número de revisión se incrementa en el ID de configuración del servicio.

    Si necesitas volver a mostrar el ID de configuración del servicio, ejecuta el siguiente comando, pero reemplaza YOUR_PROJECT_ID por el ID de tu proyecto de Google Cloud de la siguiente manera:

    gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com
    

    Puedes crear tu propio documento de OpenAPI y, luego, implementarlo, en lugar de usar uno generado. Solo debes reemplazar openapi.json ya mencionado con la ruta a tu documento de OpenAPI. Para obtener más información sobre cómo escribir un documento de OpenAPI, consulta Descripción general de OpenAPI.

  8. Edita el archivo appengine-web.xml para establecer el valor de una variable de entorno:

    <env-variables>
        <env-var name="ENDPOINTS_SERVICE_NAME" value="${endpoints.project.id}.appspot.com" />
    </env-variables>

    Reemplaza ${endpoints.project.id} por tu ID del proyecto de Google Cloud. Por ejemplo:

    <env-var name="ENDPOINTS_SERVICE_NAME" value="example-project-12345.appspot.com" />
    
  9. Implementa tu aplicación de nuevo.

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

  10. Prueba tu API mediante algunas solicitudes.

  11. Si deseas ver las métricas de tus API, abre la página Endpoints > Servicios en Cloud Console para tu proyecto de la siguiente manera:

    Ir a la página de servicios de Endpoints