Premiers pas avec le processeur d'extension Apigee

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Cette page explique comment configurer le processeur d'extension Apigee pour appliquer les règles d'API au trafic d'API à l'aide d'un équilibreur de charge compatible avec les extensions de service.

Pour en savoir plus sur les cas d'utilisation suggérés et les avantages de l'utilisation d'Apigee Extension Processor pour la gestion des API, consultez Présentation d'Apigee Extension Processor.

Le processeur d'extension Apigee est une extension de trafic (un type d'extension de service) qui vous permet d'utiliser Cloud Load Balancing pour envoyer des appels depuis le chemin de traitement des données de l'équilibreur de charge d'application vers le processeur d'extension Apigee. Une fois l'équilibreur de charge et l'extension de trafic configurés, le trafic d'API est traité par l'équilibreur de charge. Les règles du processeur d'extension Apigee sont appliquées au trafic d'API à l'aide des callouts d'extension de trafic.

Les sections suivantes vous guident dans la configuration des éléments clés du processeur d'extension Apigee :

Avant de commencer

Avant de commencer à configurer l'extension Apigee Extension Processor, effectuez les tâches suivantes :

  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. Installez la Google Cloud CLI.

    Une fois la Google Cloud CLI installée, exécutez la commande gcloud components update pour obtenir les derniers composants gcloud.

  9. Si vous ne l'avez pas déjà fait, provisionnez une instance Apigee à l'aide de la version 1-15-0-apigee-2 ou ultérieure.

    Affichez les versions des instances sur la page Détails de l'instance de l'interface utilisateur Apigee dans la console Google Cloud . Accédez à la page Instances de la console Google Cloud pour sélectionner une instance et afficher ses détails :

    Accéder à la page "Instances"

    Vous pouvez utiliser Extension Processor avec une organisation Apigee avec abonnement ou Pay-as-you-go. Si vous ne savez pas si vous utilisez une organisation Apigee avec abonnement ou en paiement à l'usage, contactez l'administrateur de votre organisation Apigee. Pour en savoir plus sur le provisionnement des instances Apigee payantes, consultez Avant de commencer.

  10. Vérifiez qu'un VPC et un sous-réseau sont activés dans l'instance Apigee que vous prévoyez d'utiliser. Accédez à la page Réseaux VPC dans la console Google Cloud  :

    Accéder aux réseaux VPC

    11. Rôles requis

    Pour obtenir les autorisations nécessaires à l'installation du processeur d'extension Apigee, demandez à votre administrateur de vous accorder les rôles IAM suivants :

    Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

    Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

    Définir des variables d'environnement

    Dans le projet Google Cloud qui contient votre instance Apigee, utilisez la commande suivante pour définir les variables d'environnement : 

    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

    Où :

    • PROJECT_ID est l'ID du projet contenant votre instance Apigee.
    • REGION est la région Google Cloud de votre instance Apigee.
    • INSTANCE est le nom de votre instance Apigee.
    • VPC_NETWORK_NAME est le nom du réseau VPC de votre projet Google Cloud que vous souhaitez utiliser pour le processeur d'extension Apigee.
    • SUBNET correspond au nom du sous-réseau de votre projet Google Cloud que vous souhaitez utiliser pour le processeur d'extension Apigee.

    Pour vérifier que les variables d'environnement sont correctement définies, exécutez la commande suivante et examinez le résultat : 

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

    Configurer un jeton d'authentification

    Pour configurer un jeton d'authentification, exécutez la commande suivante : 

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

    Configurer un équilibreur de charge pour un service de backend

    Les sections suivantes décrivent les étapes à suivre pour configurer un équilibreur de charge d'application externe global pour un service de backend, en utilisant httpbin.org comme exemple :

    1. Créez un équilibreur de charge d'application externe global.
    2. Créez un groupe de points de terminaison du réseau (NEG).
    3. Créez un service de backend.
    4. Créez un mappage d'URL.
    5. Créez un proxy cible.
    6. Créez une règle de transfert globale.

    Créer un équilibreur de charge d'application externe global

    Pour créer l'équilibreur de charge :

    1. Configurez gcloud pour utiliser votre projet actuel : 
      gcloud config set project PROJECT_ID

      Où PROJECT_ID est l'ID du projet avec votre instance Apigee.

    2. Créez une adresse IP statique globale : 
      gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global

      Où IP_ADDRESS correspond au nom de l'adresse IP que vous souhaitez créer. Le nom doit correspondre à l'expression régulière (?:a-z?).

    3. Obtenez l'adresse IP et enregistrez-la en tant que variable d'environnement : 
      IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)

      IP_ADDRESS correspond au nom de l'adresse IP que vous avez créée à l'étape précédente.

    4. Créez un certificat TLS pour nip.io, un service tiers qui fournit des enregistrements DNS génériques pour les adresses IP : 
      gcloud compute ssl-certificates create SSL_CERT_NAME \
  --domains="nip.io"

      où SSL_CERT_NAME est le nom du certificat que vous souhaitez créer.

    Créer un groupe de points de terminaison du réseau (NEG)

    Pour créer le groupe de points de terminaison du réseau (NEG) pour votre équilibreur de charge :

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

      Où NEG_NAME correspond au nom du NEG que vous souhaitez créer.

    2. Ajoutez le point de terminaison pour httpbin.org au NEG : 
      gcloud compute network-endpoint-groups update NEG_NAME \
  --add-endpoint=fqdn=httpbin.org,port=443 \
  --global

      NEG_NAME correspond au nom du NEG que vous avez créé à l'étape précédente.

    Créer un service de backend

    Pour créer le service de backend exposé par l'équilibreur de charge :

    1. Créez le service de backend : 
      gcloud compute backend-services create BACKEND_SERVICE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --protocol=HTTPS \
  --global

      Remplacez BACKEND_SERVICE_NAME par le nom du service de backend que vous souhaitez créer.

    2. Ajoutez le NEG au backend : 
      gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
  --network-endpoint-group=NEG_NAME \
  --global-network-endpoint-group \
  --global

      Où :

      • BACKEND_SERVICE_NAME est le nom du service de backend que vous avez créé à l'étape précédente.
      • NEG_NAME est le nom du NEG que vous avez créé à l'étape précédente.

    Créer un mappage d'URL

    Pour créer un mappage d'URL entre l'équilibreur de charge et le service de backend, utilisez la commande suivante : 

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

    Où :

    • URL_MAP_NAME est le nom du mappage d'URL que vous souhaitez créer.
    • BACKEND_SERVICE_NAME est le nom du service de backend que vous avez créé à une étape précédente.

    Créer un proxy cible

    Pour créer un proxy cible permettant à l'équilibreur de charge de traiter le trafic d'extension de service, utilisez la commande suivante : 

    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

    Où :

    • TARGET_PROXY_NAME est le nom du proxy cible que vous souhaitez créer.
    • URL_MAP_NAME est le nom du mappage d'URL que vous avez créé à l'étape précédente.
    • SSL_CERT_NAME est le nom du certificat SSL que vous avez créé pour nip.io à une étape précédente.

    Créer une règle de transfert globale

    Pour créer une règle de transfert globale pour l'équilibreur de charge, utilisez la commande suivante : 

    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

    Où :

    • FORWARDING_RULE_NAME est le nom de la règle de transfert que vous souhaitez créer.
    • IP_ADDRESS correspond au nom de l'adresse IP du point de terminaison NEG que vous avez créé à l'étape précédente.
    • TARGET_PROXY_NAME est le nom du proxy cible qui traite le trafic des extensions.

    Configurer le processeur d'extension Apigee

    Les sections suivantes décrivent les étapes à suivre pour configurer le processeur d'extension Apigee :

    1. Créez un environnement Apigee.
    2. Créez le proxy du processeur d'extension.

    Créer un environnement Apigee

    1. Créez un environnement Apigee à l'aide de la commande suivante : 
      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"
            }
          ]
        }
    }'

      Où ENV_NAME est le nom de l'environnement que vous créez. Le nom doit contenir entre 2 et 32 caractères, qui peuvent être des lettres minuscules, des chiffres ou des traits d'union. Le nom doit commencer par une lettre et ne peut pas se terminer par un trait d'union. Le nom doit être différent de tout autre nom d'environnement dans votre organisation.

      Vérifiez que l'environnement a été créé : 

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

      La liste des environnements doit inclure celui que vous venez de créer.

    2. Associez l'environnement nouvellement créé à votre instance 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"
        }'

      Où ENV_NAME est le nom de l'environnement que vous avez créé à l'étape précédente.

      Cette opération peut prendre jusqu'à 10 minutes.

    3. Créez le groupe d'environnements 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"]
        }'

      Où :

      • ENV_GROUP_NAME est le nom du groupe d'environnements que vous créez.
      • ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements que vous créez. Le nom d'hôte doit être un nom de domaine complet.
    4. Associez le nouvel environnement au nouveau groupe d'environnements : 
      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"
        }'

      Où :

      • ENV_GROUP_NAME est le nom du groupe d'environnements que vous créez.
      • ENV_NAME est le nom de l'environnement que vous avez créé lors d'une étape précédente.

    Créer le proxy du processeur d'extension

    Le proxy Extension Processor est un proxy d'API Apigee utilisé pour appliquer des règles de gestion des API au trafic de l'équilibreur de charge. Vous pouvez créer un proxy sans cible ou un proxy compatible avec les événements envoyés par le serveur (SSE). Pour en savoir plus sur l'utilisation des événements envoyés par le serveur avec Apigee, consultez Événements envoyés par le serveur.

    Pour créer un proxy d'API Apigee à utiliser avec l'équilibreur de charge Extension Processor :

    Aucun proxy cible

    1. Suivez les étapes décrites dans Créer un proxy d'API pour créer un proxy Aucune cible avec les spécifications suivantes :
      • Modèle de proxy : sélectionnez Aucune cible.
      • Nom du proxy : saisissez un nom de proxy. Ce nom servira d'identifiant pour le processeur d'extension.
      • Chemin de base : définissez le chemin de base de votre choix. Le chemin ne sera pas utilisé.

      La spécification XML du proxy doit ressembler à ce qui suit : 

      <?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. Suivez les étapes décrites dans Déployer un proxy d'API pour déployer le proxy dans l'environnement que vous avez créé précédemment.

    Proxy compatible avec SSE

    1. Suivez les étapes décrites dans Créer un proxy d'API pour créer un proxy d'événements envoyés par le serveur avec les spécifications suivantes :
      • Modèle de proxy : sélectionnez Aucune cible.
      • Nom du proxy : saisissez un nom de proxy.
      • Chemin de base : définissez le chemin de base de votre choix. Le chemin ne sera pas utilisé.

      La spécification XML du proxy doit ressembler à ce qui suit : 

      <?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. Configurez EventFlow dans le 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. Suivez les étapes décrites dans Déployer un proxy d'API pour déployer le proxy dans l'environnement que vous avez créé précédemment.

    Configurer l'extension de trafic

    Cette section explique comment configurer l'extension de service de trafic pour votre processeur d'extension en suivant les étapes suivantes :

    1. Créez l'extension de trafic avec l'API de provisionnement Extension Processor.
    2. Envoyez une requête à l'équilibreur de charge.

    Créer l'extension de trafic avec l'API de provisionnement Extension Processor

    Dans cette étape, créez une extension de service de trafic pour votre processeur d'extension à l'aide de l'API de provisionnement du processeur d'extension.

    Créez l'extension de trafic à l'aide de la commande suivante pour appeler l'API de provisionnement Extension Processor : 

    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"
          ]
        }
      ]
    }'

    Où :

    • TRAFFIC_EXT_NAME est le nom de l'extension de trafic que vous créez.
    • LB_FORWARDING_RULE est le nom de la règle de transfert que vous avez créée à une étape précédente.
    • NETWORK est le nom du réseau que vous avez créé à une étape précédente.
    • TARGET_PROXY_NAME est le nom du proxy qui traite le trafic des extensions.
    • CEL_EXPRESSION correspond à l'expression CEL (Common Expression Language) que vous souhaitez utiliser pour l'extension de trafic. Pour en savoir plus sur la syntaxe CEL, consultez la documentation de référence sur le langage de correspondance CEL.
    • FAIL_OPEN est une valeur booléenne qui détermine si l'extension de trafic est ouverte ou fermée en cas d'échec. Les valeurs valides sont true ou false.
    • ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements que vous avez créé lors d'une étape précédente.

    Cette opération peut prendre quelques minutes.

    Obtenir les détails de l'extension de trafic

    Pour vérifier que l'extension de service de trafic a bien été créée, utilisez la commande suivante : 

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

    Remplacez TRAFFIC_EXT_NAME par le nom de l'extension de trafic que vous venez de créer.

    La réponse s'affiche comme suit : 

    {
  "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"
      ]
    }
  ]
}

    Mettre à jour une extension de trafic

    Vous pouvez mettre à jour l'extension de trafic à l'aide du paramètre updateMask. Lorsque vous utilisez le paramètre updateMask, vous spécifiez les attributs de la ressource que vous souhaitez mettre à jour en fournissant une liste d'éléments séparés par une virgule. Les attributs acceptés pour updateMask sont les suivants :

    • networkConfigs : mises à jour des champs region et subnet.
    • extensions : met à jour les champs name, matchCondition, failOpen, hostname et supportedEvents.
    • extensionProcessor : met à jour le champ extensionProcessor.

    Pour mettre à jour une extension de trafic, utilisez la commande curl avec la méthode PATCH. Vous pouvez mettre à jour plusieurs attributs en les incluant dans le paramètre de requête updateMask sous forme de chaîne séparée par des virgules (par exemple, ?updateMask=extensions,extensionProcessor).

    Voici quelques exemples :

    Mise à jour networkConfigs (Global LB)

    Pour mettre à jour les attributs networkConfigs, utilisez la commande suivante :

    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"
      }
    ]
  }'

    Où :

    • TRAFFIC_EXT_NAME est le nom de l'extension de trafic du processeur d'extension à mettre à jour.
    • REGION est la région de la région mise à jour.
    • SUBNET est le nouveau sous-réseau du réseau.

    Mettre à jour extensions

    Pour mettre à jour les attributs extensions, utilisez la commande suivante :

    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"
        ]
      }
    ]
  }'

    Où :

    • TRAFFIC_EXT_NAME est le nom de l'extension de trafic du processeur d'extension à mettre à jour.
    • TARGET_PROXY_NAME est le nom du proxy qui traite le trafic des extensions.
    • NEW_CEL_EXPRESSION est l'expression CEL mise à jour.
    • NEW_FAIL_OPEN est la valeur booléenne mise à jour pour l'échec ouvert.
    • NEW_ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements.

    Mettre à jour extensionProcessor

    Pour mettre à jour les attributs extensionProcessor, utilisez la commande suivante :

    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"
  }'

    Où :

    • TRAFFIC_EXT_NAME est le nom de l'extension de trafic du processeur d'extension à mettre à jour.
    • NEW_TARGET_PROXY_NAME est le nouveau nom du proxy qui traite le trafic des extensions.

    Mettre à jour plusieurs attributs (équilibreur de charge global)

    Pour mettre à jour simultanément les attributs extensions et extensionProcessor, utilisez la commande suivante :

    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"
  }'

    Où :

    • TRAFFIC_EXT_NAME est le nom de l'extension de trafic du processeur d'extension à mettre à jour.
    • TARGET_PROXY_NAME est le nom du proxy qui traite le trafic des extensions.
    • NEW_CEL_EXPRESSION est l'expression CEL mise à jour.
    • NEW_FAIL_OPEN est la valeur booléenne mise à jour pour l'échec ouvert.
    • NEW_ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements.
    • NEW_TARGET_PROXY_NAME est le nouveau nom du proxy qui traite le trafic des extensions.

    Envoyer une requête à l'équilibreur de charge

    Pour tester la configuration de l'équilibreur de charge et du processeur d'extension, envoyez une requête à l'équilibreur de charge : 

    curl "https://LB_DOMAIN_NAME/get"

    Où LB_DOMAIN_NAME est le nom de domaine que vous avez utilisé pour l'équilibreur de charge et le certificat SSL. Si vous avez utilisé nip.io, le nom de domaine ressemblera à IP_ADDRESS.nip.io.

    La réponse s'affiche comme suit : 

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

    Utiliser des règles avec le processeur d'extension

    Cette section explique comment utiliser les règles avec le processeur d'extension.

    Dans cet exemple, configurez une règle VerifyAPIKey et AssignMessage pour le processeur d'extension. Ces règles valident les clés API incluses dans les requêtes envoyées à Apigee et injectent un jeton Googledans les en-têtes de requête pour les appels à un service de backend. Ce scénario serait utile aux fournisseurs d'API qui utilisent le processeur d'extension Apigee pour autoriser et authentifier les requêtes adressées à leurs services Apigee, et injecter de manière fluide les jetons d'authentificationGoogle requis pour un service de backend tel que Vertex AI.

    Ajouter la règle VerifyAPIKey pour la validation des clés API

    Les sections suivantes décrivent comment utiliser la règle VerifyAPIKey pour valider les clés API pour les appels à votre service de backend à l'aide du processeur d'extension :

    1. Associez la règle VerifyAPIKey au processeur d'extension.
    2. Créez un produit d'API.
    3. Créez une application de développement et des identifiants d'application.
    4. Envoyez une requête à l'équilibreur de charge à l'aide de la clé API.

    Associer la règle VerifyAPIKey au proxy

    Pour associer une règle VerifyAPIKey au proxy Extension Processor :

    1. Dans la console Google Cloud , accédez à la page Développement de proxys > Proxys d'API.

      Accéder aux proxys d'API

    2. Sélectionnez le proxy du processeur d'extension que vous avez créé dans la section Créer un processeur d'extension.
    3. Cliquez sur l'onglet Develop (Développer).
    4. Dans le volet de navigation, cliquez sur dans la section Règles.
    5. Dans la boîte de dialogue Créer une règle, sélectionnez VerifyAPIKey dans la liste des règles.
    6. Dans le volet VerifyAPIKey, renseignez les champs obligatoires des sections Name (Nom) et Display name (Nom à afficher) en utilisant les valeurs suivantes :
      • Nom : saisissez un nom de règle. Exemple :VA-verify-api-key
      • Nom à afficher : saisissez le nom de la règle à utiliser dans l'interface utilisateur. Exemple :VA-verify-api-key
    7. Cliquez sur Créer.

      La spécification XML de la règle VerifyAPIKey incluse dans le proxy Extension Processor doit ressembler à ce qui suit : 

        <?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. Déployez la nouvelle révision du proxy.

    Créer un produit d'API

    Pour créer un produit API et configurer l'ensemble d'opérations d'API pour votre service :

    1. Suivez les étapes décrites dans Créer un produit d'API pour créer un produit d'API pour votre service. Vous pouvez configurer les détails du produit pour le produit d'API comme vous le souhaitez.
    2. Suivez les étapes décrites dans Opérations pour ajouter un ensemble d'opérations d'API au produit d'API, en respectant les spécifications suivantes :
      • Source :

        Dans la console Google Cloud , accédez à la page Distribution > Produits d'API.

        Accéder aux produits d'API

        Sélectionnez le produit d'API que vous avez créé lors d'une étape précédente.
      • Opération : cliquez sur Modifier et configurez les chemins et méthodes suivants :
        • Chemin d'accès : /get avec la méthode : GET
        • Chemin d'accès : /TARGET_PROXY_NAME avec la méthode : GET

          TARGET_PROXY_NAME est le nom du proxy qui traite le trafic des extensions.

    Créer une application de développement et des identifiants d'application

    Pour créer une application de développeur et des identifiants d'application pour le produit d'API que vous venez de créer :

    1. Accédez à la page Gestion des API Apigee dans la console Google Cloud  :

      Gestion des API Apigee

    2. Créez un développeur :
      1. Sélectionnez Distribution > Développeurs.
      2. Sur la page Développeurs, cliquez sur + Créer.
      3. Sur la page Ajouter un développeur, renseignez les champs obligatoires avec les valeurs de votre choix.
      4. Cliquez sur Ajouter.
    3. Créer une application :
      1. Sélectionnez Distribution> Applications.
      2. Sur la page Applications, cliquez sur + Créer.
      3. Sur la page Create App (Créer une application), renseignez les champs obligatoires de la section App Details (Détails de l'application) en utilisant les valeurs suivantes :
        • Nom de l'application : saisissez un nom pour l'application, par exemple ext-proc-app.
        • Développeur : sélectionnez le développeur que vous avez créé à l'étape précédente ou un autre développeur de la liste.
      4. Dans la section Identifiants de l'application, cliquez sur + Ajouter des identifiants.
      5. Dans la section Identifiant, sélectionnez Jamais dans la zone de liste Expiration.
      6. Dans la section Produits, cliquez sur + Ajouter des produits pour afficher le volet Ajouter des produits.
      7. Sélectionnez le produit d'API que vous avez créé à l'étape précédente.
      8. Cliquez sur OK.
      9. Cliquez sur Ajouter pour fermer le volet Ajouter des produits.
      10. Cliquez sur Créer.
    4. Sur la page Informations sur l'application, dans la section Identifiant, cliquez sur pour afficher la valeur de la clé.

      Copiez la valeur Key. Vous utiliserez cette clé pour effectuer des appels d'API vers votre service lors d'une étape ultérieure.

    5. Sur la page Détails de l'application, dans la section Identifiant, cliquez sur pour afficher la valeur du secret de l'application.

    Envoyez une requête à l'équilibreur de charge à l'aide de la clé API.

    Pour tester la validation de la clé API, envoyez une requête à l'équilibreur de charge à l'aide de la clé API : 

    curl "https://LB_DOMAIN_NAME/get"

    Où LB_DOMAIN_NAME est le nom de domaine que vous avez utilisé pour l'équilibreur de charge et le certificat SSL.

    La réponse échoue sans clé API.

    Envoyez une autre requête à l'équilibreur de charge en utilisant la clé API dans la requête : 

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

    Où :

    • LB_DOMAIN_NAME correspond au nom de domaine que vous avez utilisé pour l'équilibreur de charge et le certificat SSL.
    • API_KEY correspond à la clé API des identifiants de l'application de développement révélés lors d'une étape précédente.

    La réponse indique que l'autorisation pour le point de terminaison a réussi. Cela indique que le processeur d'extension a validé la clé API et que le proxy Apigee peut désormais traiter la requête.

    Ajouter la règle AssignMessage pour l'authentification Google

    Si vous souhaitez utiliser votre processeur d'extension pour fournir une gestion des API pour un service authentifié par Google, vous pouvez injecter un jeton d'accès Google ou un jeton d'identité Google dans les requêtes envoyées au service de backend à l'aide de la règle AssignMessage.

    Les sections suivantes décrivent comment utiliser la règle AssignMessage pour injecter un jeton d'authentification dans les requêtes envoyées au service de backend à l'aide du processeur d'extension : Google

    1. Associez la règle AssignMessage au proxy.
    2. Envoyez une requête à l'équilibreur de charge pour tester l'injection de jetons.

    Associer la règle AssignMessage au proxy

    Pour ajouter la règle AssignMessage à votre proxy :

    1. Dans la console Google Cloud , accédez à la page Développement de proxys > Proxys d'API.

      Accéder aux proxys d'API

    2. Sélectionnez le proxy du processeur d'extension que vous avez créé dans la section Créer un processeur d'extension.
    3. Cliquez sur l'onglet Develop (Développer).
    4. Dans le volet de navigation, cliquez sur dans la section Règles.
    5. Dans la boîte de dialogue Créer une règle, sélectionnez AssignMessage dans la liste des règles.
    6. Dans le volet Assign Message (Attribuer un message), renseignez les champs obligatoires des sections Name (Nom) et Display name (Nom à afficher) à l'aide des valeurs suivantes :
      • Nom : saisissez un nom de règle. Exemple :AM-auth
      • Nom à afficher : saisissez un nom de règle à afficher dans l'interface utilisateur. Exemple :AM-auth
    7. Cliquez sur Créer.
    8. Sous l'élément <Set>, ajoutez les éléments enfants suivants : 
      <Set>
    <Authentication>
    <HeaderName>Authorization</HeaderName>
    <GoogleAccessToken>
        <Scopes>
        <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
    </GoogleAccessToken>
    </Authentication>
</Set>
    9. Cliquez sur Enregistrer.
    10. Déployez la nouvelle révision à l'aide d'un compte de service Google .

    Le compte de service génère des jetons d'accès Google et les injecte dans l'en-tête de requête pour les appels d'API aux services de backend Google .

    Envoyer une requête à l'équilibreur de charge pour tester l'injection de jetons

    Pour confirmer que l'injection de jetons fonctionne, envoyez une requête à l'équilibreur de charge : 

    curl "https://LB_DOMAIN_NAME/get"

    Où LB_DOMAIN_NAME est le nom de domaine que vous avez utilisé pour l'équilibreur de charge et le certificat SSL.

    La réponse s'affiche comme suit : 

    {
  ...
  "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 réponse indique que le jeton d'authentification Google a bien été injecté dans l'en-en-tête de requête.

    Une fois la règle AssignMessage appliquée, la requête réussie du client (contenant la clé API) envoyée à Apigee dans le scénario d'exemple est modifiée pour inclure un jeton d'authentification Google dans l'en-en-tête de requête, comme l'exige le service de backend authentifié par Google.