Aggiunta della gestione delle API

Endpoints Frameworks fornisce funzionalità di gestione delle API paragonabili a quelle fornite da Extensible Service Proxy (ESP) per Cloud Endpoints. Endpoints Frameworks include un gateway API integrato che intercetta tutte le richieste ed esegue i controlli necessari, ad esempio l' autenticazione, prima di inoltrare la richiesta al backend API. Quando il backend risponde, Endpoints Frameworks raccoglie e segnala la telemetria. Puoi visualizzare le metriche per la tua API nella pagina Endpoints > Servizi della Google Cloud console.

Le funzionalità di gestione delle API disponibili in Endpoints Frameworks includono:

• Monitoraggio
• Logging
• Quote
• Portale per sviluppatori

Affinché la tua API venga gestita da Endpoints, devi eseguire il deployment di un documento OpenAPI che la descriva utilizzando la versione 2.0 della specifica OpenAPI. Questa pagina descrive come generare ed eseguire il deployment di un documento OpenAPI che consenta a Endpoints di gestire la tua API.

Se non aggiungi la gestione delle API, la tua API continua a gestire le richieste, ma non viene visualizzata nella pagina Endpoints > Servizi della Google Cloud console e la funzionalità fornita da Endpoints, come la registrazione, il monitoraggio e l'impostazione delle quote, non è disponibile.

Per aggiungere la gestione delle API alla tua API:

1. Configura il file pom.xml di Maven o il file build.gradle di Gradle come descritto in Configurare i file di build.

2. Assicurati di impostare l'ID Google Cloud progetto nei file di build.

   Maven

   Cerca <endpoints.project.id> e sostituisci YOUR_PROJECT_ID con l' Google Cloud ID progetto. Ad esempio:

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

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

   Gradle

   1. Cerca def projectId e sostituisci YOUR_PROJECT_ID con l' Google Cloud ID progetto. Ad esempio:

      def projectId = 'example-project-12345'

   2. Assicurati che il file build.gradle contenga l'attività replaceProjectId che imposta l'ID progetto nei file 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. Nel file web.xml del progetto API, aggiungi la configurazione del filtro servlet di gestione delle 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 configurazione di compilazione del progetto API:

   Maven

   1. Aggiungi le dipendenze di gestione delle API:

      <dependency>
        <groupId>com.google.endpoints</groupId>
        <artifactId>endpoints-management-control-appengine-all</artifactId>
        <version>1.0.14</version>
      </dependency>

   2. Includi il plug-in che puoi utilizzare per generare le librerie client e il documento 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. Aggiungi le dipendenze di gestione delle API:

      compile 'com.google.endpoints:endpoints-management-control-appengine:1.0.14'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.14'

   2. Dichiara la dipendenza esterna in modo che il plug-in venga recuperato da Maven Central:

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0'

   3. Utilizza il plug-in Gradle di Endpoints Frameworks lato server, che genera il documento OpenAPI:

      apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

   4. Configura il nome del servizio Endpoints:

      endpointsServer {
        // Endpoints Framework Plugin server-side configuration
        hostname = "${projectId}.appspot.com"
      }

5. Dopo aver modificato le dipendenze, pulisci il progetto e poi crea l'API:

   Maven

       mvn clean
       mvn package

   Gradle

       gradle clean
       gradle build

6. Genera il documento OpenAPI, openapi.json:

   Maven

   mvn endpoints-framework:openApiDocs

   Gradle

   gradle endpointsOpenApiDocs

7. Esegui il deployment del documento OpenAPI:

    gcloud endpoints services deploy openapi.json
   

   La prima volta che esegui il deployment di openapi.json, viene creato un nuovo servizio Endpoints con il nome YOUR_PROJECT_ID.appspot.com. Al termine, viene visualizzata una riga simile alla seguente, in cui sono visualizzati l'ID configurazione del servizio e il nome del servizio:

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

   Nell'esempio precedente, 2017-02-13r0 è l'ID configurazione del servizio. L'ID configurazione del servizio è costituito da un timestamp seguito da un numero di revisione. Se esegui di nuovo il deployment di openapi.json, il numero di revisione viene incrementato nell'ID configurazione del servizio.

   Se devi visualizzare di nuovo l'ID configurazione del servizio, esegui il comando seguente, ma sostituisci YOUR_PROJECT_ID con l'ID progetto del tuo Google Cloud progetto:

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

   Puoi creare il tuo documento OpenAPI ed eseguirne il deployment anziché utilizzarne uno generato. Basta sostituire openapi.json sopra con il percorso del documento OpenAPI. Per ulteriori informazioni sulla scrittura di un documento OpenAPI, consulta la panoramica di OpenAPI.

8. Modifica il file appengine-web.xml per impostare il valore di una variabile di ambiente:

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

   Sostituisci ${endpoints.project.id} con l' Google Cloud ID progetto. Ad esempio:

   <env-var name="ENDPOINTS_SERVICE_NAME" value="example-project-12345.appspot.com" />
   

9. Esegui di nuovo il deployment dell'applicazione.

   Maven

   mvn appengine:deploy

   Gradle

   gradle appengineDeploy

10. Testa l'API inviando alcune richieste.

11. Per visualizzare le metriche API, apri la pagina Endpoints > Servizi nella Google Cloud console per il tuo progetto:
    

    Vai alla pagina Servizi Endpoints