Como adicionar gerenciamento de APIs

O Cloud Endpoints Frameworks oferece recursos de gerenciamento de APIs que são comparáveis com os recursos que o Extensible Service Proxy (ESP) fornece para o Cloud Endpoints. Os frameworks do Endpoints incluem um gateway de API (em inglês) integrado que intercepta todas as solicitações e realiza as verificações necessárias, como autenticação, antes de encaminhar a solicitação ao back-end da API. Quando o back-end responde, o Endpoints Frameworks coleta e relata a telemetria. É possível visualizar métricas da API na página Endpoints > Serviços no Console do Google Cloud.

Os recursos de gerenciamento de APIs disponíveis no Endpoints Frameworks incluem os itens a seguir:

Para que sua API seja gerenciada pelo Cloud Endpoints, implante um documento do OpenAPI que descreva sua API usando a versão 2.0 da Especificação OpenAPI. Nesta página, você aprenderá como gerar e implantar um documento OpenAPI que ative o Endpoints para gerenciar sua API.

Se você não adicionar o gerenciamento da API, sua API continuará veiculando solicitações, mas não será exibida na página Endpoints> Serviços no Console do Cloud. Além disso, as funcionalidades oferecidas pelo Endpoints, como geração de registros, monitoramento e definição de cotas, não ficarão disponíveis.

Para adicionar gerenciamento à sua API:

  1. Configure seu arquivo Maven pom.xml ou seu arquivo Gradle build.gradle como descrito em Como configurar os arquivos de versão.

  2. Certifique-se de definir o código do projeto do Google Cloud nos arquivos de versão.

    Maven

    Pesquise <endpoints.project.id> e substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Exemplo:

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

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

    Gradle

    1. Pesquise def projectId e substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud. Exemplo:

      def projectId = 'example-project-12345'

    2. Verifique se o arquivo build.gradle contém a tarefa replaceProjectId, que define o código do projeto nos arquivos appengine-web.xml e 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. No arquivo web.xml do projeto da API, adicione a configuração de filtro do servlet de gerenciamento 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. Modifique a configuração da compilação do projeto da API:

    Maven

    1. Adicione as dependências de gerenciamento da API:

      <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-management-control-appengine-all</artifactId>
        <version>1.0.13</version>
      </dependency>
    2. Inclua o plug-in que você pode usar para gerar bibliotecas de clientes e o documento da 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. Adicione as dependências de gerenciamento da API:

      compile 'com.google.endpoints:endpoints-management-control-appengine:1.0.12'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.12'
    2. Declare a dependência externa para que o plug-in seja recuperado do Maven Central:

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.0.1'
    3. Use o plug-in Gradle do Endpoints Framework no lado do servidor, que gera o documento do OpenAPI:

      apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
    4. Configure o nome do serviço do Endpoints:

      endpointsServer {
        // Endpoints Framework Plugin server-side configuration
        hostname = "${projectId}.appspot.com"
      }
  5. Depois de modificar as dependências, limpe o projeto e crie a API:

    Maven

        mvn clean
        mvn package

    Gradle

        gradle clean
        gradle build
  6. Gere o documento da OpenAPI, openapi.json:

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs
  7. Implante o documento do OpenAPI:

     gcloud endpoints services deploy openapi.json
    

    A primeira vez que você implanta openapi.json, um novo serviço do Endpoints é criado com o nome YOUR_PROJECT_ID.appspot.com. Com a conclusão bem-sucedida, uma linha semelhante à seguinte exibe o código de configuração e o nome do serviço:

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

    No exemplo anterior, 2017-02-13r0 é o ID de configuração do serviço. Esse ID de configuração do serviço consiste em um registro de data e número de revisão. Se você implementar openapi.json novamente, o número de revisão será incrementado no ID de configuração do serviço.

    Caso precise exibir o ID de configuração do serviço novamente, execute o comando a seguir, mas substitua YOUR_PROJECT_ID pelo ID do projeto do Google Cloud:

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

    É possível criar seu próprio documento OpenAPI e implantá-lo em vez de usar um gerado. Simplesmente substitua openapi.json, visto acima, pelo caminho para seu documento da OpenAPI. Para mais informações sobre como escrever um documento do OpenAPI, consulte Visão geral do OpenAPI.

  8. Edite seu arquivo appengine-web.xml para definir o valor de uma variável de ambiente:

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

    Substitua ${endpoints.project.id} pelo ID do projeto do Google Cloud. Exemplo:

    <env-var name="ENDPOINTS_SERVICE_NAME" value="example-project-12345.appspot.com" />
    
  9. Implante o aplicativo novamente.

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

  10. Faça algumas solicitações à API para testá-la.

  11. Para visualizar suas métricas de API, abra a página Endpoints > Serviços no Console do Cloud do projeto:

    Ir para a página Serviços do Endpoints