Aggiunta della gestione delle API

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

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

Affinché l'API venga gestita da Endpoints, devi eseguire il deployment di un documento OpenAPI che descriva l'API utilizzando la versione 2.0 della specifica OpenAPI. In questa pagina viene descritto come generare ed eseguire il deployment di un documento OpenAPI che consente a Endpoints di gestire l'API.

Se non aggiungi la gestione delle API, la tua API fornisce comunque le richieste, ma l'API non viene visualizzata nella pagina Endpoint > Servizi della console Google Cloud e la funzionalità fornita dagli endpoint, come il logging, il monitoraggio e l'impostazione delle quote, non è disponibile.

Per aggiungere la gestione delle API all'API:

Imposta il file Maven pom.xml o il file Gradle build.gradle come descritto in Configurare i file di build.
Assicurati di impostare l'ID progetto Google Cloud nei file di build.
Maven

Cerca <endpoints.project.id> e sostituisci YOUR_PROJECT_ID con il tuo ID progetto Google Cloud. 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 il tuo ID progetto Google Cloud. 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' }

Nel file web.xml del tuo progetto API, aggiungi la configurazione del filtro servlet per la 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>

Modifica la configurazione di compilazione del progetto API:

Maven

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>

Includi il plug-in che puoi utilizzare per generare 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

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'

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'
```
Utilizza il plug-in Gradle Endpoints Frameworks lato server, che genera il documento OpenAPI:
```
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
```

Configura il nome del servizio Endpoints:

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

Dopo aver modificato le dipendenze, pulisci il progetto e crea l'API:
Maven
```
    mvn clean
    mvn package
```
Gradle
```
    gradle clean
    gradle build
```

Genera il documento OpenAPI, openapi.json:

Maven

mvn endpoints-framework:openApiDocs

Gradle

gradle endpointsOpenApiDocs

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 completamento, una riga simile alla seguente mostra 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 con la data 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 questo comando, ma sostituisci YOUR_PROJECT_ID con l'ID del tuo progetto Google Cloud:
```
gcloud endpoints configs list --service=YOUR_PROJECT_ID.appspot.com
```
Puoi creare il tuo documento OpenAPI ed eseguirne il deployment, anziché utilizzarne uno generato. Devi solo sostituire openapi.json qui sopra con il percorso del documento OpenAPI. Per ulteriori informazioni sulla scrittura di un documento OpenAPI, consulta la panoramica di OpenAPI.

Modifica il file appengine-web.xml per impostare il valore per 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'ID del tuo progetto Google Cloud. Ad esempio:

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

Esegui di nuovo il deployment dell'applicazione.
Maven
```
mvn appengine:deploy
```
Gradle
```
gradle appengineDeploy
```
Testa l'API inviandole alcune richieste.
Per visualizzare le metriche delle API, apri la pagina Endpoint > Servizi nella console Google Cloud per il tuo progetto:

Vai alla pagina Endpoints Services