Esta página se aplica à Apigee e à Apigee híbrida.
Confira a documentação da
Apigee Edge.
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:
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:
- Faça login na IU da Apigee.
- Na barra de navegação, selecione Develop > API Proxies.
- 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 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:
Usar caracteres curinga em caminhos de base Use um ou mais caracteres curinga |
| 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
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:
- Acesse o assistente de criação de proxy, conforme descrito anteriormente em Como criar um proxy de API usando a IU.
- Clique em Upload proxy bundle.
-
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. - Clique em Próxima.
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.
- 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.nameerequest.grpc.service.name. -
Podem ser monitorados com estas variáveis de análise da Apigee:
x_apigee_grpc_rpc_name,x_apigee_grpc_service_nameex_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.
Como usar comandos da CLI gcloud para criar um 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-12 \ --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)
- 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
- 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 - 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 - 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 --globalgcloud 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 - 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: 100Valide 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 createYOUR_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-backendYOUR_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 exportAPIGEE_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 importAPIGEE_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:
- Faça login na IU da Apigee.
- Na barra de navegação, selecione Develop > API Proxies.
- Clique no proxy de API na lista que você quer copiar.
-
Clique na guia Desenvolver.
- 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.