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 Google Cloud console.

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

• Monitoramento
• Geração de registros
• Cotas
• Portal do desenvolvedor

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, ela ainda exibirá solicitações, mas não aparecerá na página Endpoints > Services doGoogle Cloud console. Além disso, a funcionalidade fornecida pelo Endpoints, como geração de registros, monitoramento e definição de cotas, não estará disponível.

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 Google Cloud ID do projeto nos arquivos de versão.

   Maven

   Pesquise <endpoints.project.id> e substitua YOUR_PROJECT_ID pelo Google Cloud ID do projeto. 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 Google Cloud ID do projeto. Exemplo:

      def projectId = 'example-project-12345'

   2. Verifique se o arquivo build.gradle contém a tarefa replaceProjectId, que define o ID 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 do build 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.14</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.1.0</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.14'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.14'

   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.1.0'

   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 ID de configurações de serviç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 das configurações de serviço. Esse ID de configurações de serviço consiste em um registro de data e hora seguido por um número de revisão. Ao implantar o openapi.json novamente, o número de revisão será incrementado no ID de configurações de serviço.

   Se for preciso exibir o código de configuração do serviço novamente, execute o comando a seguir, substituindo YOUR_PROJECT_ID pelo ID do projeto do seu Google Cloud projeto:

   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 Google Cloud ID do projeto. 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 Google Cloud console do projeto:
    

    Ir para a página Serviços do Endpoints