Como criar um proxy de API simples

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

Confira a documentação da Apigee Edge.

Note: In environments enabled for archive deployments, you cannot build API proxies using the Apigee UI, API, or gcloud. Para criar proxies de API para implantações de arquivo usando a Apigee no VS Code, consulte Como desenvolver proxies de API usando a Apigee no VS Code.

A Apigee permite que você exponha rapidamente os serviços de back-end como APIs. Para isso, você precisa criar um proxy de API que forneça uma fachada para o serviço de back-end a ser exposto. É necessário fornecer apenas o endereço de rede do serviço de back-end, junto com algumas informações que a Apigee usa para criar o proxy de API que é exposto a desenvolvedores.

O proxy de API separa a implementação do serviço de back-end da API que os desenvolvedores consomem. Assim, eles se protegem das mudanças futuras nos seus serviços de back-end. Enquanto você atualiza os serviços de back-end, os desenvolvedores, isolados dessas mudanças, podem continuar chamando a API sem interrupções.

Neste tópico, você encontra informações sobre os vários tipos de proxies e as configurações para eles. Para instruções passo a passo sobre como criar proxies, consulte os seguintes tópicos:

• Tutorial: Criar seu primeiro proxy de API
• Como criar um proxy de API

Observação: o vídeo a seguir mostra o editor clássico de proxy na interface da Apigee. A Apigee está introduzindo uma nova versão do Editor de Proxy, que tem um design diferente da versão clássica mostrada no vídeo.

Como criar um proxy de API usando a interface

A maneira mais fácil de criar um proxy de API é usando o assistente de criação de proxy.

Para acessar o assistente de criação de proxy usando a IU da Apigee, siga estas etapas:

1. Faça login na IU da Apigee.
2. Na barra de navegação, selecione Develop > API Proxies.
3. Clique em Criar nova.
   

O assistente de criação proxy exibe e direciona você pelas etapas para gerar e adicionar recursos mínimos a um proxy de API.

A primeira página do assistente permite a criação de um proxy de API a com base nas seguintes origens:

Tipo	Descrição
Proxy reverso (mais comum)	Um proxy de API que encaminha solicitações de entrada para os serviços de back-end HTTP. Pode ser uma API JSON ou XML. Consulte Como criar um proxy reverso para um serviço HTTP mais adiante nesta seção. Clique em Use OpenAPI Spec para gerar o proxy com base em uma especificação de OpenAPI válida. Para mais informações sobre essa opção, consulte Como usar especificações da OpenAPI para gerar proxies mais adiante nesta seção.
Nenhum destino	Um proxy de API sem back-end de API ("sem destino"). Semelhante à criação de um proxy reverso para um serviço HTTP descrito anteriormente, exceto que você não especificará uma API ao definir os detalhes do proxy. Clique em Use OpenAPI Spec para gerar o proxy com base em uma especificação de OpenAPI válida. Para mais informações sobre essa opção, consulte Como usar especificações da OpenAPI para gerar proxies mais adiante nesta seção.
Upload do pacote de proxy	Um pacote de proxy de API. Por exemplo, um dos proxys de API de amostra disponíveis no GitHub. Consulte Como importar um proxy de API de um pacote.

As seções a seguir discutem os detalhes de cada tipo de proxy.

Como criar um proxy reverso para um serviço HTTP

A Apigee gera proxies reversos com base nestas informações:

• URL do serviço de back-end
• Caminho de URI que identifica exclusivamente a API que será exposta pelo proxy a apps para o consumidor

O URL do serviço de back-end normalmente representa um aplicativo ativado pelo serviço que pertence à organização. Ele também pode apontar para uma API disponível publicamente. A API ou o serviço pode estar sob seu controle (por exemplo, um aplicativo de RH interno ou um aplicativo do Rails na nuvem) ou pode ser uma API ou um serviço de terceiros (por exemplo, Twitter ou Instagram).

Os seguintes detalhes do proxy estão disponíveis depois de acessar o Criar assistente de proxy e selecionar um tipo de proxy:

Campo	Descrição
Nome	Nome exibido para a API. Especifique caracteres alfanuméricos, traço (-) ou sublinhado (_).
Base path	Fragmento de URI que aparece após o endereço http://[host] ou https://[host] do proxy de API. A Apigee usa o URI do caminho base para corresponder e encaminhar as mensagens de solicitação recebidas para o proxy da API adequado. Observação: o caminho base do proxy de API assume como padrão o valor especificado para o campo Name convertido em letras minúsculas. O caminho base a seguir é qualquer URL de recurso adicional. Veja a seguir a estrutura completa do URL que os clientes usam para chamar o proxy da API: https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH Observação: o caminho base precisa ser único. Não é possível implantar dois proxies de API com o mesmo caminho de base. Se você editar um proxy de API implantado e definir o caminho de base como o mesmo valor que o caminho de base de outro proxy de API, a Apigee removerá automaticamente o proxy da API quando você salvá-lo. Antes de reimplantar o proxy de API, será preciso editar o caminho de base para que ele seja exclusivo. Usar caracteres curinga em caminhos de base Use um ou mais caracteres curinga /*/ nos caminhos de base do proxy de API para preparar seus proxies para o futuro. Por exemplo, um caminho de base /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem a necessidade de criar novos proxies de API para oferecer suporte a novas equipes. /**/ não é compatível.
Descrição	(Opcional) Descrição da API.
Target (Existing API)	URL do serviço de back-end que este proxy de API invoca.

Como importar um proxy de API de um pacote

Observação: ao importar um proxy de API de um pacote, você será responsável por configurar a segurança e adicionar políticas ao pacote. A IU não solicita a adição de segurança ou políticas ao importar o pacote, conforme descrito em Adicionar segurança, mais adiante nesta seção.

Muitas vezes, você define proxies de API como um conjunto de arquivos XML, além de outros arquivos de suporte. Ao definir os proxies da API como um conjunto de arquivos externos à Apigee, é possível mantê-los em um sistema de controle de origem e importá-los para a Apigee para teste e implantação.

Para importar proxies de API de um pacote de proxy de API, execute as seguintes etapas:

1. Acesse o assistente de criação de proxy, conforme descrito anteriormente em Como criar um proxy de API usando a IU.
2. Clique em Upload proxy bundle.

3. Na página Upload proxy bundle no assistente de proxy, digite as informações a seguir.

   Campo	Descrição
   ZIP bundle	ZIP que contém a configuração do proxy de API. Arraste e solte ou clique para navegar até o arquivo.
   Nome	Nome exibido para a API. O padrão é o nome do arquivo ZIP sem a extensão.

4. Clique em Next.

5. Na página Summary, selecione os ambientes de implantação, se quiser, e clique em Create and deploy.

   Uma confirmação é exibida atestar que o novo proxy da API foi criado.

6. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Como criar proxies de API gRPC

Além dos proxies de API REST, a Apigee é atualmente compatível com proxies de API gRPC apenas com suporte de passagem. Em Suporte de passagem, o payload de gRPC é opaco para a Apigee e o tráfego é roteado do cliente de gRPC para o servidor de destino gRPC pré-configurado na configuração de destino.

No momento, os proxies de API gRPC da Apigee:

• Oferecem suporte a solicitações de gRPC unárias.
• Não são capazes de usar políticas que afetem o payload.
• Pode ser usado em produtos de API que não estão associados a proxies GraphQL ou REST. As cotas específicas de produto da API e outras configurações de operação se aplicam a todos os proxies no produto.
• Não são compatíveis com a Apigee híbrida.
• Usam duas variáveis de fluxo específicas de gRPC: request.grpc.rpc.name e request.grpc.service.name.
• Podem ser monitorados com estas variáveis de análise da Apigee: x_apigee_grpc_rpc_name, x_apigee_grpc_service_name e x_apigee_grpc_status.
• Retornam os códigos de status de gRPC.

Você também precisa configurar o balanceador de carga para oferecer suporte a gRPC. Consulte Como usar gRPC com seus aplicativos e Como usar comandos da CLI gcloud para criar roteamento para gRPC.

Para criar um proxy de API gRPC, primeiro defina um servidor de destino gRPC (consulte Como criar servidores de destino) e, em seguida, especifique esse servidor de destino criando o novo proxy.

Observação: a configuração de proxy gRPC por meio da IU da Apigee é compatível somente com a IU da Apigee no Console do Cloud, não com outros consoles da Apigee.

Como usar comandos da CLI gcloud para criar roteamento para gRPC

Nesta seção, você verá exemplos de comandos para criar roteamento de proxies gRPC usando a CLI gcloud. As instruções incluem a configuração de balanceadores de carga, um servidor de destino e um MIG.

Esta seção não constitui um guia abrangente para a criação de roteamento. Os exemplos apresentados talvez não sejam apropriados para todos os casos de uso. Além disso, para seguir estas instruções, é preciso ter familiaridade com o Roteamento externo (MIG, na sigla em inglês) e a Configuração do gRPC do balanceador de carga do Cloud.

Definir as variáveis de ambiente

Essas variáveis de ambiente são usadas nos comandos das subseções.

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Exemplo de comandos da CLI gcloud para criar roteamento para proxies gRPC usando novos balanceadores de carga

Nesta seção, você verá exemplos de comandos para criar proxies gRPC usando a CLI gcloud e um novo balanceador de carga. As instruções incluem a configuração do balanceador de carga, um servidor de destino e um MIG.

Criar o modelo da instância

gcloud compute instance-templates create $MIG_NAME \
--project $PROJECT_ID \
--region $REGION \
--network $VPC_NAME \
--subnet $VPC_SUBNET \
--tags=https-server,apigee-mig-proxy,gke-apigee-proxy \
--machine-type e2-medium --image-family debian-10 \
--image-project debian-cloud --boot-disk-size 20GB \
--no-address \
--metadata ENDPOINT=$APIGEE_ENDPOINT,startup-script-url=gs://apigee-5g-saas/apigee-envoy-proxy-release/latest/conf/startup-script.sh

Criar o grupo gerenciado de instâncias

gcloud compute instance-groups managed create $MIG_NAME \
--project $PROJECT_ID --base-instance-name apigee-mig \
--size 2 --template $MIG_NAME --region $REGION

Configurar o escalonamento automático

gcloud compute instance-groups managed set-autoscaling $MIG_NAME \
--project $PROJECT_ID --region $REGION --max-num-replicas 50 \
--target-cpu-utilization 0.75 --cool-down-period 90

Definir uma porta nomeada

gcloud compute instance-groups managed set-named-ports $MIG_NAME \
--project $PROJECT_ID --region $REGION --named-ports https:443

Criar um certificado SSL gerenciado pelo Google e uma chave para o balanceador de carga

gcloud compute ssl-certificates create $CERTIFICATE_NAME \
--domains=$DOMAIN_HOSTNAME \
--project $PROJECT_ID \
--global

Validar o provisionamento do certificado

gcloud compute ssl-certificates describe $CERTIFICATE_NAME \
--global \
--format="get(name,managed.status, managed.Status)"

Criar o balanceador de carga global do Cloud (GCLB, na sigla em inglês)

1. Crie uma verificação de integridade
   

   gcloud compute health-checks create https hc-apigee-envoy-443 \
   --project $PROJECT_ID --port 443 --global \
   --request-path /healthz/ingress

2. Crie o serviço de back-end para http1
   

   gcloud compute backend-services create YOUR_BACKEND_1 \
   --project $PROJECT_ID \
   --protocol HTTPS \
   --health-checks hc-apigee-envoy-443 \
   --port-name https \
   --timeout 302s \
   --connection-draining-timeout 300s \
   --global

3. Crie o serviço de back-end para http2
   

   gcloud compute backend-services create YOUR_BACKEND_2 \
   --project $PROJECT_ID \
   --protocol HTTP2 \
   --health-checks hc-apigee-envoy-443 \
   --port-name https \
   --timeout 302s \
   --connection-draining-timeout 300s \
   --global

4. Adicione MIGs ao serviço de back-end. Neste exemplo, estamos reutilizando o MIG, mas também é possível criar um novo par de MIGs.
   

   gcloud compute backend-services add-backend YOUR_BACKEND_1 \
   --project $PROJECT_ID --instance-group $MIG_NAME \
   --instance-group-region $REGION \
   --balancing-mode UTILIZATION --max-utilization 0.8 --global

   gcloud compute backend-services add-backend YOUR_BACKEND_2 \
   --project $PROJECT_ID --instance-group $MIG_NAME \
   --instance-group-region $REGION \
   --balancing-mode UTILIZATION --max-utilization 0.8 --global

5. Crie um mapa de URLs de balanceamento de carga. Primeiro, verifique se você já tem um mapa de URLs. Se fizer isso, modifique o mapa de acordo com os requisitos abaixo em vez de substituí-lo.
   

   Crie um arquivo YAML ou use seu arquivo atual, em /tmp/apigee-map.yaml, com essa configuração. O back-end do mapa do URL http1 é padrão.

   defaultService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_1
   name: matcher1
   routeRules:
   - matchRules:
   - headerMatches:
   - headerName: Content-Type
   prefixMatch: application/grpc
   prefixMatch: /
   priority: 100
   routeAction:
   weightedBackendServices:
   - backendService: projects/$PROJECT_ID/global/backendServices/YOUR_BACKEND_2
   weight: 100

   Valide o mapa de URL:

   gcloud compute url-maps validate --source /tmp/apigee-map.yaml --project $PROJECT_ID

   Crie o mapa de URL com roteamento baseado em cabeçalho:

   gcloud compute url-maps import apigee-http1-http2 \
   --source /tmp/apigee-map.yaml  \
   --global --project $PROJECT_ID

Criar um proxy HTTPS de destino do balanceamento de carga

gcloud compute target-https-proxies create apigee-envoy-https-proxy \
--project $PROJECT_ID --url-map apigee-envoy-proxy-map \
--ssl-certificates $CERTIFICATE_NAME

Reservar um IP externo IPV4 e criar regras de firewall para o balanceador de carga

gcloud compute addresses create lb-ipv4-vip-1 \
--project $PROJECT_ID \
--network-tier=PREMIUM \
--ip-version=IPV4 \
--global

  gcloud compute addresses describe lb-ipv4-vip-1 \
--project $PROJECT_ID --format="get(address)" --global

  gcloud compute forwarding-rules create apigee-envoy-https-lb-rule \
--project $PROJECT_ID --address lb-ipv4-vip-1 --global \
--target-https-proxy apigee-envoy-https-proxy --ports 443

Criar uma regra de firewall

gcloud compute firewall-rules create k8s-allow-lb-to-apigee-envoy \
--description "Allow incoming from GLB on TCP port 443 to Apigee Proxy" \
--project $PROJECT_ID --network $VPC_NAME --allow=tcp:443 \
--source-ranges=130.211.0.0/22,35.191.0.0/16 --target-tags=gke-apigee-proxy

Exemplo de comandos da CLI gcloud para criar um roteamento para proxies gRPC para balanceadores de carga existentes

Nesta seção, mostramos exemplos de comandos para criar proxies gRPC usando a CLI gcloud e um balanceador de carga existente. As instruções incluem a configuração do balanceador de carga, um servidor de destino e um MIG.

Criar outro serviço de back-end para http2

# Create backend service for http2
    gcloud compute backend-services create YOUR_BACKEND_2 \
--project $PROJECT_ID \
--protocol HTTP2 \
--health-checks hc-apigee-envoy-443 \
--port-name https \
--timeout 302s \
--connection-draining-timeout 300s \
--global

Anexar o segundo serviço de back-end ao MIG

gcloud compute backend-services add-backend YOUR_BACKEND_2 \
--project $PROJECT_ID --instance-group $MIG_NAME \
--instance-group-region $REGION \
--balancing-mode UTILIZATION --max-utilization 0.8 --global

Listar o mapa de URL do GCLB da Apigee

gcloud compute url-maps list -project $PROJECT_ID

Escolher o nome correto do mapa de URL usado para o balanceamento de carga da Apigee

gcloud compute url-maps export APIGEE_URL_MAP_NAME -project $PROJECT_ID

Criar um arquivo YAML de mapa de URL de balanceamento de carga

Se você já tiver um mapa de URL, mescle essa configuração nele. Caso contrário, crie um arquivo YAML em /tmp/apigee-map.yaml com essa configuração.

defaultService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_1
name: matcher1
routeRules:
- matchRules:
- headerMatches:
- headerName: Content-Type
prefixMatch: application/grpc
prefixMatch: /
priority: 100
routeAction:
weightedBackendServices:
- backendService: projects/dg-runtime-test1/global/backendServices/YOUR_BACKEND_2
weight: 100

Aplicar o novo YAML para roteamento do gRPC

gcloud compute url-maps import APIGEE_URL_MAP_NAME\
--source /tmp/apigee-map.yaml  \
--global -project $PROJECT_ID

Como reforçar a segurança

Na página Common Policies do assistente de criação de proxy, selecione o tipo de autorização de segurança que você quer adicionar. A tabela a seguir resume as opções disponíveis:

Autorização de segurança	Descrição
Chave de API	Adiciona uma verificação de chave de API simples ao proxy que você está definindo. Em resposta, a plataforma de API adiciona as políticas VerifyAPIKey e AssignMessage ao proxy. A política VerifyAPIKey valida as chaves de API apresentadas pelos apps que fazem as solicitações. A política AssignMessage remove a chave de API, fornecida na chamada de API como um parâmetro de consulta, da solicitação encaminhada para o servidor de back-end.
OAuth 2.0	Adiciona a autenticação baseada em OAuth 2.0 ao proxy de API. A Apigee adiciona automaticamente as seguintes políticas ao proxy de API: uma para verificar um token de acesso e outra para remover esse token da mensagem antes de encaminhá-lo para o serviço de back-end. Para saber como conseguir um token de acesso, consulte OAuth.
Passagem (sem autorização)	Nenhuma autorização necessária. As solicitações são transmitidas para o back-end sem nenhuma verificação de segurança na Apigee.

Como adicionar suporte para o CORS

O compartilhamento de recursos entre origens (CORS) é um mecanismo padrão que permite ao navegador da Web fazer solicitações diretas para outro domínio. O padrão CORS define um conjunto de cabeçalhos HTTP que os servidores e os navegadores da Web usam para implementar a comunicação entre domínios.

É possível adicionar suporte ao CORS seguindo um destes procedimentos:

• Como adicionar a política de CORS ao PreFlow de solicitação do ProxyEndpoint
• Selecione Adicionar cabeçalhos CORS na página Políticas comuns do assistente Criar proxy

Para informações mais detalhadas sobre o suporte ao CORS, incluindo como adicionar a um proxy o suporte à simulação do CORS, consulte Como adicionar suporte para o CORS a um proxy de API.

Como adicionar cotas

Cotas protegem seu serviço de back-end contra tráfego alto em Quota. Veja Cotas. Essa opção não estará disponível se a autorização de passagem estiver selecionada.

Como usar especificações de OpenAPI para gerar proxies

Esta seção aborda a opção "Usar OpenAPI" que está disponível para geração de uma especificação OpenAPI nos tipos de proxies de API a seguir: reverso ou sem destino.

O que é uma especificação de OpenAPI?

   "A Iniciativa de API aberta (OAI, na sigla em inglês) tem como foco criar, evoluir e promover um formato de descrição de API neutra de fornecedor com base na especificação Swagger." Para mais informações, consulte a Iniciativa OpenAPI.

Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Gravada em formato JSON ou YAML, uma especificação de OpenAPI pode ser lida por máquinas, mas também é fácil de ler e entender para nós, humanos. A especificação descreve elementos da API, como o caminho base, caminhos e verbos, cabeçalhos, parâmetros de consulta, operações, tipos de conteúdo, descrições de resposta e muito mais. Além disso, uma especificação de OpenAPI é comumente usada para gerar a documentação da API.

O fragmento a seguir de uma especificação OpenAPI descreve o serviço de destino simulado da Apigee, http://mocktarget.apigee.net (em inglês). Para mais informações, consulte Especificação OpenAPI para a amostra helloworld.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Com o assistente de criação de proxy, é possível importar uma especificação de OpenAPI e usá-la para gerar um proxy de API. Depois que o proxy for gerado, será possível usar a IU da Apigee para desenvolvê-lo ainda mais ao adicionar políticas, implementar código personalizado etc., assim como qualquer proxy da Apigee.

Como criar um proxy de API de uma especificação da OpenAPI

Crie proxies de API com base em uma especificação de OpenAPI. Com apenas alguns cliques, você terá um proxy de API com os caminhos, parâmetros, fluxos condicionais e endpoints de destino gerados automaticamente. Em seguida, será possível adicionar recursos como segurança OAuth, limitação de taxa e armazenamento em cache.

No assistente de criação de proxy, clique em Use OpenAPI Spec e siga o assistente para criar um proxy reverso ou sem destino com base em uma especificação da OpenAPI. Para detalhes, consulte Criar um proxy de API com base em uma especificação de OpenAPI.

Como criar uma nova revisão de um proxy de API

Crie uma nova revisão de um proxy de API, conforme descrito abaixo.

Para criar uma nova revisão de um proxy de API, execute as seguintes etapas:

1. Faça login na IU da Apigee.
2. Na barra de navegação, selecione Develop > API Proxies.
3. Clique no proxy de API na lista que você quer copiar.

4. Clique na guia Desenvolver.

5. Selecione o botão Save e selecione Save as New Revision.

Como fazer backup de um proxy de API

É possível fazer backup de um proxy de API como um conjunto de arquivos XML em um pacote. Depois de exportar para um pacote, é possível importar o proxy de API para um novo proxy, conforme descrito em Como importar um proxy de API de um pacote anteriormente nesta seção. Para mais informações, consulte Fazer o download de proxies de API.

Como criar um proxy usando a API

Para criar um proxy de API usando a API, consulte Como criar um proxy de API.