Comece a usar o Apigee Extension Processor

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta página descreve como configurar o processador de extensões do Apigee para ativar a aplicação de políticas de API para tráfego de API através de um equilibrador de carga com extensões de serviço ativadas.

Para saber mais sobre os exemplos de utilização sugeridos e as vantagens de usar o Apigee Extension Processor para a gestão de APIs, consulte o artigo Vista geral do Apigee Extension Processor.

O processador de extensões do Apigee é uma extensão de tráfego (um tipo de extensão de serviço) que lhe permite usar o Cloud Load Balancing para enviar chamadas externas do caminho de processamento de dados do equilibrador de carga de aplicações para o processador de extensões do Apigee. Assim que o equilibrador de carga e a extensão de tráfego estiverem configurados, o tráfego da API é processado pelo equilibrador de carga. As políticas no processador de extensões do Apigee são aplicadas ao tráfego de API através de chamadas de extensões de tráfego.

As secções seguintes explicam os passos para configurar os elementos principais do Apigee Extension Processor:

Configure um balanceador de carga para um serviço de back-end.
Configure o processador de extensões do Apigee.
Configure a extensão de tráfego.
Use 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 CLI Google Cloud, execute o comando gcloud components update para obter os componentes gcloud mais recentes.
Aprovisione uma instância do Apigee com a versão 1-15-0-apigee-2 ou posterior, se ainda não o tiver feito.
Veja as versões das instâncias na página Detalhes da instância da IU do Apigee na Google Cloud consola. Aceda à página Instâncias na Google Cloud consola para selecionar uma instância e ver os respetivos detalhes:
Aceda a Instâncias

Pode usar o processador de extensões com uma organização do Apigee de subscrição ou de Pay-as-you-go. Se não tiver a certeza de que está a usar uma organização do Apigee de subscrição ou de pagamento conforme o uso, contacte o administrador da sua organização do Apigee. Para mais detalhes sobre o aprovisionamento de instâncias pagas do Apigee, consulte o artigo Antes de começar.
Confirme que tem uma VPC e uma sub-rede ativadas na instância do Apigee que planeia usar. Aceda à página Redes VPC na Google Cloud consola:
Aceda a Redes VPC

Funções necessárias

Para receber as autorizações de que precisa para instalar o processador de extensões do Apigee, peça ao seu administrador para lhe conceder as seguintes funções de IAM:

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

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Defina variáveis de ambiente

No Google Cloud projeto que contém a 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

Onde:

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

Para confirmar que as variáveis de ambiente estão definidas corretamente, execute o seguinte comando e reveja o resultado:

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

Configure 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

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

As secções seguintes descrevem os passos para configurar um Application Load Balancer externo global para um serviço de back-end, usando httpbin.org como exemplo:

Crie um Application Load Balancer externo global.
Crie um grupo de pontos finais 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.

Crie um balanceador de carga de aplicações externo global

Para criar o balanceador de carga:

Defina a configuração gcloud para usar o seu projeto atual:
```
gcloud config set project PROJECT_ID
```
Onde PROJECT_ID é o ID do projeto com a 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 quer criar. O nome tem de corresponder à expressão regular (?:a-z?).
Obtenha o endereço IP e guarde-o como uma variável de ambiente:
```
IP=$(gcloud compute addresses describe IP_ADDRESS --format="get(address)" --global)
```
Onde IP_ADDRESS é o nome do endereço IP que criou no passo anterior.
Crie um certificado TLS para nip.io, um serviço de terceiros que fornece registos DNS com carateres universais 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 quer criar.

Crie um grupo de pontos finais de rede (NEG)

Para criar o grupo de pontos finais de rede (NEG) para o 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 quer criar.

Adicione o ponto final para httpbin.org ao NEG:

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

Onde NEG_NAME é o nome do NEG que criou no passo anterior.

Crie 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

Replace BACKEND_SERVICE_NAME é o nome do serviço de back-end que 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
```
Onde:
- BACKEND_SERVICE_NAME é o nome do serviço de back-end que criou no passo anterior.
- NEG_NAME é o nome do NEG que criou num passo anterior.

Crie um mapa de URLs

Para criar um mapa de URLs 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

Onde:

URL_MAP_NAME é o nome do mapa de URLs que quer criar.
BACKEND_SERVICE_NAME é o nome do serviço de back-end que criou num passo anterior.

Crie um proxy de destino

Para criar um proxy de destino para o equilibrador 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

Onde:

TARGET_PROXY_NAME é o nome do proxy de destino que quer criar.
URL_MAP_NAME é o nome do mapa de URLs que criou num passo anterior.
SSL_CERT_NAME é o nome do certificado SSL que criou para nip.io num passo anterior.

Crie 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

Onde:

FORWARDING_RULE_NAME é o nome da regra de encaminhamento que quer criar.
IP_ADDRESS é o nome do endereço IP do ponto final do NEG que criou num passo anterior.
TARGET_PROXY_NAME é o nome do proxy de destino que processa o tráfego de extensões.

Configure o processador de extensões do Apigee

As secções seguintes descrevem os passos para configurar o processador de extensões do Apigee:

Crie um ambiente do Apigee.
Crie o proxy do processador de extensões.

Crie um ambiente do Apigee

Crie um ambiente do Apigee com 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 está a criar. O nome tem de conter entre 2 e 32 carateres, que podem ser letras minúsculas, números ou hífenes. O nome tem de começar com uma letra e não pode terminar com um hífen. O nome tem de ser diferente de qualquer outro nome de ambiente na sua organização.

Confirme que o ambiente foi criado:

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

A lista de ambientes deve incluir o ambiente que acabou de criar.

Associe o ambiente recém-criado à sua instância do 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 criou no passo anterior.

Esta operação pode demorar até 10 minutos.

Crie o grupo de ambientes do 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"]
        }'
```
Onde:
- ENV_GROUP_NAME é o nome do grupo de ambientes que está a criar.
- ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes que está a criar. O nome do anfitrião tem de ser um nome de domínio totalmente qualificado (FQDN).
  Nota: não é necessário que o nome do anfitrião seja resolvível.

Associe o novo ambiente ao novo grupo de ambientes:

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

Onde:

ENV_GROUP_NAME é o nome do grupo de ambientes que está a criar.
ENV_NAME é o nome do ambiente que criou num passo anterior.

Crie o proxy do processador de extensões

O proxy do processador de extensões é um proxy da API Apigee usado para aplicar políticas de gestão de APIs ao tráfego do equilibrador de carga. Pode criar um proxy no-target ou um proxy ativado para eventos enviados pelo servidor (SSE). Para saber mais sobre a utilização de SSE com o Apigee, consulte o artigo Eventos enviados pelo servidor.

Para criar um proxy de API do Apigee para utilização com o equilibrador de carga do processador de extensões:

Nenhum proxy de destino

Siga os passos em Criar um proxy de API para criar um proxy Sem destino com as seguintes especificações:

Modelo de proxy: selecione Nenhuma segmentação.
Nome do proxy: introduza um nome do proxy. Este nome vai servir como identificador do processador de extensões.
Caminho base: defina qualquer caminho base que quiser. O caminho não vai ser usado.

A especificação XML do proxy deve ser semelhante à seguinte:

<?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 os passos em Implemente um proxy de API para implementar o proxy no ambiente que criou anteriormente.

Proxy com SSE ativado

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

Modelo de proxy: selecione Nenhuma segmentação.
Nome do proxy: introduza um nome do proxy.
Caminho base: defina qualquer caminho base que quiser. O caminho não vai ser usado.

A especificação XML do proxy deve ser semelhante à seguinte:

<?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 os passos em Implemente um proxy de API para implementar o proxy no ambiente que criou anteriormente.

Configure a extensão de tráfego

Esta secção descreve como configurar a extensão do serviço de tráfego para o processador de extensões através dos seguintes passos:

Crie a extensão de tráfego com a API de aprovisionamento do processador de extensões.
Envie um pedido ao equilibrador de carga.

Crie a extensão de tráfego com a API de aprovisionamento do processador de extensões

Neste passo, crie uma extensão de serviço de tráfego para o processador de extensões através da API de aprovisionamento do processador de extensões.

Crie a extensão de tráfego através do seguinte comando para chamar a API de aprovisionamento do processador de extensões:

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

Onde:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego que está a criar.
LB_FORWARDING_RULE é o nome da regra de encaminhamento que criou num passo anterior.
NETWORK é o nome da rede que criou num passo anterior.
TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensões.
CEL_EXPRESSION é a expressão do Idioma de expressão comum (IEC) que quer usar para a extensão de tráfego. Para mais informações sobre a sintaxe do IEC, consulte a referência do idioma do motor de correspondência do IEC.
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 anfitrião do grupo de ambientes que criou num passo anterior.

Nota: depois de criar a extensão de tráfego, não é possível alterar os campos name, lbForwardingRule e network.

Esta operação pode demorar alguns minutos a ser concluída.

Obtenha detalhes da extensão de trânsito

Para verificar se a extensão do serviço de tráfego foi criada com êxito, 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 acabou de criar.

A resposta é semelhante à seguinte:

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

Atualize uma extensão de tráfego

Pode atualizar a extensão de tráfego com o parâmetro updateMask. Quando usa o parâmetro updateMask, especifica os atributos do recurso que quer atualizar fornecendo uma lista separada por vírgulas. Os atributos suportados para updateMask são:

networkConfigs: atualizações aos campos region e subnet.
Nota: este campo só pode ser atualizado para equilibradores de carga de aplicações globais. Para equilibradores de carga de aplicações regionais, não é possível atualizar o networkConfigs. Tem de eliminar 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. Pode atualizar vários atributos incluindo-os no parâmetro de consulta updateMask como uma string separada por vírgulas (por exemplo, ?updateMask=extensions,extensionProcessor).

Seguem-se alguns exemplos:

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

Onde:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensões a atualizar.
REGION é a região da 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"
        ]
      }
    ]
  }'

Onde:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensões a atualizar.
TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensões.
NEW_CEL_EXPRESSION é a expressão IEC atualizada.
NEW_FAIL_OPEN é o valor booleano atualizado para a abertura em caso de falha.
NEW_ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes.

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

Onde:

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

Atualize vários atributos (LB global)

Para atualizar os atributos extensions e extensionProcessor em simultâneo, 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"
  }'

Onde:

TRAFFIC_EXT_NAME é o nome da extensão de tráfego do processador de extensões a atualizar.
TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensões.
NEW_CEL_EXPRESSION é a expressão IEC atualizada.
NEW_FAIL_OPEN é o valor booleano atualizado para a abertura em caso de falha.
NEW_ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes.
NEW_TARGET_PROXY_NAME é o novo nome do proxy que processa o tráfego de extensões.

Envie um pedido ao balanceador de carga

Para testar a configuração do balanceador de carga e do processador de extensões, envie um pedido para o balanceador de carga:

curl "https://LB_DOMAIN_NAME/get"

Em que LB_DOMAIN_NAME é o nome do domínio que usou para o equilibrador de carga e o certificado SSL. Se tiver usado nip.io, o nome do domínio vai ser semelhante a IP_ADDRESS.nip.io.

A resposta é semelhante à seguinte:

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

Use políticas com o processador de extensões

Esta secção descreve como usar políticas com o processador de extensões.

Neste exemplo, configure uma política VerifyAPIKey e AssignMessage para o processador de extensões. Estas políticas validam as chaves da API incluídas em pedidos ao Apigee e injetam um token nos cabeçalhos dos pedidos para chamadas a um serviço de back-end. GoogleEste cenário seria útil para fornecedores de APIs que usam o processador de extensões do Apigee para autorizar e autenticar pedidos aos respetivos serviços do Apigee e injetar sem problemas os Google tokens de autorização necessários para um serviço de back-end, como a Vertex AI.

Adicione a política VerifyAPIKey para a validação da chave da API

As secções seguintes descrevem como usar a política VerifyAPIKey para validar chaves de API para chamadas ao seu serviço de back-end através do processador de extensões:

Anexe a política VerifyAPIKey ao processador de extensões.
Crie um produto API.
Crie uma app de programador e credenciais da app.
Envie um pedido ao equilibrador de carga através da chave da API.

Anexe a política VerifyAPIKey ao proxy

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

Na Google Cloud consola, aceda à página Proxy Development > API Proxies.

Aceda a Proxies de API
Selecione o proxy do processador de extensões que criou na secção Crie um processador de extensões.
Clique no separador Desenvolver.
No painel de navegação, clique em na secçã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 secções Nome e Nome a apresentar com os seguintes valores:
- Nome: introduza um nome da política. Por exemplo, VA-verify-api-key.
- Nome a apresentar: introduza o nome da política para utilização na IU. Por exemplo, VA-verify-api-key.

Clique em Criar.

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

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

Implemente a nova revisão do proxy.

Crie um produto de API

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

Siga os passos em Criar um produto API para criar um produto API para o seu serviço. Pode configurar os Detalhes do produto do produto da API da forma que quiser.
Siga os passos em Operações para adicionar um conjunto de operações da API ao produto da API, de acordo com as seguintes especificações:
- Origem:
  Na Google Cloud consola, aceda à página Distribuição > Produtos API.
  
  Aceda a API Products
  Selecione o produto API que criou num passo anterior.
- Operação: clique em Editar e configure os seguintes caminhos e métodos:
  - Caminho: /get com o método: GET
  - Caminho: /TARGET_PROXY_NAME com o método: GET
    TARGET_PROXY_NAME é o nome do proxy que processa o tráfego de extensões.

Crie uma app de programador e credenciais da app

Para criar uma app de programador e credenciais da app para o produto de API recém-criado:

Aceda à página Gestão de APIs da Apigee na Google Cloud consola:
Gestão de APIs da Apigee
Crie um programador:
1. Selecione Distribuição > Programadores.
2. Na página Programadores, clique em + Criar.
3. Na página Adicionar programador, preencha os campos obrigatórios com os valores que quiser.
4. Clique em Adicionar.
Crie uma 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 secção Detalhes da app com os seguintes valores:
  - Nome da app: introduza um nome para a app. Por exemplo, ext-proc-app
  - Programador: selecione o programador que criou no passo anterior ou outro programador da lista.
4. Na secção Credenciais da app, clique em + Adicionar credencial.
5. Na secção Credencial, selecione Nunca na caixa de lista Validade.
6. Na secção Produtos, clique em + Adicionar produtos para apresentar o painel Adicionar produtos.
7. Selecione o produto API que criou no passo anterior.
8. Clique em OK.
9. Clique em Adicionar para fechar o painel Adicionar produtos.
10. Clique em Criar.
Na página Detalhes da app, na secção Credencial, clique em para apresentar o valor da Chave.
Copie o valor Key. Vai usar esta chave para fazer chamadas API ao seu serviço num passo posterior.
Na página Detalhes da app, na secção Credencial, clique em para apresentar o valor do segredo da app.

Envie um pedido ao balanceador de carga através da chave da API

Para testar a validação da chave de API, envie um pedido para o equilibrador de carga através da chave de API:

curl "https://LB_DOMAIN_NAME/get"

Em que LB_DOMAIN_NAME é o nome do domínio que usou para o equilibrador de carga e o certificado SSL.

A resposta falha sem uma chave da API.

Envie outro pedido ao equilibrador de carga, usando a chave de API no pedido:

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

Onde:

LB_DOMAIN_NAME é o nome do domínio que usou para o equilibrador de carga e o certificado SSL.
API_KEY é a chave da API das credenciais da app de programador reveladas num passo anterior.

A resposta indica uma autorização bem-sucedida para o ponto final. Isto indica que o processador de extensões validou a chave da API e que o proxy do Apigee já pode processar o pedido.

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

Se quiser usar o seu processador de extensões para fornecer gestão de APIs para um serviço autenticado pela Google, pode injetar um token de acesso da Google ou um token de ID da Google em pedidos enviados para o serviço de back-end através da política AssignMessage.

As secções seguintes descrevem como usar a política AssignMessage para injetar um token de autenticação Google em pedidos enviados para o serviço de back-end através do processador de extensões:

Anexe a política AssignMessage ao proxy.
Envie um pedido ao balanceador de carga para testar a injeção de tokens.

Anexe a política AssignMessage ao proxy

Para adicionar a política AssignMessage ao proxy:

Na Google Cloud consola, aceda à página Proxy Development > API Proxies.

Aceda a Proxies de API
Selecione o proxy do processador de extensões que criou na secção Crie um processador de extensões.
Clique no separador Desenvolver.
No painel de navegação, clique em na secçã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 secções Nome e Nome a apresentar com os seguintes valores:
- Nome: introduza um nome da política. Por exemplo, AM-auth.
- Nome a apresentar: introduza um nome da política a apresentar na IU. Por exemplo, AM-auth.
Clique em Criar.

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

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

Clique em Guardar.
Implemente a nova revisão através de uma Google conta de serviço.

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

Envie um pedido ao balanceador de carga para testar a injeção de tokens

Para confirmar que a injeção de tokens está a funcionar, envie um pedido ao equilibrador de carga:

curl "https://LB_DOMAIN_NAME/get"

Em que LB_DOMAIN_NAME é o nome do domínio que usou para o equilibrador de carga e o certificado SSL.

A resposta é semelhante à seguinte:

{
  ...
  "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 Google token de autenticação no cabeçalho do pedido.

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

Comece a usar o Apigee Extension Processor 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 necessárias

Defina variáveis de ambiente

Configure um token de autenticação

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

Crie um balanceador de carga de aplicações externo global

Crie um grupo de pontos finais 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

Configure o processador de extensões do Apigee

Crie um ambiente do Apigee

Crie o proxy do processador de extensões

Nenhum proxy de destino

Proxy com SSE ativado

Configure a extensão de tráfego

Crie a extensão de tráfego com a API de aprovisionamento do processador de extensões

Obtenha detalhes da extensão de trânsito

Atualize uma extensão de tráfego

Atualize networkConfigs (LB global)

Atualizar extensions

Atualizar extensionProcessor

Atualize vários atributos (LB global)

Envie um pedido ao balanceador de carga

Use políticas com o processador de extensões

Adicione a política VerifyAPIKey para a validação da chave da API

Anexe a política VerifyAPIKey ao proxy

Crie um produto de API

Crie uma app de programador e credenciais da app

Envie um pedido ao balanceador de carga através da chave da API

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

Anexe a política AssignMessage ao proxy

Envie um pedido ao balanceador de carga para testar a injeção de tokens

Comece a usar o Apigee Extension Processor

Atualize `networkConfigs` (LB global)

Atualizar `extensions`

Atualizar `extensionProcessor`