Guida rapida: proteggi il traffico verso un servizio con la Google Cloud console

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

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

Prima di iniziare

Nella console Google Cloud , vai alla pagina API Gateway.

Vai ad API Gateway

Nota: se non prevedi di conservare le risorse che crei in questa guida rapida, crea un nuovo progetto invece di selezionarne uno già esistente. Una volta completata questa procedura, puoi eliminare il progetto e tutte le relative risorse.
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 attivato in precedenza questi servizi per il progetto selezionato, ti viene chiesto di farlo.
Verifica che la fatturazione sia abilitata per il tuo progetto.
Scopri come attivare la fatturazione

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

Esegui il deployment di un backend API

API Gateway si trova davanti a un servizio di backend di cui è stato eseguito il deployment e gestisce tutte le richieste in entrata. In questa guida rapida, API Gateway indirizza le chiamate in entrata a un backend Cloud Run Functions denominato helloGET che contiene la funzione Node.js mostrata di seguito.

const functions = require('@google-cloud/functions-framework');

// Register an HTTP function with the Functions Framework that will be executed
// when you make an HTTP request to the deployed function's endpoint.
functions.http('helloGET', (req, res) => {
  res.send('Hello World!');
});

Segui i passaggi descritti in Guida rapida: utilizzo di Google Cloud CLI per scaricare il codice di esempio delle funzioni Cloud Run ed eseguire il deployment del servizio di backend della funzione Cloud Run. Il tuo amministratore dovrà concedere ruoli aggiuntivi al tuo account e al account di servizio Cloud Build, come descritto in questa guida rapida.

Copia l'URL del servizio visualizzato quando viene eseguito il deployment della funzione Cloud Run. Ti servirà per creare la configurazione API nel passaggio successivo.

Crea una configurazione API

API Gateway utilizza una configurazione API per indirizzare le chiamate al servizio di backend. Puoi utilizzare una specifica OpenAPI che contiene estensioni specializzate per definire il comportamento scelto di API Gateway. Per maggiori dettagli sulle estensioni OpenAPI supportate, consulta quanto segue:

La specifica OpenAPI per questa guida rapida contiene istruzioni di routing per il backend della funzione Cloud Run:

OpenAPI 2.0

# openapi-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: SERVICE_URL/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    functions_backend:
      address: SERVICE_URL/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

Utilizza questa specifica OpenAPI per definire la tua API:

Dalla riga di comando, crea un nuovo file denominato openapi-functions.yaml.
Copia e incolla il contenuto della specifica OpenAPI mostrata nell'esempio precedente nel file appena creato.
Modifica il file come segue:
1. Nel campo title, sostituisci API_ID con il nome della tua API (che creerai nel passaggio successivo) e optional-string con una breve descrizione a tua scelta. Il valore di questo campo viene utilizzato per generare chiavi API che concedono l'accesso a questa API. Per le linee guida per la denominazione degli ID API, consulta Requisiti per l'ID API.
2. Nel campo address, sostituisci SERVICE_URL con l'URL in cui è in esecuzione il servizio di backend della funzione Cloud Run, copiato nel passaggio precedente.

Crea un gateway

Ora puoi creare ed eseguire il deployment di un gateway su API Gateway.

Apri la pagina API Gateway nella console Google Cloud .

Vai ad API Gateway
Fai clic su Crea gateway.
Nella sezione API:
1. Scegli di creare una nuova API o seleziona un'API esistente dal menu a discesa Seleziona un'API. Per questo tutorial, seleziona Crea una nuova API.
2. Inserisci il nome visualizzato per la tua API.
3. Inserisci l'ID API per la tua API.
4. (Facoltativo) Aggiungi etichette all'API utilizzando un formato chiave:valore. Per aggiungere più di un'etichetta, fai clic su Aggiungi etichetta e inserisci altri valori.
Nella sezione Configurazione API:
1. Scegli di creare una nuova configurazione API o seleziona una configurazione API 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 openapi-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 selezionato viene utilizzato come identità per API Gateway. Se non vedi un account di servizio elencato nel menu a discesa, consulta Configurazione di un service account per verificare che un account di servizio sia abilitato per il tuo progetto.
  
  Nota: il account di servizio utilizzato per creare una configurazione API per un backend Cloud Run Functions deve avere assegnato il ruolo Cloud Run Invoker.
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.
Nella sezione Dettagli gateway:
1. Inserisci il nome visualizzato del gateway. L'URL del gateway viene generato automaticamente.
2. Seleziona la posizione del gateway dal menu a discesa.
3. (Facoltativo) Aggiungi etichette al gateway utilizzando un formato chiave:valore. Per aggiungere più di un'etichetta, fai clic su Aggiungi etichetta e inserisci altri valori.
Fai clic su Crea gateway.

In questo modo viene eseguito 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 del processo di creazione e deployment, fai clic sull'icona Notifica nella barra di navigazione principale per visualizzare una notifica di stato, come mostrato nell'immagine seguente:

Pannello delle notifiche per le notifiche di stato

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

Vai ad API Gateway

Prendi nota dell'URL del gateway. Lo utilizzerai per testare la distribuzione nel passaggio successivo.

Testa 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 con una chiave API:

Crea una chiave API associata al tuo progetto.
Crea ed esegui il deployment di una nuova configurazione API per proteggere l'accesso all'API utilizzando le chiavi API.
Testare la chiave API

Vedi anche Limitare l'accesso API con le chiavi API.

Crea una chiave API

Se non hai ancora una chiave API associata al progetto Google Cloud che utilizzi in questa guida rapida, aggiungine una come descritto in Creazione di una chiave API.

Copia la stringa della chiave restituita e mantienila al sicuro. Questo è il valore della chiave che utilizzerai per testare la chiave API.

Crea e distribuisci una nuova configurazione API

Per creare e implementare una nuova configurazione API che protegga l'accesso API utilizzando le chiavi API:

Attiva il servizio:
1. Nella console Google Cloud , vai ad 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 la tua API nella home page delle API. Ad esempio:
```
my-api-123abc456def1.apigateway.my-project.cloud.goog
```
3. Nella pagina di destinazione del servizio, fai clic su Attiva.
  Nota: potrebbe verificarsi un ritardo di 30 minuti o più tra il momento in cui crei l'API e il momento in cui viene visualizzata nella libreria. Se l'API non è visibile nella libreria, puoi abilitarla utilizzando lo strumento a riga di comando gcloud. Inserisci questo comando, dove MANAGED_SERVICE_NAME specifica il nome del servizio gestito della tua API:
```
gcloud services enable MANAGED_SERVICE_NAME
```

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 securitySchemes come mostrato di seguito:

OpenAPI 2.0

  # 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: SERVICE_URL/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 trasmessa come parametro di query denominato key quando viene richiesto l'accesso a tutti i percorsi definiti nella specifica.

OpenAPI 3.x

# openapi-functions.yaml
openapi: 3.0.4
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
# Define reusable components in x-google-api-management
x-google-api-management:
  backends:
    functions_backend:
      address: SERVICE_URL/helloGET
      pathTranslation: APPEND_PATH_TO_ADDRESS
      protocol: "http/1.1"
# Apply the backend configuration by referencing it by name. Set at the root so this applies to all operations unless overridden.
x-google-backend: functions_backend
components:
# This section configures basic authentication with an API key.
  securitySchemes:
    google_api_key:
      type: apiKey
      name: x-api-key
      in: header
security:
  - google_api_key: []
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: string

securitySchemes configura l'API in modo che richieda una chiave API trasmessa come parametro di query denominato key quando viene richiesto l'accesso a tutti i percorsi definiti nella specifica.

Crea ed esegui il deployment di una nuova configurazione API sul gateway esistente:
1. Vai alla pagina di destinazione dei gateway.
  
  Vai ad API 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 viene 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.

Testare la 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

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 il valore della chiave API che hai creato in Crea 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 API Gateway. Ora puoi iniziare l'onboarding di nuovi client API generando ulteriori chiavi API.

Monitorare l'attività dell'API

Visualizza i grafici delle attività per la tua API nella pagina API Gateway della consoleGoogle Cloud . Fai clic sull'API per visualizzare i grafici delle attività nella pagina Panoramica. La visualizzazione dei dati relativi alle richieste nei grafici può richiedere alcuni minuti.
Esamina i log delle richieste per la tua API nella pagina Esplora log. Un link alla pagina Esplora log è disponibile nella pagina API API Gateway della consoleGoogle Cloud .

Vai ad API Gateway

Una volta nella pagina delle API API Gateway:
1. Seleziona l'API da visualizzare.
2. Fai clic sulla scheda Dettagli.
3. Fai clic sul link nella sezione Log.

Esegui la pulizia

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

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

Passaggi successivi

Scopri di più su API Gateway
Consulta la sezione Configurare l'ambiente di sviluppo