Gestisci le API Cloud e le librerie client di Cloud in Cloud Code per Cloud Shell

Per accedere ai prodotti e ai servizi Google Cloud in modo programmatico, puoi utilizzare le API Cloud. Queste API espongono una semplice interfaccia REST JSON. Il modo consigliato per accedere alle API Cloud è utilizzare le librerie client di Cloud.

Cloud Code semplifica l'aggiunta delle librerie client di Cloud per le API Cloud e il linguaggio che utilizzi nel tuo progetto. Nella stessa vista puoi cercare esempi per ogni API e incorporare facilmente gli esempi nella tua applicazione.

Navigazione delle API Cloud

Per esplorare tutte le API Google Cloud disponibili:

1. Fai clic su Cloud Code ed espandi la sezione API Cloud.

   La visualizzazione API Cloud raggruppa le API Cloud per categoria.

2. Per visualizzare i dettagli di un'API, fai clic sul suo nome. Sono visualizzati dettagli come il nome del servizio, lo stato, le istruzioni di installazione per le librerie client, la documentazione e gli esempi di codice.

Abilitazione delle API Cloud

Per abilitare le API Cloud per un progetto utilizzando la pagina dei dettagli delle API, segui questi passaggi:

1. Nella pagina dei dettagli dell'API Cloud, scegli il progetto per cui abilitare l'API Cloud.
2. Fai clic su Abilita API. Dopo aver abilitato l'API, viene visualizzato un messaggio per confermare la modifica.

Aggiunta di librerie client al progetto

Oltre a esplorare e abilitare le API Cloud utilizzando Cloud Code, puoi aggiungere al tuo progetto una libreria client specifica per il linguaggio.

Per installare una libreria client, segui le istruzioni nella pagina dei dettagli dell'API per la tua lingua.

Utilizzo di esempi di API

Puoi cercare e utilizzare esempi di codice per ogni API nel browser delle API.

1. Fai clic su Cloud Code ed espandi la sezione API Cloud.

2. Per aprire la visualizzazione dei dettagli, fai clic sul nome di un'API.

3. Per visualizzare gli esempi di codice per l'API, fai clic su Esempi di codice.

4. Per filtrare l'elenco degli esempi, digita il testo da cercare o scegli una lingua di programmazione dall'elenco Lingua.

5. Per visualizzare un campione, fai clic sul suo nome. Esistono anche opzioni per copiare l'esempio negli appunti o per visualizzarlo in GitHub.

Configurazione dell'autenticazione

Dopo aver abilitato le API richieste e aggiunto le librerie client necessarie, devi configurare l'applicazione affinché venga autenticato correttamente. La configurazione dipende dal tipo di sviluppo e dalla piattaforma su cui viene eseguita.

Dopo aver completato la procedura di autenticazione, l'applicazione può autenticarsi ed è pronta per il deployment.

Sviluppo locale

L'istanza VM di Cloud Shell utilizza l'account di servizio predefinito di Compute Engine (l'account di servizio utilizzato da Google Kubernetes Engine per impostazione predefinita) come account di servizio predefinito. Ciò significa che durante lo sviluppo con Cloud Code su Cloud Shell, non è necessario impostare alcuna configurazione aggiuntiva quando lavori con le librerie client. L'applicazione è autenticata e pronta per essere eseguita localmente.

Sviluppo locale con API che richiedono un account di servizio

Alcune API, come l'API Cloud Translation, richiedono un account di servizio con autorizzazioni appropriate per autenticare le tue richieste. Per maggiori informazioni, consulta Creazione e gestione degli account di servizio.

1. Per aprire un terminale, fai clic su Terminale > Nuovo terminale.

2. Crea un account di servizio per autenticare le richieste API:

   gcloud iam service-accounts create \
   SERVICE_ACCOUNT_ID \
   --project PROJECT_ID
   

   Sostituisci i seguenti valori:

   • SERVICE_ACCOUNT_ID: l'ID dell'account di servizio
   • PROJECT_ID: l'ID progetto

   Per trovare questi ID, in Google Cloud fai clic sul menu di navigazione in alto a sinistra dello schermo, tieni il puntatore del mouse su IAM e amministrazione e fai clic su Account di servizio.

   La colonna Email mostra i valori SERVICE_ACCOUNT_ID e PROJECT_ID univoci per ciascuno dei tuoi account di servizio nel seguente formato:

   SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com

   Ad esempio: un indirizzo email di un account di servizio di [e-mail] ha i seguenti valori:

   • SERVICE_ACCOUNT_ID: my-service-account
   • PROJECT_ID: my-project

3. Concedi all'account di servizio il ruolo appropriato. Il comando di esempio riportato di seguito concede il ruolo Utente API Cloud Translation. Per determinare il ruolo da concedere, consulta la documentazione dell'API Cloud che stai utilizzando.

   gcloud projects \
   add-iam-policy-binding \
   PROJECT_ID \
   --member='serviceAccount:SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com' \
   --role='roles/cloudtranslate.user'
   

4. Crea una chiave dell'account di servizio:

   gcloud iam service-accounts keys \
   create key.json --iam-account \
   SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com
   

5. Imposta la chiave come credenziale predefinita:

   export \
    GOOGLE_APPLICATION_CREDENTIALS=key.json
   

6. (Facoltativo) Per consentire agli utenti di impersonare l'account di servizio, esegui il comando gcloud iam service-accounts add-iam-policy-binding per concedere a un utente il ruolo Utente account di servizio (roles/iam.serviceAccountUser) per l'account di servizio:

   gcloud iam service-accounts add-iam-policy-binding \
       SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com \
       --member="user:USER_EMAIL" \
       --role="roles/iam.serviceAccountUser"
   

   Sostituisci i seguenti valori:

   • USER_EMAIL: l'indirizzo email dell'utente

Sviluppo remoto

GKE

A seconda dell'ambito del progetto, puoi scegliere la modalità di autenticazione dei servizi Google Cloud su GKE:

• (Solo sviluppo)
  Nota: le impostazioni dell'account di servizio e dell'ambito di accesso del cluster GKE sono permanenti; dopo la creazione del cluster, queste impostazioni non possono essere modificate. Specifica le impostazioni come consigliato di seguito.
  1. Crea un cluster GKE con le seguenti impostazioni:
     • Assicurati di utilizzare l'account di servizio che GKE utilizza per impostazione predefinita, l'account di servizio predefinito di Compute Engine e che gli Ambiti di accesso siano impostati su Consenti l'accesso completo a tutte le API Cloud (entrambe le impostazioni sono accessibili nella sezione Pool di nodi > Sicurezza). Poiché l'account di servizio Compute Engine è condiviso da tutti i carichi di lavoro di cui è stato eseguito il deployment sul nodo, questo metodo esegue l'overprovisioning delle autorizzazioni e deve essere utilizzato solo per lo sviluppo.
     • Assicurati che Workload Identity non sia abilitato nel tuo cluster (nella sezione Cluster > Sicurezza).
  2. Assegna i ruoli necessari all'account di servizio:
     • Se utilizzi l'account di servizio predefinito di Compute Engine, potrebbero essere già stati applicati i ruoli IAM corretti.
     • Per un elenco dei tipi di ruoli IAM e dei ruoli predefiniti che è possibile concedere alle identità, consulta la Guida alla comprensione dei ruoli. Per la procedura di concessione dei ruoli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
• (Consigliata per la produzione)
  1. Configura il tuo cluster e la tua applicazione GKE con Workload Identity per autenticare i servizi Google Cloud su GKE. In questo modo il tuo account di servizio Kubernetes verrà associato all'account di servizio Google.
  2. Configura il tuo deployment Kubernetes in modo che faccia riferimento all'account di servizio Kubernetes impostando il campo .spec.serviceAccountName nel file YAML del deployment di Kubernetes. Se stai lavorando su un'app creata da un'applicazione di esempio Cloud Code, questo file si trova nella cartella kubernetes-manifests.
  3. Se il servizio Google Cloud a cui stai tentando di accedere richiede ruoli aggiuntivi, concedili per l'account di servizio Google che stai utilizzando per sviluppare la tua app:
     • Per un elenco dei tipi di ruoli IAM e dei ruoli predefiniti che puoi concedere alle identità, consulta la guida alla comprensione dei ruoli. Per la procedura di concessione dei ruoli, vedi Concessione, modifica e revoca dell'accesso alle risorse.

Cloud Run

1. Per creare un nuovo account di servizio univoco per il deployment della tua applicazione Cloud Run, vai alla pagina Account di servizio e seleziona il progetto in cui è archiviato il tuo secret.

   Vai alla pagina Account di servizio

2. Fai clic su Crea account di servizio.
3. Nella finestra di dialogo Crea account di servizio, inserisci un nome descrittivo per l'account di servizio.
4. Modifica l'ID account di servizio in un valore univoco e riconoscibile, quindi fai clic su Crea.
5. Se il servizio Google Cloud a cui stai tentando di accedere richiede ruoli aggiuntivi, concedi i ruoli, fai clic su Continua e poi fai clic su Fine.
6. Per aggiungere il tuo account di servizio alla configurazione di deployment:
   1. Utilizzando la barra di stato di Cloud Code, scegli il comando Cloud Run: Deploy.
   2. Nell'interfaccia utente del deployment di Cloud Run, in Impostazioni di revisione, nel campo Account di servizio, specifica il tuo account di servizio.
   

Cloud Run

A seconda dell'ambito del progetto, puoi scegliere la modalità di autenticazione dei servizi Google Cloud su GKE:

• (Solo sviluppo)
  Nota: le impostazioni dell'account di servizio e dell'ambito di accesso del cluster GKE sono permanenti; dopo la creazione del cluster, queste impostazioni non possono essere modificate. Specifica le impostazioni come consigliato di seguito.
  1. Crea un cluster GKE con le seguenti impostazioni:
     • Assicurati di utilizzare l'account di servizio che GKE utilizza per impostazione predefinita, l'account di servizio predefinito di Compute Engine, e che gli Ambiti di accesso siano impostati su Consenti l'accesso completo a tutte le API Cloud (entrambe le impostazioni sono accessibili nella sezione Pool di nodi > Sicurezza). Poiché l'account di servizio Compute Engine è condiviso da tutti i carichi di lavoro di cui è stato eseguito il deployment sul nodo, questo metodo esegue l'overprovisioning delle autorizzazioni e deve essere utilizzato solo per lo sviluppo.
     • Assicurati che Workload Identity non sia abilitato nel tuo cluster (in Cluster > Sicurezza).
  2. Assegna i ruoli necessari all'account di servizio:
     • Se utilizzi l'account di servizio predefinito di Compute Engine, potrebbero essere già stati applicati i ruoli IAM corretti.
     • Per un elenco dei tipi di ruoli IAM e dei ruoli predefiniti che puoi concedere alle identità, consulta la guida alla comprensione dei ruoli. Per la procedura di concessione dei ruoli, vedi Concessione, modifica e revoca dell'accesso alle risorse.
• (Consigliata per la produzione)
  1. Configura il tuo cluster e la tua applicazione GKE con Workload Identity per autenticare i servizi Google Cloud su GKE. In questo modo il tuo account di servizio Kubernetes verrà associato all'account di servizio Google.
  2. Per aggiungere il tuo account di servizio alla configurazione di deployment:
     1. Utilizzando la barra di stato di Cloud Code, scegli il comando Cloud Run: Deploy.
     2. Nell'interfaccia utente del deployment di Cloud Run, in Impostazioni di revisione, nel campo Account di servizio, specifica il tuo account di servizio.
     
  3. Se il servizio Google Cloud a cui stai tentando di accedere richiede ruoli aggiuntivi, concedili per l'account di servizio Google che stai utilizzando per sviluppare la tua app:
     • Per un elenco dei tipi di ruoli IAM e dei ruoli predefiniti che puoi concedere alle identità, consulta la guida alla comprensione dei ruoli. Per la procedura di concessione dei ruoli, vedi Concessione, modifica e revoca dell'accesso alle risorse.

Sviluppo remoto con autorizzazioni di Secret Manager abilitate

Se stai sviluppando in remoto, utilizzando un account di servizio per l'autenticazione e la tua applicazione utilizza i secrets, devi completare alcuni passaggi aggiuntivi oltre alle istruzioni per lo sviluppo da remoto. Questi passaggi assegnano al tuo account di servizio Google il ruolo necessario per accedere a un determinato secret di Secret Manager:

1. Fai clic su Cloud Code ed espandi la sezione Secret Manager.

   

2. Fai clic con il tasto destro del mouse sul secret e seleziona Modifica autorizzazioni nella console Cloud. Viene avviata la pagina di configurazione di Secret Manager per quel secret nel tuo browser web.

   

3. Nella console Google Cloud, fai clic su Autorizzazioni e quindi su Aggiungi.

4. Nel campo Nuove entità, inserisci il nome dell'account di servizio.

5. Nel campo Seleziona un ruolo, scegli il ruolo Amministratore secret di Secret Manager.

6. Fai clic su Salva.

   Il tuo account di servizio dispone ora dell'autorizzazione per accedere a questo secret specifico.