Inizia a utilizzare il Processore delle estensioni Apigee

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come configurare il processore di estensioni Apigee per abilitare l'applicazione dei criteri API per il traffico API utilizzando un bilanciatore del carico abilitato per Service Extensions.

Per scoprire di più sui casi d'uso suggeriti e sui vantaggi dell'utilizzo di Apigee Extension Processor per la gestione delle API, consulta la Panoramica di Apigee Extension Processor.

Il processore di estensioni Apigee è un' estensione del traffico (un tipo di Service Extension) che ti consente di utilizzare Cloud Load Balancing per inviare callout dal percorso di elaborazione dei dati del bilanciatore del carico delle applicazioni al processore di estensioni Apigee. Una volta configurati il bilanciatore del carico e l'estensione del traffico, il traffico API viene elaborato dal bilanciatore del carico. Le policy nel processore di estensioni Apigee vengono applicate al traffico API utilizzando i callout delle estensioni di traffico.

Le sezioni seguenti illustrano i passaggi per configurare gli elementi chiave del processore di estensioni Apigee:

Prima di iniziare

Prima di iniziare a configurare il processore di estensioni Apigee, completa le seguenti attività:

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Apigee, Compute Engine, and Network Services APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

  5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Apigee, Compute Engine, and Network Services APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    8.

  8. Installa Google Cloud CLI.

    Dopo aver installato Google Cloud CLI, esegui il comando gcloud components update per ottenere i componenti gcloud più recenti.

  9. Esegui il provisioning di un'istanza Apigee utilizzando la versione 1-15-0-apigee-2 o successive, se non l'hai ancora fatto.

    Visualizza le versioni dell'istanza nella pagina Dettagli istanza dell'interfaccia utente Apigee nella console Google Cloud . Vai alla pagina Istanze nella console Google Cloud per selezionare un'istanza e visualizzarne i dettagli:

    Vai a Istanze

    Puoi utilizzare Extension Processor con un'organizzazione Apigee con abbonamento o Pay-as-you-go. Se non sai se stai utilizzando un'organizzazione Apigee con abbonamento o con pagamento a consumo, contatta l'amministratore dell'organizzazione Apigee. Per maggiori dettagli sul provisioning delle istanze Apigee a pagamento, vedi Prima di iniziare.

  10. Verifica di aver attivato una rete VPC e una subnet nell'istanza Apigee che prevedi di utilizzare. Vai alla pagina Reti VPC nella console Google Cloud :

    Vai a Reti VPC

    11. Ruoli obbligatori

    Per ottenere le autorizzazioni necessarie per installare il processore di estensioni Apigee, chiedi all'amministratore di concederti i seguenti ruoli IAM:

    Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

    Imposta le variabili di ambiente

    Nel progetto Google Cloud che contiene l'istanza Apigee, utilizza il seguente comando per impostare le variabili di ambiente: 

    export PROJECT_ID=PROJECT_ID
export ORG_NAME=$PROJECT_ID
export REGION=REGION
export INSTANCE=INSTANCE
export VPC_NETWORK_NAME=VPC_NETWORK_NAME
export SUBNET=SUBNET

    Dove:

    • PROJECT_ID è l'ID del progetto con la tua istanza Apigee.
    • REGION è la regione Google Cloud dell'istanza Apigee.
    • INSTANCE è il nome della tua istanza Apigee.
    • VPC_NETWORK_NAME è il nome della rete VPC nel tuo progetto Google Cloud che vuoi utilizzare per Apigee Extension Processor.
    • SUBNET è il nome della subnet nel tuo progetto Google Cloud che vuoi utilizzare per il processore di estensioni Apigee.

    Per verificare che le variabili di ambiente siano impostate correttamente, esegui il comando seguente ed esamina l'output: 

    echo $PROJECT_ID $ORG_NAME $REGION $INSTANCE $VPC_NETWORK_NAME $SUBNET

    Configura un token di autenticazione

    Per configurare un token di autenticazione, esegui questo comando: 

    export TOKEN=$(gcloud auth print-access-token)
echo $TOKEN

    Configura un bilanciatore del carico per un servizio di backend

    Le sezioni seguenti descrivono i passaggi per configurare un bilanciatore del carico delle applicazioni esterno globale per un servizio di backend utilizzando httpbin.org come esempio:

    1. Crea un bilanciatore del carico delle applicazioni esterno globale.
    2. Crea un gruppo di endpoint di rete (NEG).
    3. Crea un servizio di backend.
    4. Crea una mappa URL.
    5. Crea un proxy di destinazione.
    6. Crea una regola di forwarding globale.

    Crea un bilanciatore del carico delle applicazioni esterno globale

    Per creare il bilanciatore del carico:

    1. Imposta la configurazione di gcloud in modo da utilizzare il progetto corrente: 
      gcloud config set project PROJECT_ID

      Dove PROJECT_ID è l'ID del progetto con la tua istanza Apigee.

    2. Crea un indirizzo IP statico globale: 
      gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global

      dove IP_ADDRESS è il nome dell'indirizzo IP che vuoi creare. Il nome deve corrispondere all'espressione regolare (?:a-z?).

    3. Ottieni l'indirizzo IP e salvalo come variabile di ambiente: 
      IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)

      Dove IP_ADDRESS è il nome dell'indirizzo IP creato nel passaggio precedente.

    4. Crea un certificato TLS per nip.io, un servizio di terze parti che fornisce record DNS jolly per gli indirizzi IP: 
      gcloud compute ssl-certificates create SSL_CERT_NAME \
  --domains="nip.io"

      dove SSL_CERT_NAME è il nome del certificato che vuoi creare.

    Crea un gruppo di endpoint di rete (NEG)

    Per creare il gruppo di endpoint di rete (NEG) per il bilanciatore del carico:

    1. Crea un NEG: 
      gcloud compute network-endpoint-groups create NEG_NAME \
  --network-endpoint-type=INTERNET_FQDN_PORT \
  --default-port=443 \
  --global

      dove NEG_NAME è il nome del NEG che vuoi creare.

    2. Aggiungi l'endpoint per httpbin.org al NEG: 
      gcloud compute network-endpoint-groups update NEG_NAME \
  --add-endpoint=fqdn=httpbin.org,port=443 \
  --global

      Dove NEG_NAME è il nome del NEG creato nel passaggio precedente.

    Crea un servizio di backend

    Per creare il servizio di backend esposto dal bilanciatore del carico:

    1. Crea il servizio di backend: 
      gcloud compute backend-services create BACKEND_SERVICE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --protocol=HTTPS \
  --global

      Sostituisci BACKEND_SERVICE_NAME con il nome del servizio di backend che vuoi creare.

    2. Aggiungi il NEG al backend: 
      gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
  --network-endpoint-group=NEG_NAME \
  --global-network-endpoint-group \
  --global

      Dove:

      • BACKEND_SERVICE_NAME è il nome del servizio di backend che hai creato nel passaggio precedente.
      • NEG_NAME è il nome del NEG che hai creato in un passaggio precedente.

    Crea una mappa URL

    Per creare una mappa URL tra il bilanciatore del carico e il servizio di backend, utilizza questo comando: 

    gcloud compute url-maps create URL_MAP_NAME \
  --default-service BACKEND_SERVICE_NAME \
  --global

    Dove:

    • URL_MAP_NAME è il nome della mappa URL che vuoi creare.
    • BACKEND_SERVICE_NAME è il nome del servizio di backend che hai creato in un passaggio precedente.

    Crea un proxy di destinazione

    Per creare un proxy di destinazione per il bilanciatore del carico in modo che elabori il traffico dell'estensione di servizio, utilizza questo comando: 

    gcloud compute target-https-proxies create TARGET_PROXY_NAME \
  --global \
  --ssl-certificates SSL_CERT_NAME \
  --global-ssl-certificates \
  --url-map URL_MAP_NAME \
  --global-url-map

    Dove:

    • TARGET_PROXY_NAME è il nome del proxy di destinazione che vuoi creare.
    • URL_MAP_NAME è il nome della mappa URL che hai creato in un passaggio precedente.
    • SSL_CERT_NAME è il nome del certificato SSL creato per nip.io in un passaggio precedente.

    Crea una regola di forwarding globale

    Per creare una regola di forwarding globale per il bilanciatore del carico, utilizza il seguente comando: 

    gcloud compute forwarding-rules create FORWARDING_RULE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --network-tier=PREMIUM \
  --address=IP_ADDRESS \
  --target-https-proxy=TARGET_PROXY_NAME \
  --ports=443 \
  --global

    Dove:

    • FORWARDING_RULE_NAME è il nome della regola di forwarding che vuoi creare.
    • IP_ADDRESS è il nome dell'indirizzo IP dell'endpoint NEG creato in un passaggio precedente.
    • TARGET_PROXY_NAME è il nome del proxy di destinazione che elabora il traffico delle estensioni.

    Configura il processore di estensioni Apigee

    Le sezioni seguenti descrivono i passaggi per configurare il processore di estensioni Apigee:

    1. Crea un ambiente Apigee.
    2. Crea il proxy del processore di estensioni.

    Crea un ambiente Apigee

    1. Crea un ambiente Apigee utilizzando il seguente comando: 
      curl -i -X POST -H  "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments" -H "Content-Type:application/json" -d \
    '{
        "name": "ENV_NAME",
        "displayName": "ENV_NAME",
        "state": "ACTIVE",
        "deploymentType": "PROXY",
        "apiProxyType": "PROGRAMMABLE",
        "type": "COMPREHENSIVE",
        "properties":
        {"property": [
            {
            "name": "apigee-service-extension-enabled",
            "value": "true"
            }
          ]
        }
    }'

      dove ENV_NAME è il nome dell'ambiente che stai creando. Il nome deve contenere tra 2 e 32 caratteri che possono essere lettere minuscole, numeri o trattini. Il nome deve iniziare con una lettera e non può terminare con un trattino. Il nome deve essere diverso da qualsiasi altro nome di ambiente nella tua organizzazione.

      Verifica che l'ambiente sia stato creato: 

      curl -i -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/environments"

      L'elenco degli ambienti dovrebbe includere quello che hai appena creato.

    2. Collega l'ambiente appena creato alla tua istanza Apigee: 
      curl -i -X POST -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances/$INSTANCE/attachments" -H "Content-Type:application/json" -d \
    '{
        "environment": "ENV_NAME"
        }'

      Dove ENV_NAME è il nome dell'ambiente creato nel passaggio precedente.

      Questa operazione potrebbe richiedere fino a 10 minuti.

    3. Crea il gruppo di ambienti Apigee: 
      curl -H "Authorization: Bearer $TOKEN" -X POST \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups" -H "Content-Type:application/json" -d \
    '{
        "name": "ENV_GROUP_NAME",
        "hostnames": ["ENV_GROUP_HOSTNAME"]
        }'

      Dove:

      • ENV_GROUP_NAME è il nome del gruppo di ambienti che stai creando.
      • ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti che stai creando. Il nome host deve essere un nome di dominio completo (FQDN).
    4. Collega il nuovo ambiente al nuovo gruppo di ambienti: 
      curl -H "Authorization: Bearer $TOKEN" -X POST\
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/envgroups/ENV_GROUP_NAME/attachments" -H "content-type:application/json" -d \
        '{
            "name": "ENV_GROUP_NAME",
            "environment": "ENV_NAME"
        }'

      Dove:

      • ENV_GROUP_NAME è il nome del gruppo di ambienti che stai creando.
      • ENV_NAME è il nome dell'ambiente che hai creato in un passaggio precedente.

    Crea il proxy del processore di estensione

    Il proxy del processore di estensioni è un proxy API Apigee utilizzato per applicare le norme di gestione delle API al traffico del bilanciatore del carico. Puoi creare un proxy senza target o un proxy abilitato per Server-Sent Events (SSE). Per saperne di più sull'utilizzo di SSE con Apigee, consulta Server-Sent Events.

    Per creare un proxy API Apigee da utilizzare con il bilanciatore del carico del processore di estensione:

    Nessun proxy di destinazione

    1. Segui i passaggi descritti in Creazione di un proxy API per creare un proxy Nessun target con le seguenti specifiche:
      • Modello proxy: seleziona Nessun target.
      • Nome proxy: inserisci un nome proxy. Questo nome fungerà da identificatore per il processore di estensioni.
      • Percorso di base: imposta il percorso di base che preferisci. Il percorso non verrà utilizzato.

      La specifica XML per il proxy dovrebbe essere simile alla seguente: 

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APIProxy revision="1" name="extproc-sample">
    <DisplayName/>
    <Description/>
    <CreatedAt>1739581781912</CreatedAt>
    <LastModifiedAt>1739582447868</LastModifiedAt>
    <BasePaths>/</BasePaths>
    <Policies></Policies>
    <ProxyEndpoints>
        <ProxyEndpoint>default</ProxyEndpoint>
    </ProxyEndpoints>
</APIProxy>
    2. Segui i passaggi descritti in Eseguire il deployment di un proxy API per eseguire il deployment del proxy nell'ambiente creato in precedenza.

    Proxy abilitato per SSE

    1. Segui i passaggi descritti in Creazione di un proxy API per creare un proxy Server-sent event con le seguenti specifiche:
      • Modello proxy: seleziona Nessun target.
      • Nome proxy: inserisci un nome proxy.
      • Percorso di base: imposta il percorso di base che preferisci. Il percorso non verrà utilizzato.

      La specifica XML per il proxy dovrebbe essere simile alla seguente: 

      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APIProxy revision="1" name="extproc-sample">
    <DisplayName/>
    <Description/>
    <CreatedAt>1739581781912</CreatedAt>
    <LastModifiedAt>1739582447868</LastModifiedAt>
    <BasePaths>/</BasePaths>
    <ProxyEndpoints>
        <ProxyEndpoint>default</ProxyEndpoint>
    </ProxyEndpoints>
</APIProxy>
    2. Configura EventFlow nel proxy: 
      <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<APIProxy revision="1" name="extproc-sample">
    <DisplayName/>
    <Description/>
    <CreatedAt>1739581781912</CreatedAt>
    <LastModifiedAt>1739582447868</LastModifiedAt>
    <BasePaths>/</BasePaths>
    <ProxyEndpoints>
        <ProxyEndpoint>default</ProxyEndpoint>
        <EventFlow name="EventFlow" content-type="text/event-stream">
          <Response/>
        </EventFlow>
        <HTTPProxyConnection>
          <Properties/>
          <URL>https://httpbin.org/sse</URL>
        </HTTPProxyConnection>
    </ProxyEndpoints>
</APIProxy>
    3. Segui i passaggi descritti in Eseguire il deployment di un proxy API per eseguire il deployment del proxy nell'ambiente creato in precedenza.

    Configurare l'estensione del traffico

    Questa sezione descrive come configurare l'estensione di servizio di gestione del traffico per Extension Processor utilizzando i seguenti passaggi:

    1. Crea l'estensione del traffico con l'API di provisioning del processore di estensioni.
    2. Invia una richiesta al bilanciatore del carico.

    Crea l'estensione del traffico con l'API di provisioning del processore di estensioni

    In questo passaggio, crea un'estensione del servizio di gestione del traffico per il tuo processore di estensioni utilizzando l'API di provisioning del processore di estensioni.

    Crea l'estensione del traffico utilizzando il seguente comando per chiamare l'API di provisioning del processore di estensioni: 

    curl -X POST -H  "Authorization: Bearer $TOKEN" \
    https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions?apimServiceExtensionId=TRAFFIC_EXT_NAME \
    -H "Content-Type:application/json" -d \
    '{
      "extensionProcessor": "TARGET_PROXY_NAME"
      "lbForwardingRule": "LB_FORWARDING_RULE",
      "network" : "NETWORK",
      "networkConfigs": [
        {
          "region": "$REGION",
          "subnet": "project/my-project/regions/$REGION/subnetworks/$SUBNET"
        }
      ],
      "extensions": [
        {
          "name": "TARGET_PROXY_NAME",
          "matchCondition": "CEL_EXPRESSION",
          "failOpen": FAIL_OPEN,
          "hostname": "ENV_GROUP_HOSTNAME",
          "supportedEvents": [
            "REQUEST_HEADERS",
            "RESPONSE_HEADERS"
          ]
        }
      ]
    }'

    Dove:

    • TRAFFIC_EXT_NAME è il nome dell'estensione del traffico che stai creando.
    • LB_FORWARDING_RULE è il nome della regola di forwarding che hai creato in un passaggio precedente.
    • NETWORK è il nome della rete che hai creato in un passaggio precedente.
    • TARGET_PROXY_NAME è il nome del proxy che elabora il traffico delle estensioni.
    • CEL_EXPRESSION è l'espressione Common Expression Language (CEL) che vuoi utilizzare per l'estensione del traffico. Per ulteriori informazioni sulla sintassi CEL, consulta il riferimento al linguaggio del matcher CEL.
    • FAIL_OPEN è un valore booleano che determina se l'estensione del traffico si apre o si chiude. I valori validi sono true o false.
    • ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti che hai creato in un passaggio precedente.

    Il completamento dell'operazione potrebbe richiedere alcuni minuti.

    Visualizzare i dettagli dell'estensione traffico

    Per verificare che l'estensione del servizio di gestione del traffico sia stata creata correttamente, utilizza questo comando: 

    curl -H "Authorization: Bearer $TOKEN" \
    "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME"

    Sostituisci TRAFFIC_EXT_NAME con il nome dell'estensione del traffico che hai appena creato.

    La risposta è simile alla seguente: 

    {
  "name": "my-traffic-extension",
  "extensionProcessor": "my-extension-processor",
  "lbForwardingRule": "https://www.googleapis.com/compute/v1/projects/my-project/global/forwardingRules/my-forwarding-rule",
  "network": "projects/my-project/global/networks/my-network",
  "networkConfigs": [
    {
      "region": "us-west1",
      "subnet": "projects/my-project/regions/us-west1/subnetworks/my-subnet"
    }
  ],
  "extensions": [
    {
      "name": "organizations/my-org/apis/my-api-proxy",
      "matchCondition": "request.url.contains('1234567890')",
      "failOpen": true,
      "hostname": "my-hostname.apigee.net",
      "supportedEvents": [
        "REQUEST_HEADERS",
        "RESPONSE_HEADERS"
      ]
    }
  ]
}

    Aggiorna un'estensione del traffico

    Puoi aggiornare l'estensione del traffico utilizzando il parametro updateMask. Quando utilizzi il parametro updateMask, devi specificare gli attributi della risorsa che vuoi aggiornare fornendo un elenco separato da virgole. Gli attributi supportati per updateMask sono:

    • networkConfigs: aggiornamenti ai campi region e subnet.
    • extensions: aggiorna i campi name, matchCondition, failOpen, hostname e supportedEvents.
    • extensionProcessor: aggiorna il campo extensionProcessor.

    Per aggiornare un'estensione del traffico, utilizza il comando curl con il metodo PATCH. Puoi aggiornare più attributi includendoli nel parametro di query updateMask come stringa separata da virgole (ad es. ?updateMask=extensions,extensionProcessor).

    Ecco alcuni esempi:

    Aggiorna networkConfigs (bilanciatore del carico globale)

    Per aggiornare gli attributi networkConfigs, utilizza il comando seguente:

    curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=networkConfigs \
  -H "Content-Type:application/json" -d \
  '{
    "networkConfigs": [
      {
        "region": "REGION",
        "subnet": "projects/$PROJECT/regions/REGION/subnetworks/SUBNET"
      }
    ]
  }'

    Dove:

    • TRAFFIC_EXT_NAME è il nome dell'estensione del traffico del processore di estensioni da aggiornare.
    • REGION è la regione della regione aggiornata.
    • SUBNET è la nuova subnet della rete.

    Aggiorna extensions

    Per aggiornare gli attributi extensions, utilizza il comando seguente:

    curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ]
  }'

    Dove:

    • TRAFFIC_EXT_NAME è il nome dell'estensione del traffico del processore di estensioni da aggiornare.
    • TARGET_PROXY_NAME è il nome del proxy che elabora il traffico delle estensioni.
    • NEW_CEL_EXPRESSION è l'espressione CEL aggiornata.
    • NEW_FAIL_OPEN è il valore booleano aggiornato per l'apertura in caso di errore.
    • NEW_ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti.

    Aggiorna extensionProcessor

    Per aggiornare gli attributi extensionProcessor, utilizza il comando seguente:

    curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

    Dove:

    • TRAFFIC_EXT_NAME è il nome dell'estensione del traffico del processore di estensioni da aggiornare.
    • NEW_TARGET_PROXY_NAME è il nuovo nome del proxy che elabora il traffico delle estensioni.

    Aggiorna più attributi (bilanciamento del carico globale)

    Per aggiornare contemporaneamente gli attributi extensions e extensionProcessor, utilizza il seguente comando:

    curl -X PATCH -H  "Authorization: Bearer $TOKEN" \
  https://apigee.googleapis.com/v1/organizations/$ORG_NAME/apimServiceExtensions/TRAFFIC_EXT_NAME?updateMask=extensions,extensionProcessor \
  -H "Content-Type:application/json" -d \
  '{
    "extensions": [
      {
        "name": "TARGET_PROXY_NAME",
        "matchCondition": "NEW_CEL_EXPRESSION",
        "failOpen": NEW_FAIL_OPEN,
        "hostname": "NEW_ENV_GROUP_HOSTNAME",
        "supportedEvents": [
          "REQUEST_HEADERS",
          "RESPONSE_HEADERS"
        ]
      }
    ],
    "extensionProcessor": "NEW_TARGET_PROXY_NAME"
  }'

    Dove:

    • TRAFFIC_EXT_NAME è il nome dell'estensione del traffico del processore di estensioni da aggiornare.
    • TARGET_PROXY_NAME è il nome del proxy che elabora il traffico delle estensioni.
    • NEW_CEL_EXPRESSION è l'espressione CEL aggiornata.
    • NEW_FAIL_OPEN è il valore booleano aggiornato per l'apertura in caso di errore.
    • NEW_ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti.
    • NEW_TARGET_PROXY_NAME è il nuovo nome del proxy che elabora il traffico delle estensioni.

    Invia una richiesta al bilanciatore del carico

    Per testare la configurazione del bilanciatore del carico e del processore delle estensioni, invia una richiesta al bilanciatore del carico: 

    curl "https://LB_DOMAIN_NAME/get"

    dove LB_DOMAIN_NAME è il nome di dominio che hai utilizzato per il bilanciatore del carico e il certificato SSL. Se hai utilizzato nip.io, il nome di dominio sarà simile a IP_ADDRESS.nip.io.

    La risposta è simile alla seguente: 

    {"status": 200,
  {
    "args": {},
    "headers": {
      ...
    },
    "origin": "173.93.50.108",
    "url": "https://httpbin.org/get"
  }
}

    Utilizzare i criteri con Extension Processor

    Questa sezione descrive come utilizzare i criteri con Extension Processor.

    In questo esempio, configura un criterio VerifyAPIKey e AssignMessage per il processore di estensioni. Queste norme convalidano le chiavi API incluse nelle richieste ad Apigee e inseriscono un token Google nelle intestazioni delle richieste per le chiamate a un servizio di backend. Questo scenario sarebbe utile per i fornitori di API che utilizzano il processore di estensioni Apigee per autorizzare e autenticare le richieste ai propri servizi Apigee e inserire senza problemi i token di autenticazioneGoogle richiesti per un servizio di backend come Vertex AI.

    Aggiungere il criterio VerifyAPIKey per la convalida delle chiavi API

    Le sezioni seguenti descrivono come utilizzare il criterio VerifyAPIKey per convalidare le chiavi API per le chiamate al servizio di backend utilizzando Extension Processor:

    1. Allega la policy VerifyAPIKey al processore di estensioni.
    2. Crea un prodotto API.
    3. Crea un'app sviluppatore e le relative credenziali.
    4. Invia una richiesta al bilanciatore del carico utilizzando la chiave API.

    Collega il criterio VerifyAPIKey al proxy

    Per collegare una policy VerifyAPIKey al proxy del processore di estensioni:

    1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

      Vai a Proxy API

    2. Seleziona il proxy del processore di estensione che hai creato nella sezione Crea un processore di estensione.
    3. Fai clic sulla scheda Sviluppa.
    4. Nel riquadro di navigazione, fai clic su nella sezione Policy.
    5. Nella finestra di dialogo Crea policy, seleziona VerifyAPIKey dall'elenco delle policy.
    6. Nel riquadro VerifyAPIKey, compila i campi obbligatori nelle sezioni Name (Nome) e Display name (Nome visualizzato) utilizzando i seguenti valori:
      • Nome: inserisci un nome per la policy. Ad esempio, VA-verify-api-key.
      • Nome visualizzato: inserisci il nome della policy da utilizzare nell'interfaccia utente. Ad esempio, VA-verify-api-key.
    7. Fai clic su Crea.

      La specifica XML per il criterio VerifyAPIKey incluso nel proxy del processore di estensioni dovrebbe essere simile alla seguente: 

        <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <VerifyAPIKey continueOnError="false" enabled="true" name="VA-verify-api-key">
    <DisplayName>VA-verify-api-key</DisplayName>
    <Properties/>
    <APIKey ref="request.queryparam.x-api-key"/>
  </VerifyAPIKey>
    8. Esegui il deployment della nuova revisione del proxy.

    Crea un prodotto API

    Per creare un prodotto API e configurare il set di operazioni API per il tuo servizio:

    1. Segui i passaggi descritti in Creazione di un prodotto API per creare un prodotto API per il tuo servizio. Puoi configurare i dettagli del prodotto per il prodotto API come preferisci.
    2. Segui i passaggi descritti in Operazioni per aggiungere un insieme di operazioni API al prodotto API, in base alle seguenti specifiche:
      • Fonte:

        Nella console Google Cloud , vai alla pagina Distribuzione > Prodotti API.

        Vai a Prodotti API

        Seleziona il prodotto API che hai creato in un passaggio precedente.
      • Operazione: fai clic su Modifica e configura i seguenti percorsi e metodi:
        • Percorso: /get con metodo: GET
        • Percorso: /TARGET_PROXY_NAME con metodo: GET

          TARGET_PROXY_NAME è il nome del proxy che elabora il traffico delle estensioni.

    Creare un'app sviluppatore e le relative credenziali

    Per creare un'app sviluppatore e le relative credenziali per il prodotto API appena creato:

    1. Vai alla pagina Gestione API Apigee nella console Google Cloud :

      Gestione delle API Apigee

    2. Crea uno sviluppatore:
      1. Seleziona Distribuzione > Sviluppatori.
      2. Nella pagina Sviluppatori, fai clic su + Crea.
      3. Nella pagina Aggiungi sviluppatore, compila i campi obbligatori utilizzando i valori che preferisci.
      4. Fai clic su Aggiungi.
    3. Crea un'app:
      1. Seleziona Distribuzione> App.
      2. Nella pagina App, fai clic su + Crea.
      3. Nella pagina Crea app, compila i campi obbligatori nella sezione Dettagli app utilizzando i seguenti valori:
        • Nome app: inserisci un nome per l'app. Ad esempio, ext-proc-app
        • Sviluppatore: seleziona lo sviluppatore che hai creato nel passaggio precedente o un altro sviluppatore dall'elenco.
      4. Nella sezione Credenziali app, fai clic su + Aggiungi credenziale.
      5. Nella sezione Credenziali, seleziona Mai dalla casella di riepilogo Scadenza.
      6. Nella sezione Prodotti, fai clic su + Aggiungi prodotti per visualizzare il riquadro Aggiungi prodotti.
      7. Seleziona il prodotto API che hai creato nel passaggio precedente.
      8. Fai clic su OK.
      9. Fai clic su Aggiungi per chiudere il riquadro Aggiungi prodotti.
      10. Fai clic su Crea.
    4. Nella pagina Dettagli app, nella sezione Credenziali, fai clic su per visualizzare il valore della chiave.

      Copia il valore di Key. Utilizzerai questa chiave per effettuare chiamate API al tuo servizio in un passaggio successivo.

    5. Nella pagina Dettagli app, nella sezione Credenziali, fai clic su per visualizzare il valore del secret dell'app.

    Invia una richiesta al bilanciatore del carico utilizzando la chiave API

    Per testare la convalida della chiave API, invia una richiesta al bilanciatore del carico utilizzando la chiave API: 

    curl "https://LB_DOMAIN_NAME/get"

    dove LB_DOMAIN_NAME è il nome di dominio che hai utilizzato per il bilanciatore del carico e il certificato SSL.

    La risposta non va a buon fine senza una chiave API.

    Invia un'altra richiesta al bilanciatore del carico, utilizzando la chiave API nella richiesta: 

    curl "https://LB_DOMAIN_NAME/get?key=API_KEY"

    Dove:

    • LB_DOMAIN_NAME è il nome di dominio che hai utilizzato per il bilanciatore del carico e il certificato SSL.
    • API_KEY è la chiave API delle credenziali dell'app per sviluppatori mostrate in un passaggio precedente.

    La risposta indica l'autorizzazione riuscita per l'endpoint. Ciò indica che Extension Processor ha convalidato la chiave API e il proxy Apigee ora può elaborare la richiesta.

    Aggiungi la policy AssignMessage per l'autenticazione Google

    Se vuoi utilizzare il tuo processore di estensioni per fornire la gestione delle API per un servizio autenticato da Google, puoi inserire un token di accesso Google o un token ID Google nelle richieste inviate al servizio di backend utilizzando il criterio AssignMessage.

    Le sezioni seguenti descrivono come utilizzare il criterio AssignMessage per inserire un token di autenticazione Google nelle richieste inviate al servizio di backend utilizzando il processore di estensioni:

    1. Collega la policy AssignMessage al proxy.
    2. Invia una richiesta al bilanciatore del carico per testare l'inserimento del token.

    Collega la policy AssignMessage al proxy

    Per aggiungere la norma AssignMessage al proxy:

    1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

      Vai a Proxy API

    2. Seleziona il proxy del processore di estensione che hai creato nella sezione Crea un processore di estensione.
    3. Fai clic sulla scheda Sviluppa.
    4. Nel riquadro di navigazione, fai clic su nella sezione Policy.
    5. Nella finestra di dialogo Crea policy, seleziona AssignMessage dall'elenco delle policy.
    6. Nel riquadro Assegna messaggio, compila i campi obbligatori nelle sezioni Nome e Nome visualizzato utilizzando i seguenti valori:
      • Nome: inserisci un nome per la policy. Ad esempio, AM-auth.
      • Nome visualizzato: inserisci un nome della policy da visualizzare nell'interfaccia utente. Ad esempio, AM-auth.
    7. Fai clic su Crea.
    8. Nell'elemento <Set>, aggiungi i seguenti elementi secondari: 
      <Set>
    <Authentication>
    <HeaderName>Authorization</HeaderName>
    <GoogleAccessToken>
        <Scopes>
        <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
    </GoogleAccessToken>
    </Authentication>
</Set>
    9. Fai clic su Salva.
    10. Esegui il deployment della nuova revisione utilizzando un Google service account.

    Il account di servizio genera Google token di accesso e li inserisce nell'intestazione della richiesta per le chiamate API ai Google servizi di backend.

    Invia una richiesta al bilanciatore del carico per testare l'inserimento del token

    Per verificare che l'inserimento del token funzioni, invia una richiesta al bilanciatore del carico: 

    curl "https://LB_DOMAIN_NAME/get"

    dove LB_DOMAIN_NAME è il nome di dominio che hai utilizzato per il bilanciatore del carico e il certificato SSL.

    La risposta è simile alla seguente: 

    {
  ...
  "headers": {
    "Accept": "*/*",
    "Authorization": "Bearer ya29.c.c0ASRK0Gbw03y9cfvxL11DxaRYBQUU18SmUP4Vu63OckHI5cX7wJ4DmGMG2vbDDS69HXJHqMj-lak4tcqOsJGmE65crn2gNuJLanXidwM8",
    "First": "1.0",
    "Host": "apigee-ext-proc-test.apigee.net",
    "Second": "1.0",
    "Sum": "2",
    "User-Agent": "curl/8.7.1",
    "X-Api-Key": "McYcHGR3PTSGLXExvKADwQ1JJeCjgPDUvAakCl0rJKCFaX0Y",
    "X-Cloud-Trace-Context": "0fd3dadc2a3c328fa968d5f5f1434c29/18300783092696918345"
  },
  ...
}

    La risposta mostra l'inserimento riuscito del token di autenticazione Google nell'intestazione della richiesta.

    Con l'applicazione riuscita del criterio AssignMessage, la richiesta riuscita del client (contenente la chiave API) ad Apigee nello scenario di esempio viene ulteriormente modificata per includere un token di autenticazione Google nell'intestazione della richiesta, come richiesto dal servizio di backend autenticato con Google.