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 API, 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 necessárias 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

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

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Enable the APIs

1. 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 da gcloud.

2. 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.

   É possível conferir 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.

3. 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ões do Apigee, peça ao administrador para conceder a você os seguintes papéis do IAM na organização:

• Criar e gerenciar contas de serviço: Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
• Criar e gerenciar extensões de serviço: Administrador de extensões de serviço (roles/networkservices.serviceExtensionsAdmin)
• Criar e gerenciar grupos de endpoints de rede (NEGs): Administrador de instâncias do Compute (roles/compute.instanceAdmin)
• Criar e gerenciar recursos de rede: Administrador de rede do Compute (roles/compute.networkAdmin)
• Criar e gerenciar serviços de back-end: Administrador do balanceador de carga do Compute (roles/compute.loadBalancerAdmin)
• Criar e gerenciar recursos da Apigee: Administrador da organização da Apigee (roles/apigee.admin)

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 necessárias para configurar um balanceador de carga de aplicativo externo global para um serviço de back-end usando httpbin.org como exemplo:

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

Criar um balanceador de carga de aplicativo externo global

Para criar o balanceador de carga:

1. 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.

2. 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?).

3. 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.

4. 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:

1. 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.

2. 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:

1. Crie o serviço de back-end:

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

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

2. 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, 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 você criou em uma etapa anterior.

Configurar o processador de extensões da Apigee

As seções a seguir descrevem as etapas necessárias para configurar o processador de extensão da Apigee:

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

Criar um ambiente da Apigee

Observação:antes de criar um novo ambiente e grupo de ambiente ou usar recursos atuais para a etapa, confira as limitações em ambientes, grupos de ambiente e proxies de API na configuração do processador de extensões. Saiba mais em Limitações.
1. 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.

2. 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.

3. 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.
4. 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 a 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

1. Siga as etapas em Como criar um proxy de API para criar um proxy Sem destino com as seguintes especificações:
   • Modelo do 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>
       <Policies></Policies>
       <ProxyEndpoints>
           <ProxyEndpoint>default</ProxyEndpoint>
       </ProxyEndpoints>
   </APIProxy>

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

Proxy compatível com SSE

1. 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 do 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>

2. 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>

3. 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:

1. Crie um grupo de endpoints da rede do Private Service Connect do Apigee.
2. Crie uma extensão de serviço do balanceador de carga.
3. Envie uma solicitação ao balanceador de carga.

Criar um grupo de endpoints da rede do Private Service Connect do Apigee

Nesta seção, você vai criar um grupo de endpoints de rede (NEG) do Private Service Connect (PSC) da Apigee usado para se conectar à sua instância da Apigee. Para saber mais sobre o PSC, consulte Padrões de rede para sul.

Observação: o comando para receber o anexo de serviço do PSC da Apigee exige jq. Se esse utilitário de processamento JSON ainda não estiver instalado no seu ambiente de desenvolvimento, instale-o usando o seguinte comando: $ sudo apt install jq.

Para criar um NEG do PSC da Apigee:

1. Acesse o anexo de serviço do PSC da Apigee:

   PSC_ATTACHMENT=$(curl -s -H "Authorization: Bearer $TOKEN" \
       "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/instances" \
       | jq -r '.instances[] | select(.name = "'$INSTANCE'") | .serviceAttachment' \
       )

   Para ver o anexo de serviço:

   echo $PSC_ATTACHMENT

   A resposta será assim:

   projects/apigee-psc-autopush/regions/us-west1/serviceAttachments/apigee-us-west1-1234567890-psc-service-attachment

2. Crie o NEG de PSC na mesma região da sua instância do Apigee:

   gcloud compute network-endpoint-groups create apigee-neg-$REGION \
     --network-endpoint-type=private-service-connect \
     --psc-target-service=$PSC_ATTACHMENT \
     --region=$REGION \
     --network=$VPC_NETWORK_NAME \
     --subnet=$SUBNET

   A resposta será assim:

   projects/ab123456cd78ef910g-tp/regions/asia-northeast1/serviceAttachments/apigee-asia-northeast1-abcd

3. Crie um serviço de back-end HTTP/2 que aponte para o NEG do PSC, se ainda não existir:

   gcloud compute backend-services create PSC_NEG_BACKEND_SERVICE \
     --load-balancing-scheme=EXTERNAL_MANAGED \
     --protocol=HTTP2 \
     --global

   Em que PSC_NEG_BACKEND_SERVICE é o nome do serviço de back-end que você quer criar.

4. Adicione o serviço de back-end do NEG do PSC:

   gcloud compute backend-services add-backend PSC_NEG_BACKEND_SERVICE \
     --network-endpoint-group=apigee-neg-$REGION \
     --network-endpoint-group-region=$REGION \
     --global

   Em que PSC_NEG_BACKEND_SERVICE é o nome do serviço de back-end que você criou em uma etapa anterior.

5. Ative a geração de registros para o serviço de back-end:

   gcloud compute backend-services update PSC_NEG_BACKEND_SERVICE \
     --global \
     --enable-logging \
     --logging-sample-rate=1.0

   Em que PSC_NEG_BACKEND_SERVICE é o nome do serviço de back-end que você criou em uma etapa anterior.

Criar uma extensão de serviço do balanceador de carga

Ao criar uma extensão de serviço de balanceador de carga, é possível personalizar o comportamento do proxy do processador de extensão mudando os valores de vários campos que descrevem a extensão, conforme mostrado na tabela a seguir:

Processamento de corpo	Eventos aceitos	Metadados	Modo de envio
Processamento do corpo de solicitação e resposta	REQUEST_HEADERS REQUEST_BODY REQUEST_TRAILERS RESPONSE_HEADERS RESPONSE_BODY RESPONSE_TRAILERS	apigee-request-body: true apigee-response-body: true	requestBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED responseBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED
Processamento apenas do corpo da solicitação	REQUEST_HEADERS REQUEST_BODY REQUEST_TRAILERS RESPONSE_HEADERS	apigee-request-body: true	requestBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED
Processamento apenas do corpo da resposta	REQUEST_HEADERS RESPONSE_HEADERS RESPONSE_BODY RESPONSE_TRAILERS	apigee-response-body: true	responseBodySendMode: BODY_SEND_MODE_FULL_DUPLEX_STREAMED

Nesta etapa, você vai criar uma extensão de serviço de balanceador de carga que oferece suporte ao processamento do corpo da solicitação e da resposta:

curl -X POST "https://networkservices.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/global/lbTrafficExtensions?lbTrafficExtensionId=global-xlb-httpbin-apim-policy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "global-xlb-httpbin-apim-policy",
    "forwardingRules": [
        "https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/forwardingRules/FORWARDING_RULE_NAME"
    ],
    "extensionChains": [
        {
            "name": "httpbin-apigee-extension-chain",
            "matchCondition": {
                "celExpression": "true"
            },
            "extensions": [
                {
                    "name": "httpbin-apigee-extension",
                    "authority": "ENV_GROUP_HOSTNAME",
                    "service": "https://www.googleapis.com/compute/v1/projects/$PROJECT_ID/global/backendServices/PSC_NEG_BACKEND_SERVICE",
                    "supportedEvents": [
                        "REQUEST_HEADERS",
                        "REQUEST_BODY",
                        "REQUEST_TRAILERS",
                        "RESPONSE_HEADERS",
                        "RESPONSE_BODY",
                        "RESPONSE_TRAILERS"
                    ],
                    "timeout": "1s",
                    "requestBodySendMode": "BODY_SEND_MODE_FULL_DUPLEX_STREAMED",
                    "responseBodySendMode": "BODY_SEND_MODE_FULL_DUPLEX_STREAMED"
                }
            ]
        }
    ],
    "loadBalancingScheme": "EXTERNAL_MANAGED",
    "metadata": {
        "apigee-extension-processor": "EXT_PROC_NAME",
        "apigee-request-body": "true",
        "apigee-response-body": "true"
    }
}'

Em que:

• EXT_PROC_NAME: esse nome precisa corresponder ao nome do proxy de API criado em uma etapa anterior.
• FORWARDING_RULE_NAME é o nome da regra de encaminhamento criada em uma etapa anterior.
• ENV_GROUP_HOSTNAME é o nome de domínio usado para o grupo de ambientes.
• PSC_NEG_BACKEND_SERVICE é o nome do serviço de back-end que você criou em uma etapa anterior.

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

Para confirmar se a extensão de serviço foi criada, use o seguinte comando:

curl "https://networkservices.googleapis.com/v1beta1/projects/$PROJECT_ID/locations/global/lbTrafficExtensions/httpbin-apigee-extension" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

A resposta vai aparecer assim e mostrar a regra de encaminhamento e o serviço de back-end:

createTime: '2025-03-22T00:29:16.056719825Z'
extensionChains:
- extensions:
  - authority: extension-processor-test.hybrid.e2e.apigeeks.net
    name: httpbin-apigee-extension
    service: https://www.googleapis.com/compute/v1/projects/123456789012/global/backendServices/ep-test-psc-neg-bes
    supportedEvents:
    - REQUEST_HEADERS
    - REQUEST_BODY
    - REQUEST_TRAILERS
    - RESPONSE_HEADERS
    - RESPONSE_BODY
    - RESPONSE_TRAILERS
    timeout: 1s
  matchCondition:
    celExpression: 'true'
  name: httpbin-apigee-extension-chain
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/123456789012/global/forwardingRules/ep-test-fw-rule
loadBalancingScheme: EXTERNAL_MANAGED
metadata:
  apigee-extension-processor: ep-test-proxy
  apigee-request-body: true
  apigee-response-body: true
name: projects/extension-processor-test/locations/global/lbTrafficExtensions/global-xlb-httpbin-apim-policy
updateTime: '2025-03-22T00:29:31.183275055Z'

Enviar uma solicitação ao balanceador de carga

Para testar o balanceador de carga e a configuração do processador de extensões, 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 será 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, uma política VerifyAPIkey e AssignMessage são configuradas para o Extension Processor. Essas políticas são usadas para validar chaves de API incluídas em solicitações para o Apigee e injetar um token Googlenos 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 tokens de autenticaçãoGoogle 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:

1. Anexe a política VerifyAPIKey ao processador de extensão.
2. Crie um produto de API.
3. Crie um app de desenvolvedor e credenciais do app.
4. 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 processador de extensão:

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

   Acessar proxies de API

2. Selecione o proxy do processador de extensão que você criou na seção Criar um processador de extensão.
3. Clique na guia Desenvolver.
4. No painel de navegação, clique em na seção Políticas.
5. Na caixa de diálogo Criar política, selecione VerifyAPIKey na lista de políticas.
6. 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.
7. 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>

8. Implante a nova revisão do proxy.

Criar um produto da API

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

1. 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 da maneira que quiser.
2. 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: /PROXY_NAME com método: GET

       PROXY_NAME é o nome do proxy que você criou em uma etapa anterior.

Criar um app de desenvolvedor e credenciais do app

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

1. Acesse a página Gerenciamento de APIs do Apigee no console do Google Cloud :

   Gerenciamento de APIs da Apigee

2. 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.
3. 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.
4. 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.

5. 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 vai falhar 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 precisa indicar que a autorização do endpoint foi bem-sucedida. Isso indica que o Extension Processor validou a chave de API e que a solicitação agora pode ser processada pelo proxy da Apigee.

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

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:

1. Anexe a política AssignMessage ao proxy.
2. 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:

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

   Acessar proxies de API

2. Selecione o proxy do processador de extensão que você criou na seção Criar um processador de extensão.
3. Clique na guia Desenvolver.
4. No painel de navegação, clique em na seção Políticas.
5. Na caixa de diálogo Criar política, selecione AssignMessage na lista de políticas.
6. 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.
7. Clique em Criar.
8. 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>

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

A conta de serviço é usada para gerar tokens de acesso Google e injetá-los 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 será 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 precisa mostrar 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.