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:

Affinché la tua API venga gestita da Endpoints, devi eseguire il deployment di un documento OpenAPI che descriva la tua API 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 > Services dellaGoogle Cloud console e la funzionalità fornita da Endpoints, come logging, monitoraggio e impostazione delle quote, non è disponibile.

Installazione e configurazione del software richiesto

Se non l'hai ancora fatto, installa e configura Google Cloud CLI per Python e aggiungi la libreria Python di Endpoints Frameworks alla directory del progetto API in modo che venga caricata con il codice API al momento del deployment.

Installare e configurare gcloud CLI per Python

  1. Installa e inizializza gcloud CLI:

    Scarica e installa gcloud CLI

  2. Installa il componente gcloud che include l'estensione App Engine per Python:

    gcloud components install app-engine-python

  3. Aggiorna gcloud CLI:

    gcloud components update

  4. Assicurati che gcloud CLI sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:

    gcloud auth login

    Si apre una nuova scheda del browser e ti viene chiesto di scegliere un account.

  5. Imposta il progetto predefinito sull'ID progetto. Sostituisci YOUR_PROJECT_ID con l' Google Cloud ID progetto.

    gcloud config set project YOUR_PROJECT_ID

  6. Per Linux, imposta la variabile di ambiente ENDPOINTS_GAE_SDK sul percorso della cartella SDK di App Engine:

    PATH_TO_CLOUD_SDK/platform/google_appengine

    Sostituisci PATH_TO_CLOUD_SDK con l'output del seguente comando:

    gcloud info --format="value(installation.sdk_root)"

Aggiungere la libreria Python di Endpoints Frameworks

  1. Assicurati di poter compilare le estensioni C per Python.

    • Windows: è richiesto Microsoft Visual C++ 9.0 o versioni successive. Puoi scaricare Microsoft Visual C++ Compiler per Python 2.7 dal Centro download Microsoft

    • Altri sistemi operativi: a seconda del sistema operativo, potrebbe essere necessario installare gli strumenti del compilatore (a volte in un pacchetto denominato build-essential) e/o le intestazioni di sviluppo Python (a volte in un pacchetto denominato python-dev).

  2. Passa alla directory principale dell'API.

  3. Crea una sottodirectory /lib nella directory principale dell'API:

    mkdir lib

  4. Installa la libreria:

    pip install -t lib google-endpoints --ignore-installed

Generare il documento OpenAPI

Dalla directory principale dell'API, genera un documento OpenAPI utilizzando gli strumenti del framework. Ad esempio:

Singola classe

Nel comando seguente, sostituisci YOUR_PROJECT_ID con l'ID Google Cloud progetto.

python lib/endpoints/endpointscfg.py get_openapi_spec main.EchoApi \
    --hostname YOUR_PROJECT_ID.appspot.com

Ignora gli avvisi visualizzati.

Più classi

Puoi elencare più classi nella riga di comando. Endpoints genera un documento OpenAPI per ogni combinazione di nome e versione dell'API.

Se vuoi eseguire il deployment di più classi API con nomi API diversi come parte di un singolo servizio, devi anche aggiungere il flag --x-google-api-name. L'attivazione di questo flag aggiunge ulteriori limitazioni ai nomi delle API. In particolare, i nomi devono corrispondere all'espressione regolare [a-z][a-z0-9]{0,39}; ovvero, il nome deve essere composto da 1-40 caratteri, che possono essere tutti caratteri alfabetici minuscoli o numeri, tranne il primo carattere, che non deve essere un numero. Ad esempio:

Nel comando seguente, sostituisci YOUR_PROJECT_ID con l'ID Google Cloud progetto.

python lib/endpoints/endpointscfg.py get_openapi_spec main.FooApi main.BarApi \
   --hostname YOUR_PROJECT_ID.appspot.com \
   --x-google-api-name

Ignora gli avvisi visualizzati.

Endpoints utilizza il testo specificato nell'argomento hostname come nome del servizio. Quando esegui il deployment dell'API in App Engine, viene creata automaticamente una voce DNS con un nome nel formato YOUR_PROJECT_ID.appspot.com.

Eseguire il deployment del documento OpenAPI

Singola classe

gcloud endpoints services deploy echov1openapi.json

Più classi

Se hai più documenti OpenAPI, elencali tutti nella riga di comando. Ad esempio:

 gcloud endpoints services deploy foov1openapi.json barv1openapi.json

La prima volta che esegui il deployment del documento (o dei documenti) OpenAPI, 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 del documento OpenAPI, il numero di revisione viene incrementato nell'ID configurazione del servizio.

Se devi visualizzare di nuovo l'ID configurazione del servizio, esegui il seguente comando, 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 e eseguire il deployment del tuo documento OpenAPI anziché utilizzarne uno generato. Basta sostituire echov1openapi.json sopra con il percorso del documento OpenAPI. Per ulteriori informazioni sulla scrittura di un documento OpenAPI, consulta la panoramica di OpenAPI.

Eseguire di nuovo il deployment dell'API e testarla

  1. Modifica il file app.yaml del progetto e aggiungi una sezione env_variables come segue:

    env_variables:
  ENDPOINTS_SERVICE_NAME: YOUR_PROJECT_ID.appspot.com
  ENDPOINTS_SERVICE_VERSION: YOUR_SERVICE_VERSION

    Sostituisci YOUR_PROJECT_ID con il tuo Google Cloud ID progetto e YOUR_SERVICE_VERSION con l'ID configurazione del servizio della sezione precedente. Con questa aggiunta al file app.yaml, Endpoints gestisce la tua API dopo che hai rieseguito il deployment dell'applicazione.

  2. Esegui di nuovo il deployment dell'applicazione:

    gcloud app deploy

  3. Attendi qualche istante per il completamento del deployment, ignorando i messaggi di avviso. Al termine del deployment, viene visualizzato un messaggio simile al seguente:

    File upload done.
Updating service [default]...done.

  4. Verifica che il deployment sia stato eseguito correttamente, ad esempio utilizzando curl:

    curl --request POST \
    --header "Content-Type: application/json" \
    --data '{"content":"echo"}' \
    https://YOUR_PROJECT_ID.appspot.com/_ah/api/echo/v1/echo?n=2

    Sostituisci echo con il nome della tua API.

    I risultati dovrebbero mostrare qualcosa di simile a:

    {
 "content": "echo echo"
}

  5. Esegui altre richieste alla tua API.

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

    Vai alla pagina Servizi Endpoints