Esta página foi traduzida pela API Cloud Translation.

Comece a usar o processador de extensão do Apigee

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como configurar o processador de extensão da Apigee para ativar a aplicação de políticas de API no tráfego de API usando um balanceador de carga habilitado para extensões de serviço.

Para saber mais sobre os casos de uso sugeridos e os benefícios de usar o processador de extensões do Apigee para gerenciamento de APIs, consulte Visão geral do processador de extensões do Apigee.

O processador de extensões do Apigee é uma extensão de tráfego (um tipo de extensão de serviço) que permite usar o Cloud Load Balancing para enviar solicitações do caminho de processamento de dados do balanceador de carga de aplicativo para o processador de extensões do Apigee. Depois que o balanceador de carga e a extensão de tráfego forem configurados, o tráfego de API será processado pelo balanceador de carga. As políticas no processador de extensão da Apigee são aplicadas ao tráfego de API usando as chamadas de extensão de tráfego.

As seções a seguir orientam você nas etapas para configurar os elementos principais do processador de extensões da Apigee:

Configure um balanceador de carga para um serviço de back-end.
Configure o processador de extensões da Apigee.
Configure a extensão de tráfego.
Usar políticas com o processador de extensões.

Antes de começar

Antes de começar a configurar o processador de extensões do Apigee, conclua as seguintes tarefas:

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.

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

Verify that billing is enabled for your Google Cloud project.

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

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

Verify that billing is enabled for your Google Cloud project.

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

Instale a CLI do Google Cloud.

Depois de instalar a Google Cloud CLI, execute o comando gcloud components update para receber os componentes mais recentes dessa ferramenta.
Provisione uma instância do Apigee usando a versão 1-15-0-apigee-2 ou mais recente, caso ainda não tenha feito isso.
Confira as versões da instância na página Detalhes da instância da interface da Apigee no console do Google Cloud . Acesse a página Instâncias no console do Google Cloud para selecionar uma instância e conferir os detalhes dela:
Acesse "Instâncias"

É possível usar o processador de extensões com uma organização da Apigee por assinatura ou Pay-as-you-go. Se você não tiver certeza se está usando uma organização da Apigee por assinatura ou pagamento por uso, entre em contato com o administrador da Apigee. Para mais detalhes sobre o provisionamento de instâncias pagas da Apigee, consulte Antes de começar.
Confirme se você tem uma VPC e uma sub-rede ativadas na instância da Apigee que planeja usar. Acesse a página Redes VPC no console Google Cloud :
Acessar redes VPC

Funções exigidas

Para receber as permissões necessárias para instalar o processador de extensão do Apigee, peça ao administrador que conceda a você os seguintes papéis do IAM:

Criar e gerenciar contas de serviço: Administrador da conta de serviço (roles/iam.serviceAccountAdmin) na organização
Criar e gerenciar extensões de serviço: Administrador de extensões de serviço (roles/networkservices.serviceExtensionsAdmin) na organização
Criar e gerenciar grupos de endpoints de rede (NEGs): Administrador de instâncias do Compute (roles/compute.instanceAdmin) na organização
Criar e gerenciar recursos de rede: Administrador de rede do Compute (roles/compute.networkAdmin) na organização
Criar e gerenciar serviços de back-end: Administrador do balanceador de carga do Compute (roles/compute.loadBalancerAdmin) na organização
Criar e gerenciar recursos da Apigee: Administrador da organização da Apigee (roles/apigee.admin) na organização
Criar e gerenciar extensões de tráfego: Administrador de extensão de serviço da APIM da Apigee (roles/apigee.apimServiceExtensionAdmin) na organização
Ver extensões de tráfego: Leitor de extensões de serviço da APIM da Apigee (roles/apigee.apimServiceExtensionViewer) na organização
Gerenciar operações de longa duração: Agente de serviço de extensão de serviço da APIM da Apigee (roles/apigee.apimServiceExtensionServiceAgent) no agente de serviço do projeto Google Cloud

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Defina as variáveis de ambiente

No projeto Google Cloud que contém sua instância do Apigee, use o seguinte comando para definir variáveis de 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

Em que:

PROJECT_ID é o ID do projeto com sua instância da Apigee.
REGION é a Google Cloud região da sua instância da Apigee.
INSTANCE é o nome da instância da Apigee.
VPC_NETWORK_NAME é o nome da rede VPC no projeto Google Cloud que você quer usar para o processador de extensões do Apigee.
SUBNET é o nome da sub-rede no projeto Google Cloud que você quer usar para o processador de extensões da Apigee.

Para confirmar se as variáveis de ambiente estão definidas corretamente, execute o comando a seguir e analise a saída:

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

Configurar um token de autenticação

Para configurar um token de autenticação, execute o seguinte comando:

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

Configurar um balanceador de carga para um serviço de back-end

As seções a seguir descrevem as etapas para configurar um balanceador de carga de aplicativo externo global para um serviço de back-end usando httpbin.org como exemplo:

Crie um balanceador de carga de aplicativo externo global.
Crie um grupo de endpoints de rede (NEG).
Crie um serviço de back-end.
Crie um mapa de URLs.
Crie um proxy de destino.
Crie uma regra de encaminhamento global.

Criar um balanceador de carga de aplicativo externo global

Para criar o balanceador de carga:

Defina a configuração do gcloud para usar seu projeto atual:
```
gcloud config set project PROJECT_ID
```
Em que PROJECT_ID é o ID do projeto com sua instância do Apigee.
Crie um endereço IP estático global:
```
gcloud compute addresses create IP_ADDRESS --ip-version=IPV4 --global
```
Em que IP_ADDRESS é o nome do endereço IP que você quer criar. O nome precisa corresponder à expressão regular (?:a-z?).
Acesse o endereço IP e salve-o como uma variável de ambiente:
```
IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)
```
Em que IP_ADDRESS é o nome do endereço IP que você criou na etapa anterior.
Crie um certificado TLS para nip.io, um serviço de terceiros que fornece registros DNS curinga para endereços IP:
```
gcloud compute ssl-certificates create SSL_CERT_NAME \
  --domains="nip.io"
```
Em que SSL_CERT_NAME é o nome do certificado que você quer criar.

Criar um grupo de endpoints de rede (NEG)

Para criar o grupo de endpoints de rede (NEG) do balanceador de carga:

Crie um NEG:

gcloud compute network-endpoint-groups create NEG_NAME \
  --network-endpoint-type=INTERNET_FQDN_PORT \
  --default-port=443 \
  --global

Em que NEG_NAME é o nome do NEG que você quer criar.

Adicione o endpoint para httpbin.org ao NEG:

gcloud compute network-endpoint-groups update NEG_NAME \
  --add-endpoint=fqdn=httpbin.org,port=443 \
  --global

Em que NEG_NAME é o nome do NEG criado na etapa anterior.

Criar um serviço de back-end

Para criar o serviço de back-end exposto pelo balanceador de carga:

Crie o serviço de back-end:

gcloud compute backend-services create BACKEND_SERVICE_NAME \
  --load-balancing-scheme=EXTERNAL_MANAGED \
  --protocol=HTTPS \
  --global

Substitua BACKEND_SERVICE_NAME pelo nome do serviço de back-end que você quer criar.

Adicione o NEG ao back-end:
```
gcloud compute backend-services add-backend BACKEND_SERVICE_NAME \
  --network-endpoint-group=NEG_NAME \
  --global-network-endpoint-group \
  --global
```
Em que:
- BACKEND_SERVICE_NAME é o nome do serviço de back-end que você criou na etapa anterior.
- NEG_NAME é o nome do NEG criado em uma etapa anterior.

Criar um mapa de URLs

Para criar um mapa de URL entre o balanceador de carga e o serviço de back-end, use o seguinte comando:

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

Em que:

URL_MAP_NAME é o nome do mapa de URL que você quer criar.
BACKEND_SERVICE_NAME é o nome do serviço de back-end que você criou em uma etapa anterior.

Criar um proxy de destino

Para criar um proxy de destino para o balanceador de carga processar o tráfego de extensão de serviço, use o seguinte 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

Em que:

TARGET_PROXY_NAME é o nome do proxy de destino que você quer criar.
URL_MAP_NAME é o nome do mapa de URL criado em uma etapa anterior.
SSL_CERT_NAME é o nome do certificado SSL que você criou para nip.io em uma etapa anterior.

Criar uma regra de encaminhamento global

Para criar uma regra de encaminhamento global para o balanceador de carga, use o seguinte 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

Em que:

FORWARDING_RULE_NAME é o nome da regra de encaminhamento que você quer criar.
IP_ADDRESS é o nome do endereço IP do endpoint do NEG criado em uma etapa anterior.
TARGET_PROXY_NAME é o nome do proxy de destino que processa o tráfego de extensão.

Configurar o processador de extensões da Apigee

As seções a seguir descrevem as etapas para configurar o processador de extensões do Apigee:

Crie um ambiente da Apigee.
Crie o proxy do processador de extensão.

Criar um ambiente da Apigee

Crie um ambiente da Apigee usando o seguinte 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"
            }
          ]
        }
    }'

Em que ENV_NAME é o nome do ambiente que você está criando. O nome precisa ter entre 2 e 32 caracteres, que podem ser letras minúsculas, números ou hifens. O nome precisa começar com uma letra e não pode terminar com um hífen. O nome precisa ser diferente de qualquer outro nome de ambiente da organização.

Confirme se o ambiente foi criado:

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

A lista de ambientes precisa incluir o que você acabou de criar.

Anexe o ambiente recém-criado à sua instância da 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"
        }'

Em que ENV_NAME é o nome do ambiente que você criou na etapa anterior.

Essa operação pode levar até 10 minutos.

Crie o grupo de ambientes da 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"]
        }'
```
Em que:
- ENV_GROUP_NAME é o nome do grupo de ambiente que você está criando.
- ENV_GROUP_HOSTNAME é o nome do host do grupo de ambientes que você está criando. O nome do host precisa ser um nome de domínio totalmente qualificado (FQDN).
  Observação:não é necessário que o nome do host seja resolvido.

Anexe o novo ambiente ao novo grupo de ambiente:

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

Em que:

ENV_GROUP_NAME é o nome do grupo de ambiente que você está criando.
ENV_NAME é o nome do ambiente que você criou em uma etapa anterior.

Criar o proxy do processador de extensão

O proxy do processador de extensões é um proxy de API da Apigee usado para aplicar políticas de gerenciamento de API ao tráfego do balanceador de carga. É possível criar um proxy sem destino ou um proxy ativado para eventos enviados pelo servidor (SSE). Para saber mais sobre como usar SSE com o Apigee, consulte Eventos enviados pelo servidor.

Para criar um proxy de API do Apigee para uso com o balanceador de carga do processador de extensão:

Nenhum proxy de destino

Siga as etapas em Como criar um proxy de API para criar um proxy Sem destino com as seguintes especificações:

Modelo de proxy: selecione Nenhum destino.
Nome do proxy: insira um nome. Esse nome vai servir como identificador do processador de extensões.
Caminho base: defina o caminho base que quiser. O caminho não será usado.

A especificação XML do proxy será semelhante a esta:

<?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>

Siga as etapas em Implantar um proxy de API para implantar o proxy no ambiente criado anteriormente.

Proxy compatível com SSE

Siga as etapas em Como criar um proxy de API para criar um proxy de eventos enviados pelo servidor com as seguintes especificações:

Modelo de proxy: selecione Nenhum destino.
Nome do proxy: insira um nome.
Caminho base: defina o caminho base que quiser. O caminho não será usado.

A especificação XML do proxy será semelhante a esta:

<?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>

Configure o EventFlow no 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>

Siga as etapas em Implantar um proxy de API para implantar o proxy no ambiente criado anteriormente.

Configurar a extensão de trânsito

Nesta seção, descrevemos como configurar a extensão de serviço de tráfego para o processador de extensões usando as seguintes etapas:

Crie a extensão de tráfego com a API de provisionamento do Extension Processor.
Envie uma solicitação ao balanceador de carga.

Criar a extensão de tráfego com a API de provisionamento do Extension Processor

Nesta etapa, crie uma extensão de serviço de tráfego para seu processador de extensão usando a API de provisionamento do processador de extensão.

Crie a extensão de tráfego usando o seguinte comando para chamar a API de provisionamento do processador de extensão:

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

Em que:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego que você está criando.
LB_FORWARDING_RULE é o nome da regra de encaminhamento criada em uma etapa anterior.
NETWORK é o nome da rede que você criou em uma etapa anterior.
TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensão.
CEL_EXPRESSION é a expressão da Common Expression Language (CEL) que você quer usar para a extensão de tráfego. Para mais informações sobre a sintaxe da CEL, consulte a referência da linguagem de correspondência da CEL.
FAIL_OPEN é um valor booleano que determina se a extensão de tráfego falha aberta ou fechada. Os valores válidos são true ou false.
ENV_GROUP_HOSTNAME é o nome do host do grupo de ambientes que você criou em uma etapa anterior.

Observação:depois que a extensão de tráfego é criada, os campos name, lbForwardingRule e network não podem ser alterados.

Esta operação leva alguns minutos para ser concluída.

Receber detalhes da extensão de trânsito

Para verificar se a extensão do serviço de tráfego foi criada, use o seguinte comando:

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

Substitua TRAFFIC_EXT_NAME pelo nome da extensão de tráfego que você acabou de criar.

A resposta vai aparecer assim:

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

Atualizar uma extensão de trânsito

É possível atualizar a extensão de tráfego usando o parâmetro updateMask. Ao usar o parâmetro updateMask, especifique os atributos do recurso que você quer atualizar fornecendo uma lista separada por vírgulas. Os atributos aceitos para updateMask são:

networkConfigs: atualizações nos campos region e subnet.
Observação:esse campo só pode ser atualizado para balanceadores de carga de aplicativo globais. Para balanceadores de carga de aplicativo regionais, não é possível atualizar o networkConfigs. É necessário excluir e recriar a extensão para modificar as configurações de rede.
extensions: atualiza os campos name, matchCondition, failOpen, hostname e supportedEvents.
extensionProcessor: atualiza o campo extensionProcessor.

Para atualizar uma extensão de tráfego, use o comando curl com o método PATCH. É possível atualizar vários atributos incluindo-os no parâmetro de consulta updateMask como uma string separada por vírgulas (por exemplo, ?updateMask=extensions,extensionProcessor).

Veja alguns exemplos:

Atualizar `networkConfigs` (LB global)

Para atualizar os atributos networkConfigs, use o seguinte comando:

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

Em que:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensão a ser atualizada.
REGION é a região atualizada.
SUBNET é a nova sub-rede da rede.

Atualizar `extensions`

Para atualizar os atributos extensions, use o seguinte comando:

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

Em que:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensão a ser atualizada.
TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensão.
NEW_CEL_EXPRESSION é a expressão CEL atualizada.
NEW_FAIL_OPEN é o valor booleano atualizado para a abertura por falha.
NEW_ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente.

Atualizar `extensionProcessor`

Para atualizar os atributos extensionProcessor, use o seguinte comando:

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

Em que:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensão a ser atualizada.
NEW_TARGET_PROXY_NAME é o novo nome do proxy que processa o tráfego de extensão.

Atualizar vários atributos (balanceador de carga global)

Para atualizar os atributos extensions e extensionProcessor simultaneamente, use o seguinte 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"
  }'

Em que:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensão a ser atualizada.
TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensão.
NEW_CEL_EXPRESSION é a expressão CEL atualizada.
NEW_FAIL_OPEN é o valor booleano atualizado para a abertura por falha.
NEW_ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente.
NEW_TARGET_PROXY_NAME é o novo nome do proxy que processa o tráfego de extensão.

Enviar uma solicitação ao balanceador de carga

Para testar o balanceador de carga e a configuração do processador de extensão, envie uma solicitação ao balanceador de carga:

curl "https://LB_DOMAIN_NAME/get"

Em que LB_DOMAIN_NAME é o nome de domínio usado para o balanceador de carga e o certificado SSL. Se você usou nip.io, o nome de domínio será semelhante a IP_ADDRESS.nip.io.

A resposta vai aparecer assim:

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

Usar políticas com o Extension Processor

Nesta seção, descrevemos como usar políticas com o Extension Processor.

Neste exemplo, configure uma política VerifyAPIKey e AssignMessage para o Extension Processor. Essas políticas validam as chaves de API incluídas em solicitações para a Apigee e injetam um token Google nos cabeçalhos de solicitação para chamadas a um serviço de back-end. Esse cenário seria útil para provedores de API que usam o processador de extensão do Apigee para autorizar e autenticar solicitações aos serviços do Apigee e injetar sem problemas os Google tokens de autenticação necessários para um serviço de back-end como a Vertex AI.

Adicionar a política VerifyAPIKey para validação de chaves de API

As seções a seguir descrevem como usar a política VerifyAPIKey para validar chaves de API em chamadas ao serviço de back-end usando o processador de extensão:

Anexe a política VerifyAPIKey ao Extension Processor.
Crie um produto de API.
Crie um app de desenvolvedor e credenciais de app.
Envie uma solicitação ao balanceador de carga usando a chave de API.

Anexe a política VerifyAPIKey ao proxy.

Para anexar uma política VerifyAPIKey ao proxy do Extension Processor:

No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.

Acessar "Proxies de API"
Selecione o proxy do processador de extensão que você criou na seção Criar um processador de extensão.
Clique na guia Desenvolver.
No painel de navegação, clique em na seção Políticas.
Na caixa de diálogo Criar política, selecione VerifyAPIKey na lista de políticas.
No painel VerifyAPIKey, preencha os campos obrigatórios nas seções Nome e Nome de exibição usando os seguintes valores:
- Nome: insira um nome para a política. Por exemplo, VA-verify-api-key.
- Nome de exibição: insira o nome da política para uso na UI. Por exemplo, VA-verify-api-key.

Clique em Criar.

A especificação XML da política VerifyAPIKey incluída no proxy do Extension Processor deve ser semelhante a esta:

  <?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>

Implante a nova revisão do proxy.

Criar um produto de API

Para criar um produto de API e configurar o conjunto de operações de API do seu serviço:

Siga as etapas em Como criar um produto de API para criar um produto de API para seu serviço. Você pode configurar os detalhes do produto do produto de API como quiser.
Siga as etapas em Operações para adicionar um conjunto de operações de API ao produto de API, de acordo com as especificações a seguir:
- Fonte:
  No console do Google Cloud , acesse a página Distribuição > Produtos de API.
  
  Acessar produtos de API
  Selecione o produto da API que você criou em uma etapa anterior.
- Operação: clique em Editar e configure os seguintes caminhos e métodos:
  - Caminho: /get com método: GET
  - Caminho: /TARGET_PROXY_NAME com método: GET
    TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensão.

Criar um app de desenvolvedor e credenciais de app

Para criar um app de desenvolvedor e credenciais de app para o produto de API recém-criado:

Acesse a página Gerenciamento de APIs do Apigee no console do Google Cloud :
Gerenciamento de APIs da Apigee
Crie um desenvolvedor:
1. Selecione Distribuição > Desenvolvedores.
2. Na página Desenvolvedores, clique em + Criar.
3. Na página Adicionar desenvolvedor, preencha os campos obrigatórios com os valores que quiser.
4. Clique em Adicionar.
Crie um app:
1. Selecione Distribuição> Apps.
2. Na página Apps, clique em + Criar.
3. Na página Criar app, preencha os campos obrigatórios na seção Detalhes do app usando os seguintes valores:
  - Nome do app: insira um nome para o app. Por exemplo, ext-proc-app
  - Desenvolvedor: selecione o desenvolvedor que você criou na etapa anterior ou outro desenvolvedor na lista.
4. Na seção Credenciais do app, clique em + Adicionar credencial.
5. Na seção Credencial, selecione Nunca na caixa de listagem Validade.
6. Na seção Produtos, clique em + Adicionar produtos para mostrar o painel Adicionar produtos.
7. Selecione o produto da API que você criou na etapa anterior.
8. Clique em OK.
9. Clique em Adicionar para fechar o painel Adicionar produtos.
10. Clique em Criar.
Na página Detalhes do app, na seção Credencial, clique em para mostrar o valor da Chave.
Copie o valor de Key. Você vai usar essa chave para fazer chamadas de API ao seu serviço em uma etapa posterior.
Na página Detalhes do app, na seção Credencial, clique em para mostrar o valor do Secret do app.

Envie uma solicitação ao balanceador de carga usando a chave de API

Para testar a validação da chave de API, envie uma solicitação ao balanceador de carga usando a chave de API:

curl "https://LB_DOMAIN_NAME/get"

Em que LB_DOMAIN_NAME é o nome de domínio usado para o balanceador de carga e o certificado SSL.

A resposta falha sem uma chave de API.

Envie outra solicitação ao balanceador de carga usando a chave de API na solicitação:

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

Em que:

LB_DOMAIN_NAME é o nome de domínio usado para o balanceador de carga e o certificado SSL.
API_KEY é a chave de API das credenciais do app para desenvolvedores reveladas em uma etapa anterior.

A resposta indica que a autorização do endpoint foi concluída. Isso indica que o Extension Processor validou a chave de API e o proxy da Apigee agora pode processar a solicitação.

Adicionar a política AssignMessage para autenticação Google

Se você quiser usar o Extension Processor para fornecer gerenciamento de API a um serviço autenticado pelo Google, é possível injetar um token de acesso ou um token de ID do Google em solicitações enviadas ao serviço de back-end usando a política AssignMessage.

As seções a seguir descrevem como usar a política AssignMessage para injetar um token de autenticação Google em solicitações enviadas ao serviço de back-end usando o Extension Processor:

Anexe a política AssignMessage ao proxy.
Envie uma solicitação ao balanceador de carga para testar a injeção de token.

Anexe a política AssignMessage ao proxy

Para adicionar a política AssignMessage ao seu proxy:

No console do Google Cloud , acesse a página Desenvolvimento de proxy > Proxies de API.

Acessar "Proxies de API"
Selecione o proxy do processador de extensão que você criou na seção Criar um processador de extensão.
Clique na guia Desenvolver.
No painel de navegação, clique em na seção Políticas.
Na caixa de diálogo Criar política, selecione AssignMessage na lista de políticas.
No painel Atribuir mensagem, preencha os campos obrigatórios nas seções Nome e Nome de exibição usando os seguintes valores:
- Nome: insira um nome para a política. Por exemplo, AM-auth.
- Nome de exibição: insira um nome de política para mostrar na UI. Por exemplo, AM-auth.
Clique em Criar.

No elemento <Set>, adicione os seguintes elementos filhos:

<Set>
    <Authentication>
    <HeaderName>Authorization</HeaderName>
    <GoogleAccessToken>
        <Scopes>
        <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
        </Scopes>
    </GoogleAccessToken>
    </Authentication>
</Set>

Clique em Salvar.
Implante a nova revisão usando uma conta de serviço Google .

A conta de serviço gera tokens de acesso Google e os injeta no cabeçalho da solicitação para chamadas de API aos serviços de back-end Google .

Enviar uma solicitação ao balanceador de carga para testar a injeção de token

Para confirmar se a injeção de token está funcionando, envie uma solicitação ao balanceador de carga:

curl "https://LB_DOMAIN_NAME/get"

Em que LB_DOMAIN_NAME é o nome de domínio usado para o balanceador de carga e o certificado SSL.

A resposta vai aparecer assim:

{
  ...
  "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"
  },
  ...
}

A resposta mostra a injeção bem-sucedida do token de autenticação Google no cabeçalho da solicitação.

Com a aplicação bem-sucedida da política AssignMessage, a solicitação bem-sucedida do cliente (que contém a chave de API) para a Apigee no cenário de exemplo é modificada ainda mais para incluir um token de autenticação do Google no cabeçalho da solicitação, conforme exigido pelo serviço de back-end autenticado com Google.

Comece a usar o processador de extensão do Apigee Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Defina as variáveis de ambiente

Configurar um token de autenticação

Configurar um balanceador de carga para um serviço de back-end

Criar um balanceador de carga de aplicativo externo global

Criar um grupo de endpoints de rede (NEG)

Criar um serviço de back-end

Criar um mapa de URLs

Criar um proxy de destino

Criar uma regra de encaminhamento global

Configurar o processador de extensões da Apigee

Criar um ambiente da Apigee

Criar o proxy do processador de extensão

Nenhum proxy de destino

Proxy compatível com SSE

Configurar a extensão de trânsito

Criar a extensão de tráfego com a API de provisionamento do Extension Processor

Receber detalhes da extensão de trânsito

Atualizar uma extensão de trânsito

Atualizar networkConfigs (LB global)

Atualizar extensions

Atualizar extensionProcessor

Atualizar vários atributos (balanceador de carga global)

Enviar uma solicitação ao balanceador de carga

Usar políticas com o Extension Processor

Adicionar a política VerifyAPIKey para validação de chaves de API

Anexe a política VerifyAPIKey ao proxy.

Criar um produto de API

Criar um app de desenvolvedor e credenciais de app

Envie uma solicitação ao balanceador de carga usando a chave de API

Adicionar a política AssignMessage para autenticação Google

Anexe a política AssignMessage ao proxy

Enviar uma solicitação ao balanceador de carga para testar a injeção de token

Comece a usar o processador de extensão do Apigee

Atualizar `networkConfigs` (LB global)

Atualizar `extensions`

Atualizar `extensionProcessor`