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

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

Cloud Code semplifica l'aggiunta al progetto delle librerie client Cloud per le API Cloud e il linguaggio che utilizzi. Nella stessa visualizzazione, puoi cercare esempi per ogni API e incorporarli facilmente nella tua applicazione.

Sfogliare le 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 nome dell'API. Vengono visualizzati dettagli come il nome del servizio, lo stato, le istruzioni di installazione per le librerie client, la documentazione e gli esempi di codice.

Attivazione delle API Cloud

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

1. Nella pagina dei dettagli dell'API Cloud, scegli il progetto per cui attivare l'API Cloud.
2. Fai clic su Abilita API. Una volta attivata l'API, viene visualizzato un messaggio per confermare la modifica.

Aggiungere librerie client al progetto

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

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

Utilizzare gli esempi di API

Puoi cercare ed eseguire esempi di codice per ogni API nel browser 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 di esempi, digita il testo da cercare o scegli un linguaggio di programmazione dall'elenco Lingua.

5. Per visualizzare un Sample, fai clic sul nome del Sample. Sono inoltre disponibili opzioni per copiare il sample negli appunti o visualizzarlo su GitHub.

Configurazione dell'autenticazione

Dopo aver attivato le API richieste e aver aggiunto le librerie client necessarie, devi configurare l'applicazione in modo che venga autenticata correttamente. La configurazione dipende dal tipo di sviluppo e dalla piattaforma su cui esegui l'operazione.

Una volta completati i passaggi di autenticazione, l'applicazione può autenticarsi ed è pronta per il deployment.

Sviluppo locale

L'istanza VM Cloud Shell utilizza l'account di servizio predefinito di Compute Engine (l'account di servizio utilizzato per impostazione predefinita da Google Kubernetes Engine) come account di servizio predefinito. Ciò significa che, quando sviluppi con Cloud Code su Cloud Shell, non devi configurare alcuna configurazione aggiuntiva quando utilizzi le librerie client. La tua applicazione è stata autenticata ed è pronta per essere eseguita in locale.

Sviluppo locale con API che richiedono un account di servizio

Alcune API, come l'API Cloud Translation, richiedono un account di servizio con le autorizzazioni appropriate per autenticare le richieste. Per scoprire di più, consulta la pagina Creare e gestire gli 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 service account
   • PROJECT_ID: l'ID progetto

   Per trovare questi ID, in Google Cloudfai clic sul menu di navigazione in alto a sinistra sullo schermo, passa il cursore del mouse sopra 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 dell'account 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 seguente comando di esempio concede il ruolo Utente API Cloud Translation. Per determinare il ruolo da concedere, consulta la documentazione dell'API Cloud in uso.

   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 simulare l'identità dell'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) nell'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 come autenticare Google Cloud i servizi su GKE:

• (Solo per lo sviluppo)
  Nota: l'account di servizio del cluster GKE e le impostazioni dell'ambito di accesso 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 utilizzato per impostazione predefinita da GKE, ovvero l'account di servizio predefinito di Compute Engine, e che Ambiti di accesso sia impostato su Consenti l'accesso completo a tutte le API Cloud (entrambe le impostazioni sono accessibili nella sezione Pool di nodi > Sicurezza). Poiché il service account Compute Engine è condiviso da tutti i carichi di lavoro di cui è stato eseguito il deployment sul tuo nodo, questo metodo esegue il provisioning eccessivo delle autorizzazioni e deve essere utilizzato solo per lo sviluppo.
     • Assicurati che Workload Identity non sia abilitato sul cluster (nella sezione Cluster > Sicurezza).
  2. Assegna i ruoli necessari all'account di servizio:
     • Se utilizzi l'account di servizio predefinito di Compute Engine, i ruoli IAM corretti potrebbero essere già applicati.
     • Per un elenco dei tipi di ruoli IAM e dei ruoli predefiniti che puoi concedere alle identità, consulta la guida Informazioni sui ruoli. Per la procedura di concessione dei ruoli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
• (consigliato per la produzione)
  1. Configura il cluster e l'applicazione GKE con Workload Identity per autenticare i servizi Google Cloud su GKE. In questo modo, il tuo account di servizio Kubernetes viene associato al tuo account di servizio Google.
  2. Configura il deployment Kubernetes in modo che faccia riferimento al service account Kubernetes impostando il campo .spec.serviceAccountName nel file YAML del deployment Kubernetes. Se stai lavorando a un'app creata da un'applicazione di esempio Cloud Code, questo file si trova nella cartella kubernetes-manifests.
  3. Se il Google Cloud servizio a cui stai tentando di accedere richiede ruoli aggiuntivi, concedili per l'account del 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 Informazioni sui ruoli. Per la procedura di concessione dei ruoli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

Cloud Run

1. Per creare un nuovo account di servizio univoco per il deployment dell'applicazione Cloud Run, vai alla pagina Account di servizio e seleziona il progetto in cui è archiviato il 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 Google Cloud servizio a cui stai tentando di accedere richiede ruoli aggiuntivi, concedili, fai clic su Continua e poi su Fine.
6. Per aggiungere l'account di servizio alla configurazione di deployment:
   1. Utilizza la barra di stato di Cloud Code per scegliere il comando Cloud Run: Deploy.
   2. Nell'interfaccia utente di Deployment di Cloud Run, in Impostazioni revisione, nel campo Account di servizio, specifica il tuo account di servizio.
   

Cloud Run

A seconda dell'ambito del progetto, puoi scegliere come autenticare Google Cloud i servizi su GKE:

• (Solo per lo sviluppo)
  Nota: l'account di servizio del cluster GKE e le impostazioni dell'ambito di accesso 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 utilizzato per impostazione predefinita da GKE, ovvero l'account di servizio predefinito di Compute Engine, e che Ambiti di accesso sia impostato su Consenti l'accesso completo a tutte le API Cloud (entrambe le impostazioni sono accessibili nella sezione Pool di nodi > Sicurezza). Poiché il service account Compute Engine è condiviso da tutti i carichi di lavoro di cui è stato eseguito il deployment sul nodo, questo metodo esegue un overprovisioning delle autorizzazioni e deve essere utilizzato solo per lo sviluppo.
     • Assicurati che Workload Identity non sia abilitato nel cluster (nella sezione Cluster > Sicurezza).
  2. Assegna i ruoli necessari all'account di servizio:
     • Se utilizzi l'account di servizio predefinito di Compute Engine, i ruoli IAM corretti potrebbero essere già applicati.
     • Per un elenco dei tipi di ruoli IAM e dei ruoli predefiniti che puoi concedere alle identità, consulta la guida Informazioni sui ruoli. Per la procedura di concessione dei ruoli, consulta Concessione, modifica e revoca dell'accesso alle risorse.
• (consigliato per la produzione)
  1. Configura il cluster e l'applicazione GKE con Workload Identity per autenticare i servizi Google Cloud su GKE. In questo modo, il tuo account di servizio Kubernetes viene associato al tuo account di servizio Google.
  2. Per aggiungere l'account di servizio alla configurazione di deployment:
     1. Utilizza la barra di stato di Cloud Code per scegliere il comando Cloud Run: Deploy.
     2. Nell'interfaccia utente di Deployment di Cloud Run, in Impostazioni revisione, nel campo Account di servizio, specifica il tuo account di servizio.
     
  3. Se il Google Cloud servizio a cui stai tentando di accedere richiede ruoli aggiuntivi, concedili all'account di servizio Google che utilizzi 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 Informazioni sui ruoli. Per la procedura di concessione dei ruoli, consulta Concessione, modifica e revoca dell'accesso alle risorse.

Sviluppo remoto con le autorizzazioni di Secret Manager abilitate

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

1. Fai clic su Cloud Code ed espandi la sezione Gestore dei segreti.

   

2. Fai clic con il tasto destro del mouse sul segreto e seleziona Modifica autorizzazioni nella console Cloud. Verrà aperta la pagina di configurazione di Secret Manager per il segreto nel browser web.

   

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

4. Nel campo Nuove entità, inserisci il nome del tuo account di servizio.

5. Nel campo Seleziona un ruolo, scegli il ruolo Accesso ai segreti di Secret Manager.

6. Fai clic su Salva.

   Il tuo account di servizio ora ha l'autorizzazione per accedere a questo determinato secret.