Chiama le API da un progetto Google Cloud

1. Prima di iniziare

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

Prerequisiti

• Possibilità 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 account di servizio.

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.

Creare un progetto Google Cloud e configurare un account di fatturazione

Nota:se non hai ancora 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 dell'operazione.

Tieni presente l'ID progetto, visualizzato sotto il campo Nome progetto. L'ID è un nome univoco in tutti i progetti Google Cloud (il nome sopra è già stato utilizzato) e verrà 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 località adatta alla tua organizzazione.

2. Successivamente, abilita la fatturazione nella console Cloud per utilizzare le risorse Google Cloud.

Anche se questo codelab non dovrebbe costare molto, segui le istruzioni nella sezione Pulizia per arrestare le risorse ed evitare costi diversi da questo codelab. Tieni presente che i nuovi utenti di Google Cloud hanno diritto alla prova senza costi di 300$.

Configurare Cloud Shell

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

Per attivare Cloud Shell dalla console Cloud:

1. Fai clic su Attiva Cloud Shell.

Il provisioning e la connessione all'ambiente potrebbero richiedere qualche istante.

Dopo la connessione a Cloud Shell, dovresti vedere che l'autenticazione è già stata effettuata e che il progetto è già impostato su 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 dell'interfaccia a riga di comando gcloud è preinstallato in Cloud Shell e ti aiuta a creare e gestire le risorse Google Cloud. Per ulteriori informazioni, 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 è configurato, esegui questo comando per configurarlo.

gcloud config set project <PROJECT_ID>

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

Cloud Shell imposta anche alcune variabili di ambiente per impostazione predefinita, cosa che può essere utile quando eseguirai comandi futuri.

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

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 zone diverse. Per ulteriori informazioni, consulta Regioni e zone.

Nota:quando esegui lo strumento dell'interfaccia a riga di comando gcloud sulla tua macchina, le impostazioni di configurazione vengono mantenute da una sessione all'altra. In Cloud Shell, tuttavia, devi configurare queste impostazioni per ogni nuova sessione o riconnessione.

3. Chiama un'API da un progetto

Questo codelab ti 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 preferenza) di quel testo. Imparerai a:

• Abilita le API Google Cloud.
• Ottenere l'autorizzazione per l'API con chiavi API e account di servizio.
• Chiama l'API con curl e le librerie client.

Abilita un'API

1. Seleziona API e Services dal menu principale della console Cloud.

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

3. A questo punto, puoi filtrare e sfogliare le API o passare direttamente a un'API utilizzando 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 provare quel metodo.

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 seleziona Chiave API:

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

Utilizza 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 generata 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 Metodo: documents.analyzeEntities.
5. Per cambiare il testo da analizzare nel file request.json, sostituisci il valore content con il testo che preferisci.

4. Autorizza con un account di servizio

Gli account di servizio sono spesso da preferire alle chiavi API in quanto forniscono sia autenticazione che autorizzazione. Puoi considerare gli account di servizio come indirizzi email per la tua app.

1. Torna alla sezione Credenziali della pagina API e Menu.
2. Seleziona Crea credenziali, ma questa volta seleziona Account di servizio.

3. Fornisci un Nome account di servizio che ne descriva lo scopo, ad esempio "Natural Language Service Account". Il sistema suggerisce un ID. Puoi anche aggiungere una descrizione. Man mano che impari di più sugli account di servizio, puoi fornire all'account di servizio l'accesso ai progetti e concedere agli utenti l'accesso all'account di servizio, ma per il momento devi solo fare clic su Fine per creare l'account di servizio.
4. Per creare una coppia di chiavi da utilizzare per l'account di servizio, fai clic su per modificare l'account di servizio.

Vengono visualizzati i dettagli dell'account di servizio.

5. Copia l'indirizzo email dell'account di servizio e torna a Cloud Shell.
6. In Cloud Shell, crea una coppia di chiavi per il tuo account di servizio e imposta una variabile di ambiente 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, che quindi non devono essere incluse 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 ampie librerie client da cui estrarre questi dettagli. Per saperne di più sulle librerie client, consulta Librerie client di Cloud. Puoi anche leggere la documentazione relativa alle API che utilizzi per scoprire quali librerie client sono disponibili.

5. Esegui la pulizia

È sufficiente avere una chiave API senza restrizioni per i progetti. Se qualcuno ottiene l'accesso, quella persona può usarlo senza ulteriore 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, quindi fai clic su Elimina.
3. Analogamente, anziché preoccuparti che la chiave privata dell'account di servizio non sia protetta, in Account di servizio seleziona l'account da eliminare e fai clic su Elimina.

6. Complimenti

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