Proteggere il traffico verso un servizio con la console Google Cloud

Questa pagina mostra come eseguire il deployment di un'API su API Gateway per proteggere il traffico a un servizio di backend.

Segui i passaggi riportati di seguito per eseguire il deployment di una nuova API per accedere a un servizio di backend su Cloud Run Functions utilizzando la console Google Cloud. Questo inizio rapido descrive anche come utilizzare una chiave API per proteggere il backend da accessi non autorizzati.

Prima di iniziare

1. Nella console Google Cloud, vai alla pagina API Gateway e seleziona o crea un progetto Google Cloud.

   Vai alla pagina API Gateway

   Nota: se non prevedi di conservare le risorse create in questa guida introduttiva, crea un nuovo progetto anziché selezionarne uno esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.

2. API Gateway richiede l'abilitazione dei seguenti servizi Google:

   Nome	Titolo
   apigateway.googleapis.com	API API Gateway
   servicemanagement.googleapis.com	API Service Management
   servicecontrol.googleapis.com	API Service Control

   Se non hai già attivato questi servizi per il progetto selezionato, ti verrà chiesto di farlo.

3. Verifica che la fatturazione sia attivata per il progetto.

   Scopri come attivare la fatturazione

Deployment di un backend API

API Gateway si trova di fronte a un servizio di backend di cui è stato eseguito il deployment e gestisce tutte le richieste in entrata. In questa guida introduttiva, API Gateway inoltra le chiamate in arrivo a un backend di funzioni Cloud Run denominato helloGET che contiene la funzione mostrata di seguito:

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Segui i passaggi descritti in Guida rapida: utilizzo di Google Cloud CLI per scaricare il codice delle funzioni Cloud Run di esempio ed eseguire il deployment del servizio di backend della funzione Cloud Run.

Nota: il nome effettivo della funzione e del backend nell'esempio varia in base alla lingua scelta al termine del tutorial sulle funzioni Cloud Run. Questo tutorial utilizza l'esempio di Node.js.

Creazione di una definizione di API

API Gateway utilizza una definizione di API per instradare le chiamate al servizio di backend. Puoi utilizzare una specifica OpenAPI che contiene annotazioni per definire il comportamento desiderato di API Gateway. La specifica OpenAPI per questa guida rapida contiene istruzioni di routing per il backend della funzione Cloud Run:

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://us-central1-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

Per utilizzare la specifica OpenAPI mostrata sopra per definire l'API:

1. Dalla riga di comando, crea un nuovo file denominato openapi2-functions.yaml.

2. Copia e incolla il contenuto della specifica OpenAPI mostrata sopra nel file appena creato.

3. Modifica il file come segue:

   1. Nel campo title, sostituisci API_ID con il nome dell'API (che verrà creata nel passaggio successivo) e sostituisci optional-string con una breve descrizione di tua scelta. Il valore di questo campo viene utilizzato per coniare le chiavi API che consentono l'accesso a questa API. Consulta i requisiti per gli ID API per le linee guida per la denominazione degli ID API.
   2. Nel campo address, sostituisci PROJECT_ID con il nome del tuo progetto Google Cloud.

Creazione di un gateway

Ora è tutto pronto per creare ed eseguire il deployment di un gateway su API Gateway.

1. Apri la pagina API Gateway nella console Google Cloud.

   Vai alla pagina API Gateway

2. Fai clic su Crea gateway.

3. Nella sezione API:

   1. Puoi scegliere di creare una nuova API o selezionarne una esistente dal menu a discesa Seleziona un'API. Per questo tutorial, seleziona Crea una nuova API.
   2. Inserisci il Nome visualizzato per l'API.
   3. Inserisci l'ID API della tua API.
   4. (Facoltativo) Aggiungi etichette all'API utilizzando un formato chiave/valore. Per aggiungerne altre di un'etichetta, fai clic su Aggiungi etichetta e inserisci altri valori.

4. Nella sezione Configurazione API:

   1. Puoi scegliere di creare una nuova configurazione API o selezionarne una esistente dal menu a discesa Seleziona una configurazione. Per questo tutorial, seleziona Crea una nuova configurazione API.
   2. Utilizza il browser dei file per caricare il file openapi2-functions.yaml utilizzato per definire la tua API.
   3. Inserisci un nome visualizzato per la configurazione API.

   4. Seleziona un account di servizio dall'elenco a discesa. L'account di servizio che selezioni verrà utilizzato come identità per API Gateway.

      Nota: se non vedi un account di servizio elencato nel menu a discesa, consulta Configurazione di un account di servizio per assicurarti che sia abilitato un account di servizio per il tuo progetto.

   5. (Facoltativo) Aggiungi etichette alla configurazione dell'API utilizzando un formato chiave/valore. Per aggiungere più di un'etichetta, fai clic su Aggiungi etichetta e inserisci ulteriori valori.

5. Nella sezione Dettagli gateway:

   1. Inserisci il nome visualizzato del gateway. L'URL del gateway viene generato automaticamente.
   2. Seleziona la posizione della porta di accesso dal menu a discesa.
   3. (Facoltativo) Aggiungi etichette al gateway utilizzando un formato chiave/valore. Per aggiungerne altre di un'etichetta, fai clic su Aggiungi etichetta e inserisci altri valori.

6. Fai clic su Crea gateway.

Questa operazione esegue il deployment della configurazione API su un gateway appena creato. Il deployment di una configurazione API su un gateway definisce un URL esterno che i client API possono utilizzare per accedere all'API.

Il completamento dell'operazione potrebbe richiedere diversi minuti. Per controllare lo stato di il processo di creazione e deployment, puoi fare clic sull'icona Notifica nella barra di navigazione principale per visualizzare una notifica di stato, come mostrato nell'immagine di seguito:

Al termine dell'operazione, puoi visualizzare i dettagli del gateway nella pagina di destinazione Gateway.

Vai alla pagina Gateway

Prendi nota dell'URL del gateway. Questo viene utilizzato per testare il deployment nel passaggio successivo.

Nota: potrebbero essere necessari alcuni istanti prima che venga visualizzato l'URL del gateway appena creato. Se non viene visualizzato dopo qualche istante, fai clic su Aggiorna nella pagina di destinazione dei gateway per aggiornare la visualizzazione.

Testare il deployment dell'API

Ora puoi inviare richieste all'API utilizzando l'URL generato al momento del deployment del gateway.

Nel browser, inserisci il seguente URL, dove:

• GATEWAY_URL specifica l'URL del gateway di cui è stato eseguito il deployment.
• hello è il percorso specificato nella configurazione API.

https://GATEWAY_URL/hello

Ad esempio:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Nel browser dovrebbe essere visualizzato il messaggio Hello World!.

Hai creato ed eseguito correttamente il deployment di API Gateway.

Proteggere l'accesso con una chiave API

Per proteggere l'accesso al backend dell'API, puoi generare una chiave API associata al progetto e concedere l'accesso alla chiave per chiamare l'API. Per ulteriori informazioni, consulta Limitare l'accesso alle API con le chiavi API.

Se non hai già una chiave API associata al progetto Google Cloud che stai utilizzando in questa guida rapida, puoi aggiungerne una seguendo la procedura descritta in Creazione di una chiave API.

Per proteggere l'accesso al gateway utilizzando una chiave API:

1. Attiva il supporto delle chiavi API per il tuo servizio:
   1. Nella console Google Cloud, vai a API e servizi > Libreria.
   2. Nella barra di ricerca, inserisci il nome del servizio gestito dell'API che hai appena creato. Puoi trovare questo valore nella colonna Servizio gestito per l'API nella pagina di destinazione delle API. Ad esempio:

      my-api-123abc456def1.apigateway.my-project.cloud.goog

   3. Nella pagina di destinazione del servizio, fai clic su Abilita.
      Nota: potrebbe essere presente un ritardo massimo di 30 minuti o più tra il momento in cui crei l'API e quello in cui viene visualizzata nella raccolta. Se l'API non è visibile nella libreria, puoi attivarla utilizzando lo strumento a riga di comando gcloud. Inserisci il seguente comando, dove MANAGED_SERVICE_NAME specifica il nome del servizio gestito della tua API:

      gcloud services enable MANAGED_SERVICE_NAME

2. Modifica la specifica OpenAPI utilizzata per creare la configurazione API in modo da includere le istruzioni per applicare un criterio di sicurezza per la convalida della chiave API su tutto il traffico. Aggiungi il tipo security e securityDefinitions come mostrato di seguito:

       # openapi2-functions.yaml
       swagger: '2.0'
       info:
         title: API_ID optional-string
         description: Sample API on API Gateway with a Google Cloud Functions backend
         version: 1.0.0
       schemes:
         - https
       produces:
         - application/json
       paths:
         /hello:
           get:
             summary: Greet a user
             operationId: hello
             x-google-backend:
               address:https://us-central1.PROJECT_ID.cloudfunctions.net/helloGET
             security:
             - api_key: []
             responses:
               '200':
                 description: A successful response
                 schema:
                   type: string
       securityDefinitions:
         # This section configures basic authentication with an API key.
         api_key:
           type: "apiKey"
           name: "key"
           in: "query"

   securityDefinition configura l'API in modo che richieda una chiave API passato come parametro di query denominato key quando viene richiesto l'accesso a tutti i percorsi definiti nella specifica.
3. Crea ed esegui il deployment di una nuova configurazione API nel gateway esistente:
   1. Vai alla pagina di destinazione Gateway.

      Vai alla pagina Gateway

   2. Seleziona il gateway dall'elenco per visualizzare i dettagli.
   3. Fai clic su Modifica per aprire il riquadro di configurazione del gateway.
   4. Nella sezione Configurazione API:
      1. Seleziona Crea una nuova configurazione API dal menu a discesa disponibile.
      2. Carica la specifica OpenAPI modificata utilizzando il browser dei file.
      3. Inserisci il nome visualizzato per la nuova configurazione API.
      4. Seleziona un account di servizio dall'elenco a discesa. L'account di servizio selezionato verrà utilizzato come identità per API Gateway.
      5. (Facoltativo) Aggiungi etichette alla configurazione API utilizzando un formato chiave/valore. Per aggiungere più di un'etichetta, fai clic su Aggiungi etichetta e inserisci altri valori.
   5. Fai clic su Aggiorna.

Test della chiave API

Dopo aver creato l'API modificata e aver eseguito il deployment sulla stessa, prova a inviare una richiesta.

Nel browser, inserisci il seguente URL, dove:

• GATEWAY_URL specifica l'URL del gateway di cui è stato eseguito il deployment.
• hello è il percorso specificato nella configurazione API.

https://GATEWAY_URL/hello

Ad esempio:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

Dovrebbe verificarsi il seguente errore:

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Ora, nel browser, inserisci il seguente URL, dove:

• GATEWAY_URL specifica l'URL del gateway di cui è stato eseguito il deployment.
• hello è il percorso specificato nella configurazione API.
• API_KEY specifica la chiave API creata nella sezione Proteggere l'accesso mediante una chiave API.

https://GATEWAY_URL/hello?key=API_KEY

Ora dovresti vedere Hello World! nel browser.

Complimenti! Hai protetto correttamente il backend dell'API con un API Gateway. Ora puoi iniziare l'onboarding di nuovi client API generando ulteriori chiavi API.

monitora l'attività dell'API

1. Visualizza i grafici delle attività per la tua API nella pagina API Gateway della console Google Cloud. Fai clic sulla tua API per visualizzarne i grafici di attività nella Panoramica. L'applicazione delle richieste potrebbe richiedere qualche istante nei grafici.

2. Controlla i log delle richieste per l'API nella pagina Esplora log. Un link alla pagina Esplora log è disponibile nella pagina API Gateway della console Google Cloud.

   Vai alla pagina API Gateway

   Nella pagina API Gateway:
   1. Seleziona l'API da visualizzare.
   2. Fai clic sulla scheda Dettagli.
   3. Fai clic sul link sotto Log.

Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questa guida rapida, puoi:

• Eliminare i gateway
• Eliminare l'API

In alternativa, puoi anche eliminare il progetto Google Cloud utilizzato per questo tutorial.

Passaggi successivi

• Scopri di più su API Gateway
• Segui la procedura per la configurazione dell'ambiente di sviluppo