Chiama le API da un progetto Google Cloud

1. Prima di iniziare

Questo codelab mostra come creare un progetto Google Cloud e poi chiamare le API Google Cloud da quel progetto.

Prerequisiti

• Capacità di navigare nella console Google Cloud.

Obiettivi didattici

• Come creare un progetto Google Cloud.
• Come configurare un account di fatturazione.
• Come configurare Cloud Shell.
• Come abilitare un'API.
• Come autorizzare un'API con una chiave API.
• Come autorizzare un'API con un service account.

Che cosa ti serve

• Un Account Google, ad esempio un account Gmail o un account Google Workspace.
• Accesso a un account di fatturazione Cloud o a una carta di credito da utilizzare per registrarsi al programma di prova senza costi.

2. Configurazione

Questa sezione mostra come creare un progetto Google Cloud, configurare un account di fatturazione e configurare Cloud Shell.

Crea un progetto Google Cloud e configura un account di fatturazione

Nota:se non hai già un account Gmail o un account Google Workspace, devi prima crearne uno.

1. Accedi alla console Cloud e seleziona o crea un progetto.

Avviso: se riutilizzi un progetto e completi questo codelab, potresti consentire ad alcuni utenti di accedere alle risorse del progetto se non vengono disattivate al termine.

Ricorda l'ID progetto, mostrato sotto il campo Nome progetto. L'ID è un nome univoco in tutti i progetti Google Cloud (il nome sopra è già stato utilizzato) e viene indicato più avanti in questo codelab come PROJECT_ID.

Nota:se utilizzi un account Gmail, puoi lasciare la posizione predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, abilita la fatturazione in Cloud Console per utilizzare le risorse Google Cloud.

Sebbene questo codelab non dovrebbe costare molto, se non nulla, segui le istruzioni nella sezione Pulizia per arrestare le risorse ed evitare costi al di fuori di questo codelab. Tieni presente che i nuovi utenti di Google Cloud possono beneficiare della prova senza costi di 300$.

Configura Cloud Shell

In questo codelab, utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Cloud Shell è una macchina virtuale basata su Debian in cui sono caricati tutti gli strumenti per sviluppatori di cui hai bisogno. Offre una home directory permanente da 5 GB, migliorando notevolmente le prestazioni e l'autenticazione della rete. Ciò significa che per questo codelab ti serve solo un browser.

Per attivare Cloud Shell dalla console Cloud:

1. Fai clic su Attiva Cloud Shell.

Potrebbero occorrere alcuni istanti per eseguire il provisioning e connettersi all'ambiente.

Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è già autenticato e il progetto è già impostato sul tuo PROJECT_ID.

2. Genera un elenco di account con credenziali:

gcloud auth list

Dovresti vedere questo output:

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

Nota:lo strumento CLI gcloud è preinstallato in Cloud Shell e ti aiuta a creare e gestire le risorse Google Cloud. Per saperne di più, consulta la panoramica dello strumento gcloud.

3. Per visualizzare un elenco dei tuoi progetti, inserisci questo comando.

gcloud config list project

Dovresti vedere questo output:

[core]
project = <PROJECT_ID>

Se per qualche motivo il progetto non è impostato, esegui questo comando per configurarlo.

gcloud config set project <PROJECT_ID>

PROJECT_ID è l'ID che hai utilizzato nei passaggi di configurazione. Puoi anche cercarlo nella dashboard della console Cloud:

Cloud Shell imposta anche alcune variabili di ambiente per impostazione predefinita, che potrebbero essere utili quando esegui comandi futuri.

4. Per visualizzare l'ID progetto, inserisci il seguente comando.

echo $GOOGLE_CLOUD_PROJECT

Dovresti vedere l'output seguente:

<PROJECT_ID>

5. Infine, imposta la zona e la configurazione del progetto predefinite.

gcloud config set compute/zone us-central1-f

Puoi scegliere una serie di zone diverse. Per saperne di più, consulta Regioni e zone.

Nota:quando esegui lo strumento a riga di comando gcloud sul tuo computer, le impostazioni di configurazione vengono mantenute da una sessione all'altra. In Cloud Shell, invece, devi configurare queste impostazioni per ogni nuova sessione o riconnessione.

3. Chiamare un'API da un progetto

Questo codelab mostra come utilizzare un'API di esempio (l'API Natural Language) per trovare entità (come persone, luoghi ed eventi) nel testo e come approssimare il sentiment (livello di favorevolezza) di quel testo. Imparerai a:

• Abilita le API Google Cloud.
• Ottieni l'autorizzazione per l'API con chiavi API e service account.
• Chiama l'API con curl e le librerie client.

Abilita un'API

1. Seleziona API e servizi dal menu principale di Cloud Console.

2. Seleziona + ABILITA API E SERVIZI nella parte superiore dello schermo.

3. A questo punto, puoi filtrare e sfogliare le API o andare direttamente a un'API con la casella Cerca. Cerca Natural Language e seleziona API Cloud Natural Language.

4. Fai clic su PROVA QUESTA API.

Se non viene visualizzato il pulsante PROVA QUESTA API, fai clic su uno dei metodi elencati per provarlo.

Creare una chiave API

Poiché utilizzi curl per inviare una richiesta all'API Natural Language, devi generare una chiave API da passare nell'URL della richiesta.

1. Nella console Cloud, seleziona Menu di navigazione > API e servizi > Credenziali.

2. Fai clic su CREA CREDENZIALI e poi seleziona Chiave API:

3. Copia la chiave API generata e poi fai clic su Chiudi.

Utilizzare la chiave API per chiamare l'API

1. Nella riga di comando di Cloud Shell, esporta la chiave API.

export API_KEY=<YOUR_API_KEY>

Sostituisci <YOUR_API_KEY> con la chiave che hai generato in precedenza.

2. Crea una richiesta per l'API nell'editor di Cloud Shell o con un editor Linux, ad esempio Vim o Emacs. Puoi trovare i dettagli dei parametri in Metodo: documents.analyzeEntities. Salva l'output in un file denominato request.json:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. Chiama l'API con le informazioni della richiesta.

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. Esegui di nuovo il comando, reindirizza l'output a un file ed esamina il risultato. I dettagli dell'output del file JSON sono disponibili anche in Method: documents.analyzeEntities.
5. Per modificare il testo da analizzare nel file request.json, sostituisci il valore content con il testo che preferisci.

4. Autorizzare con un service account

Gli account di servizio sono spesso preferiti alle chiavi API perché forniscono sia l'autenticazione che l'autorizzazione. Puoi considerare i service account come indirizzi email per la tua app.

1. Torna alla sezione Credenziali del menu API e servizi.
2. Seleziona Crea credenziali, ma questa volta seleziona Service Account.

3. Fornisci un Nome service account che ne descriva lo scopo, ad esempio "Natural Language Service Account". Il sistema suggerisce un ID. Puoi anche aggiungere una descrizione. Man mano che acquisisci maggiori informazioni sui service account, fornisci l'accesso del service account ai progetti e concedi agli utenti l'accesso al service account, ma per ora fai clic su Fine per creare il service account.
4. Per creare una coppia di chiavi da utilizzare per il service account, fai clic su per modificare il service account.

Vengono visualizzati i dettagli del service account.

5. Copia l'indirizzo email del service account e torna a Cloud Shell.
6. In Cloud Shell, crea una coppia di chiavi per il service account e imposta una variabile di ambiente in modo che punti a questa coppia:

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

Google Cloud utilizza questa variabile di ambiente per trovare le credenziali, quindi non è necessario includerle nella chiamata API.

7. Ora puoi chiamare l'API con il comando:

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

Il risultato dovrebbe essere lo stesso di prima.

Molte API dispongono di librerie client complete da cui estrarre questi dettagli. Per saperne di più sulle librerie client, consulta Librerie client di Cloud. Puoi anche leggere la documentazione delle API che utilizzi per vedere quali librerie client sono disponibili.

5. Esegui la pulizia

È una pratica sconsigliata avere una chiave API senza restrizioni per i progetti. Se qualcuno vi accede, può utilizzarlo senza ulteriori necessità di autenticazione.

Per eliminare questa chiave API:

1. Fai clic su Menu di navigazione > API e servizi > Credenziali.
2. In Chiavi API, seleziona la chiave da eliminare e fai clic su Elimina.
3. Allo stesso modo, anziché preoccuparti che la chiave privata del service account non sia protetta, nella sezione Service Accounts, seleziona il service account da eliminare e poi fai clic su Elimina.

6. Complimenti

Complimenti! Hai imparato a creare un progetto Google Cloud e a chiamare un'API dall'interno del progetto.