Gestire le API Cloud e le librerie client di Cloud in Cloud Code for VS Code

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

Cloud Code semplifica l'aggiunta delle librerie client Cloud per le API Cloud e il linguaggio che utilizzi al tuo progetto. 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 vista 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 quali 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 dell'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. Una volta abilitata l'API, viene visualizzato un messaggio per confermare la modifica.

Aggiungere librerie client al progetto

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

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

Utilizzo degli esempi di API

Puoi cercare e utilizzare 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 dettagliata, fai clic sul nome di un'API.

  3. Per visualizzare 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 un linguaggio di programmazione dall'elenco Linguaggio.

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

Configurazione dell'autenticazione

Dopo aver abilitato le API richieste e aggiunto le librerie client necessarie, devi configurare l'applicazione per l'autenticazione. La configurazione dipende dal tipo di sviluppo e dalla piattaforma su cui viene eseguito.

Dopo aver completato i passaggi di autenticazione, l'applicazione può autenticarsi ed è pronta per essere implementata.

Sviluppo locale

Macchina locale

Se hai eseguito l'accesso a Google Cloud nel tuo IDE, Cloud Code imposta le credenziali predefinite dell'applicazione (ADC) e puoi saltare questo passaggio. Se hai eseguito l'accesso a Google Cloud al di fuori del tuo IDE (ad esempio, utilizzando gcloud CLI), configura le credenziali predefinite dell'applicazione e consenti alle librerie client di autenticarsi tramite ADC eseguendo: Google Cloud 

gcloud auth login --update-adc

minikube

  1. Se hai eseguito l'accesso a Google Cloud nel tuo IDE, Cloud Code imposta le credenziali predefinite dell'applicazione (ADC) e puoi saltare questo passaggio. Se hai eseguito l'accesso a Google Cloud al di fuori del tuo IDE (ad esempio, utilizzando gcloud CLI), configura le credenziali predefinite dell'applicazione e consenti alle librerie client di autenticarsi tramite ADC eseguendo: Google Cloud 

    gcloud auth login --update-adc
  2. Avvia minikube eseguendo minikube start --addons gcp-auth. Questo comando monta le tue credenziali predefinite dell'account di servizio nei pod. Per informazioni dettagliate sull'autenticazione di minikube con Google Cloud, consulta la documentazione di minikube gcp-auth.

Altri cluster K8s locali

  1. Se hai eseguito l'accesso a Google Cloud nel tuo IDE, Cloud Code imposta le credenziali predefinite dell'applicazione (ADC) e puoi saltare questo passaggio. Se hai eseguito l'accesso a Google Cloud al di fuori del tuo IDE (ad esempio, utilizzando gcloud CLI), configura le credenziali predefinite dell'applicazione e consenti alle librerie client di autenticarsi tramite ADC eseguendo: Google Cloud 

    gcloud auth login --update-adc
  2. Per assicurarti che le librerie client Google Cloud possano trovare le tue credenziali, monta la directory ~/.config/gcloud locale nei pod Kubernetes modificando i manifest di deployment.
  3. Imposta l'ID progetto Google Cloud come variabile di ambiente denominata GOOGLE_CLOUD_PROJECT.

Esempio di configurazione del pod Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
  labels:
    name: my-app
spec:
  containers:
  - name: my-app
    image: gcr.io/google-containers/busybox
    ports:
      - containerPort: 8080
    env:
    - name: GOOGLE_CLOUD_PROJECT
      value: my-project-id
    volumeMounts:
      - mountPath: /root/.config/gcloud
        name: gcloud-volume
  volumes:
    - name: gcloud-volume
      hostPath:
        path: /path/to/home/.config/gcloud

Cloud Run

Se hai eseguito l'accesso a Google Cloud nel tuo IDE, Cloud Code imposta le credenziali predefinite dell'applicazione (ADC) e puoi saltare questo passaggio. Se hai eseguito l'accesso a Google Cloud al di fuori del tuo IDE (ad esempio, utilizzando gcloud CLI), configura le credenziali predefinite dell'applicazione e consenti alle librerie client di autenticarsi tramite ADC eseguendo: Google Cloud 

gcloud auth login --update-adc

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 richieste. Per saperne di più, vedi Creazione e gestione dei service account. Per una guida rapida che utilizza un account di servizio, consulta Utilizza le librerie client di Cloud in Cloud Code.

  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 del 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 sopra IAM e amministrazione e fai clic su Service account.

    La colonna Email mostra l'SERVICE_ACCOUNT_ID e l'PROJECT_ID unici per ciascuno dei tuoi service account nel seguente formato:

    SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com

    Ad esempio, un indirizzo email del account di servizio my-service-account@my-project.iam.gserviceaccount.com ha i seguenti valori:

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

  3. Concedi al tuo account di servizio il ruolo appropriato. Il seguente comando di esempio concede il ruolo di 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 simulare l'identità del service account, esegui il comando gcloud iam service-accounts add-iam-policy-binding per concedere a un utente il ruolo Utente service account (roles/iam.serviceAccountUser) nel 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 sviluppo)
    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 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é il account di servizio Compute Engine è condiviso da tutti i carichi di lavoro di cui è stato eseguito il deployment sul 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 tuo cluster (nella sezione Cluster > Sicurezza).
    2. Assegna i ruoli necessari al account di servizio:
  • (Consigliato per la produzione)
    1. Configura il cluster GKE e l'applicazione con Workload Identity per autenticare Google Cloud i servizi 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 di 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 il service account Google che utilizzi per sviluppare la tua app:

Cloud Run

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

    Vai alla pagina Service account

  2. Fai clic su Crea service account.
  3. Nella finestra di dialogo Crea service account, inserisci un nome descrittivo per il account di servizio.
  4. Modifica l'ID account di servizio con un valore univoco e riconoscibile e poi 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 su Fine.
  6. Per aggiungere il account di servizio alla configurazione di deployment:
    1. Utilizzando la barra di stato di Cloud Code, scegli il comando Cloud Run: Deploy (Cloud Run: esegui il deployment).
    2. Nell'interfaccia utente di Cloud Run Deployment, in Revision Settings (Impostazioni revisione), nel campo Service Account (Service account), specifica il tuo account di servizio.
    Sezione Impostazioni avanzate di revisione espansa in Cloud Run: campo Deployment e service account compilato con il nome account di servizio nel formato service-account-name@project-name.iam.gserviceaccount.com

Cloud Run

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

  • (Solo sviluppo)
    1. Crea un cluster GKE con le seguenti impostazioni:
      • Assicurati di utilizzare il account di servizio che GKE utilizza per impostazione predefinita, ovvero il account di servizio Compute Engine predefinito, 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é il account di servizio Compute Engine è condiviso da tutti i carichi di lavoro di cui è stato eseguito il deployment sul 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 al account di servizio:
  • (Consigliato per la produzione)
    1. Configura il cluster GKE e l'applicazione con Workload Identity per autenticare Google Cloud i servizi su GKE. In questo modo, il tuo account di servizio Kubernetes viene associato al tuo account di servizio Google.
    2. Per aggiungere il account di servizio alla configurazione di deployment:
      1. Utilizzando la barra di stato di Cloud Code, scegli il comando Cloud Run: Deploy (Cloud Run: esegui il deployment).
      2. Nell'interfaccia utente di Cloud Run Deployment, in Revision Settings (Impostazioni revisione), nel campo Service Account (Service account), specifica il tuo account di servizio.
      Sezione Impostazioni avanzate di revisione espansa in Cloud Run: campo Deployment e service account compilato con il nome del account di servizio Kubernetes nel formato service-account-name@project-name.iam.gserviceaccount.com
    3. Se il servizio Google Cloud a cui stai tentando di accedere richiede ruoli aggiuntivi, concedili per il account di servizio Google che stai utilizzando per sviluppare l'app:

Sviluppo remoto con le autorizzazioni di Secret Manager abilitate

Se esegui lo sviluppo da remoto, utilizzi un account di servizio per l'autenticazione e la tua applicazione utilizza secret, devi completare alcuni passaggi aggiuntivi oltre alle istruzioni per lo sviluppo da 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 Secret Manager.

    Secret Manager in Cloud Code si apre con due secret elencati

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

    Secret su cui è stato fatto clic con il tasto destro del mouse nel riquadro di Secret Manager

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

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

  5. Nel campo Seleziona un ruolo, scegli il ruolo Secret Manager Secret Accessor.

  6. Fai clic su Salva.

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

Richiedi assistenza

Per inviare feedback, segnala problemi su GitHub, oppure fai una domanda su Stack Overflow.