Questa pagina è stata tradotta dall'API Cloud Translation.

Guida rapida: proteggi il traffico verso un servizio con gcloud CLI

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

Segui questi passaggi per eseguire il deployment di una nuova API per accedere a un servizio di backend su Cloud Run Functions utilizzando Google Cloud CLI. 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 Dashboard e seleziona o crea un progetto Google Cloud .
Vai alla Dashboard

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.
Verifica che la fatturazione sia attivata per il tuo progetto.
Abilita fatturazione
Verifica che Google Cloud CLI sia scaricata e installata sulla tua macchina.
Scarica gcloud CLI
Aggiorna i componenti di gcloud:
```
gcloud components update
```
Imposta il progetto predefinito. Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud .
```
gcloud config set project PROJECT_ID
```

Attivare i servizi richiesti

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

Utilizza i seguenti comandi per abilitare questi servizi:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Per saperne di più sui servizi gcloud, consulta Servizi gcloud.

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 seguente funzione:

/**
 * 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 di esempio di Cloud Run Functions ed eseguire il deployment del servizio di backend di Cloud Run Function.

Crea un'API

Ora tutto è pronto per la creazione dell'API su API Gateway.

Inserisci il seguente comando, dove:
- API_ID specifica il nome dell'API. Per le linee guida per la denominazione delle API, consulta Requisiti per l'ID API.
```
gcloud api-gateway apis create API_ID 
```
Ad esempio:
```
gcloud api-gateway apis create my-api
```

Al termine, puoi utilizzare questo comando per visualizzare i dettagli della nuova API:

gcloud api-gateway apis describe API_ID

Ad esempio:

gcloud api-gateway apis describe my-api

Questo comando restituisce quanto segue:

  createTime: '2020-02-29T21:52:20.297426875Z'
  displayName: my-api
  managedService: my-api-123abc456def1.apigateway.my-project.cloud.goog
  name: projects/my-project/locations/global/apis/my-api
  state: ACTIVE
  updateTime: '2020-02-29T21:52:20.647923711Z'

Prendi nota del valore della proprietà managedService. Questo valore viene utilizzato per abilitare l'API in un passaggio successivo.

Crea una configurazione API

Prima di poter utilizzare API Gateway per gestire il traffico verso il backend dell'API di cui hai eseguito il deployment, è necessaria una configurazione API.

Puoi creare una configurazione API utilizzando una descrizione OpenAPI che contiene annotazioni specializzate per definire il comportamento scelto di API Gateway. Per maggiori dettagli sulle estensioni OpenAPI supportate, vedi quanto segue:

La descrizione OpenAPI utilizzata per questa guida rapida contiene istruzioni di routing al backend della nostra 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: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/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:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/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

Per caricare questa descrizione OpenAPI e creare una configurazione API utilizzando gcloud CLI:

Dalla riga di comando, crea un nuovo file denominato openapi-functions.yaml.
Copia e incolla i contenuti della descrizione OpenAPI nel file appena creato.
Modifica il file come segue:
1. Nel campo title, sostituisci API_ID con il nome della tua API 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.
2. Nel campo address, sostituisci GATEWAY_LOCATION con la regione Google Cloud della funzione di cui è stato eseguito il deployment e PROJECT_ID con il nome del tuo progetto Google Cloud .
Inserisci il seguente comando, dove:
- CONFIG_ID specifica il nome della configurazione API.
- API_ID specifica il nome dell'API.
- API_DEFINITION specifica il nome del file della specifica OpenAPI.
- SERVICE_ACCOUNT_EMAIL specifica il account di servizio utilizzato per firmare i token per i backend con l'autenticazione configurata. Per ulteriori informazioni, vedi Configurazione di un service account.
  Nota: il account di servizio utilizzato per creare una configurazione API per un backend Cloud Run Functions deve avere il ruolo cloudfunctions.invoker assegnato.
```
gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
   --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
Ad esempio:
```
gcloud api-gateway api-configs create my-config \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --backend-auth-service-account=0000000000000-compute@developer.gserviceaccount.com
```
Il completamento di questa operazione potrebbe richiedere diversi minuti, poiché la configurazione dell'API viene propagata ai sistemi downstream. La creazione di una configurazione API complessa potrebbe richiedere fino a 10 minuti.

Nota: se esegui questo comando e ricevi un errore nel formato FAILED_PRECONDITION: Service Account ... does not exist, consulta Configurazione di un service account per verificare che un account di servizio sia abilitato per il tuo progetto.
Nota: per una determinata API può essere creata una sola configurazione API alla volta. Attendi il completamento della creazione della configurazione prima di tentare di crearne una nuova per la stessa API.

Una volta creata la configurazione API, puoi visualizzarne i dettagli eseguendo questo comando:

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID

Ad esempio:

gcloud api-gateway api-configs describe my-config \
  --api=my-api

L'output mostra i dettagli della configurazione API, tra cui nome e stato, come mostrato nel seguente esempio:

createTime: '2020-02-07T18:17:01.839180746Z'
displayName: my-config
gatewayConfig:
backendConfig:
  googleServiceAccount: 0000000000000-compute@developer.gserviceaccount.com
name: projects/my-project/locations/global/apis/my-api/configs/my-config
serviceRollout:
rolloutId: 2020-02-07r0
state: ACTIVE
updateTime: '2020-02-07T18:17:02.173778118Z'

Creazione di un gateway

Ora esegui il deployment della configurazione API su un gateway. Il deployment di una configurazione API su un gateway definisce un URL esterno che i client API possono utilizzare per accedere all'API.

Esegui questo comando per eseguire il deployment della configurazione API appena creata in API Gateway:

gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION

dove:

GATEWAY_ID specifica il nome del gateway.
API_ID specifica il nome dell'API API Gateway associata a questo gateway.
CONFIG_ID specifica il nome della configurazione API di cui è stato eseguito il deployment sul gateway.
GCP_REGION è la regioneGoogle Cloud del gateway di cui è stato eseguito il deployment.
Nota:
i valori consentiti sono:
- asia-northeast1
- australia-southeast1
- europe-west1
- europe-west2
- us-east1
- us-east4
- us-central1
- us-west2
- us-west3
- us-west4
PROJECT_ID specifica il nome del tuo progetto Google Cloud .

Ad esempio:

gcloud api-gateway gateways create my-gateway \
  --api=my-api --api-config=my-config \
  --location=us-central1

Al termine, utilizza questo comando per visualizzare i dettagli del gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION

Ad esempio:

gcloud api-gateway gateways describe my-gateway \
  --location=us-central1

Questo comando restituisce quanto segue:

apiConfig: projects/my-project/locations/global/apis/my-api/configs/my-config
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: my-gateway
name: projects/my-project/locations/us-central1/gateways/my-gateway
serviceAccount:
      email: 0000000000000-compute@developer.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

Prendi nota del valore della proprietà defaultHostname. Questa è la parte del nome host dell'URL del gateway che utilizzerai per testare il deployment nel passaggio successivo.

Testa il deployment dell'API

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

Inserisci questo comando curl, dove:

DEFAULT_HOSTNAME specifica la parte del nome host dell'URL del gateway di cui è stato eseguito il deployment.
hello è il percorso specificato nella configurazione API.

curl https://DEFAULT_HOSTNAME/hello

Ad esempio:

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

L'output è:

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, genera una chiave API associata al progetto e concedi 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 utilizzi in questa guida rapida, puoi aggiungerne una seguendo i passaggi descritti in Creazione di una chiave API.

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

Attiva il supporto delle chiavi API per il tuo servizio. Inserisci il seguente comando, dove:
- MANAGED_SERVICE_NAME specifica il nome del servizio gestito creato durante il deployment dell'API. Puoi visualizzarlo nella proprietà Servizio gestito elencata con il comando gcloud apigee-gateway apis describe.
- PROJECT_ID specifica il nome del tuo progetto Google Cloud .
```
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
```
Ad esempio:
```
gcloud services enable my-api-123abc456def1.apigateway.my-project.cloud.goog
```

Modifica la descrizione 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:

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: https://GATEWAY_LOCATION-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 trasmessa come parametro di ricerca 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:
  backend:
    functions_backend:
      address: https://GATEWAY_LOCATION-PROJECT_ID.cloudfunctions.net/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 una nuova configurazione API con la specifica OpenAPI modificata utilizzando questo comando:

gcloud api-gateway api-configs create NEW_CONFIG_ID \
--api=API_ID --openapi-spec=NEW_API_DEFINITION \
--backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Ad esempio:

gcloud api-gateway api-configs create my-config-key \
  --api=my-api --openapi-spec=openapi2-functions.yaml \
  --project=my-project --backend-auth-service-account=0000000000000compute@developer.gserviceaccount.com

Esegui questo comando per aggiornare il gateway esistente con la nuova configurazione API:

gcloud api-gateway gateways update GATEWAY_ID \
  --api=API_ID --api-config=NEW_CONFIG_ID \
  --location=GCP_REGION

Ad esempio:

gcloud api-gateway gateways update my-gateway \
  --api=my-api --api-config=my-config-key \
  --location=us-central1

Testare la chiave API

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

Inserisci questo comando curl, dove:

DEFAULT_HOSTNAME specifica la parte del nome host dell'URL del gateway di cui è stato eseguito il deployment.
hello è il percorso specificato nella configurazione API.

curl https://DEFAULT_HOSTNAME/hello

Ad esempio:

curl 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 inserisci il seguente comando curl, dove:

DEFAULT_HOSTNAME specifica la parte del nome host dell'URL del gateway di cui è stato eseguito il deployment.
hello è il percorso specificato nella configurazione API.
API_KEY specifica la chiave API creata nel passaggio precedente.

curl https://DEFAULT_HOSTNAME/hello?key=API_KEY

Ora dovresti vedere Hello World! nella risposta dall'API.

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

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
Esamina la sezione Configurazione dell'ambiente di sviluppo.
Scopri di più sull'autenticazione tra servizi