Esta página aplica-se ao Apigee e ao Apigee Hybrid.
Veja a documentação do
Apigee Edge.
O Apigee permite-lhe expor rapidamente serviços de back-end como APIs. Para tal, crie um proxy de API que forneça uma fachada para o serviço de back-end que quer expor. Só tem de fornecer o endereço de rede do serviço de back-end, juntamente com algumas informações que o Apigee usa para criar o proxy de API que é exposto aos programadores.
O proxy de API desvincula a implementação do serviço de back-end da API que os programadores usam. Isto protege os programadores de alterações futuras aos seus serviços de back-end. À medida que atualiza os serviços de back-end, os programadores, isolados dessas alterações, podem continuar a chamar a API sem interrupções.
Este tópico fornece informações sobre os vários tipos de proxies e as respetivas definições. Para ver instruções passo a passo sobre como criar proxies, consulte os seguintes tópicos:
Criar um proxy de API através da IU
A forma mais fácil de criar um proxy de API é usar o assistente Criar proxy.
IU do Apigee na Cloud Console
-
Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.
- Clique em + Criar.
IU clássica
Para aceder ao assistente Create Proxy através da IU do Apigee, siga estes passos:
- Inicie sessão na IU do Apigee.
- Na barra de navegação, selecione Desenvolver > Proxies de API.
- Clique em Criar novo.
O assistente Criar proxy é apresentado e orienta-o pelos passos para gerar e adicionar funcionalidades mínimas a um proxy de API.
A primeira página do assistente permite-lhe criar um proxy de API a partir das seguintes origens:
Tipo | Descrição |
---|---|
Proxy reverso (mais comum) |
Um proxy de API que encaminha pedidos de entrada para serviços de back-end HTTP existentes. Pode ser uma API JSON ou XML. Consulte a secção Criar um proxy inverso para um serviço HTTP mais adiante nesta secção. Clique em Usar especificação OpenAPI para gerar o proxy a partir de uma especificação OpenAPI válida. Para mais informações sobre esta opção, consulte a secção Usar especificações da OpenAPI para gerar proxies mais adiante nesta secção. |
Sem objetivo |
Um proxy de API sem um back-end de API ("sem destino"). Semelhante à criação de um proxy inverso para um serviço HTTP descrito anteriormente, exceto que não especifica uma API existente quando define os detalhes do proxy de API. Clique em Usar especificação OpenAPI para gerar o proxy a partir de uma especificação OpenAPI válida. Para mais informações sobre esta opção, consulte a secção Usar especificações da OpenAPI para gerar proxies mais adiante nesta secção. |
Carregue o pacote de proxy | Um pacote de proxy de API existente (por exemplo, um dos proxies de API de exemplo disponíveis no GitHub). Consulte o artigo Importar um proxy de API a partir de um pacote de proxy de API. |
Proxy com eventos enviados pelo servidor (SSE) | Um proxy de API que inclui um EventFlow para eventos enviados pelo servidor (SSE) de streaming.
Para mais informações, consulte o artigo Streaming de eventos enviados pelo servidor. |
As secções seguintes abordam os detalhes de cada tipo de proxy.
Criar um proxy reverso para um serviço HTTP
O Apigee gera proxies inversos com base nas seguintes informações:
- URL do serviço de back-end.
- Caminho do URI que identifica de forma exclusiva a API que vai ser exposta pelo proxy de API às apps de consumo.
Normalmente, o URL do serviço de back-end representa uma aplicação ativada para serviços pertencente à sua organização. Também pode apontar para uma API disponível publicamente. A API ou o serviço podem estar sob o seu controlo (por exemplo, uma aplicação de RH interna ou uma aplicação Rails na nuvem) ou podem ser uma API ou um serviço de terceiros (por exemplo, o Twitter ou o Instagram).
Os seguintes detalhes do proxy estão disponíveis depois de aceder ao assistente Criar proxy e selecionar um tipo de proxy:
Campo | Descrição |
---|---|
Nome | Nome apresentado para a sua API. Especifique carateres alfanuméricos, um traço (-) ou um sublinhado (_). |
Caminho base |
Fragmento do URI apresentado após o endereço Após o caminho base, encontram-se os URLs de recursos adicionais. A estrutura de URL completa que os clientes usam para chamar o proxy de API é a seguinte:
Use carateres universais em caminhos base Use um ou mais carateres universais nos caminhos base do proxy de API para
preparar os seus proxies de API para o futuro. |
Descrição | (Opcional) Descrição da API. |
Destino (API existente) | URL do serviço de back-end que este proxy de API invoca. |
Importar um proxy de API a partir de um pacote de proxy de API
Muitas vezes, define os proxies de API como uma coleção de ficheiros XML, juntamente com quaisquer outros ficheiros de apoio. Ao definir os seus proxies de API como um conjunto de ficheiros externos ao Apigee, pode mantê-los num sistema de controlo de origem e, em seguida, importá-los para o Apigee para testes e implementação.
Para importar proxies de API a partir de um pacote de proxies de API, siga estes passos:
- Aceda ao assistente Criar proxy, conforme descrito no artigo Criar um proxy de API através da IU.
- Especifique os detalhes do pacote de proxy de API.
- No menu Modelo de proxy, selecione Carregar pacote de proxy.
- Na secção Detalhes do proxy, introduza o Nome do proxy, carregue o ficheiro ZIP e clique em Seguinte.
- Na secção Implementar, selecione os ambientes de implementação, se quiser, e clique em Criar.
- Clique em Carregar pacote de proxy.
-
Na página Carregar pacote de proxy no assistente de proxy, introduza as seguintes informações:
Campo Descrição Pacote ZIP Ficheiro ZIP que contém a configuração do proxy de API. Arraste e largue ou clique para navegar até ao ficheiro. Nome Nome apresentado para a sua API. A predefinição é o nome do ficheiro ZIP sem a extensão. - Clicar em Seguinte.
Na página Resumo, selecione os ambientes de implementação, se quiser, e clique em Criar e implementar.
É apresentada uma confirmação a indicar que o novo proxy de API foi criado com êxito.
- Clique em Editar proxy para apresentar a página de detalhes do proxy de API.
IU do Apigee na Cloud Console
IU clássica
Criar proxies de API gRPC
Além dos proxies de API REST, o Apigee suporta proxies de API gRPC apenas com suporte de transferência neste momento. Com a compatibilidade com a passagem direta, a carga útil gRPC é, em si mesma, opaca para o Apigee, e o tráfego é encaminhado do cliente gRPC para o servidor de destino gRPC pré-configurado na configuração de destino.Neste momento, os proxies de API gRPC da Apigee:
- Suporte pedidos gRPC unários.
- Não é possível usar políticas que afetem a carga útil.
- Pode ser usado em produtos de API que não estão associados a proxies GraphQL ou REST. API As quotas específicas do produto e outras definições de funcionamento aplicam-se a todos os proxies no produto.
- Não são suportados no Apigee hybrid.
- Use duas variáveis de fluxo específicas do gRPC:
request.grpc.rpc.name
erequest.grpc.service.name
. -
Pode ser monitorizado com estas variáveis do Apigee Analytics específicas do gRPC:
x_apigee_grpc_rpc_name
,x_apigee_grpc_service_name
ex_apigee_grpc_status
. - Devolver códigos de estado gRPC.
Também tem de configurar o equilibrador de carga para suportar gRPC. Consulte os artigos Usar o gRPC com as suas aplicações e Usar comandos da CLI gcloud para criar encaminhamento para o gRPC.
Para criar um proxy de API gRPC, primeiro defina um servidor de destino gRPC (consulte Criar TargetServers) e, em seguida, especifique esse servidor de destino quando criar o novo proxy.
Usar comandos da CLI gcloud para criar encaminhamento para gRPC
Esta secção mostra comandos de exemplo para criar encaminhamento para 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 secção não é um guia abrangente para criar o encaminhamento. Estes exemplos podem não ser adequados para todos os exemplos de utilização. Além disso, estas instruções pressupõem que tem familiaridade com o encaminhamento externo (MIG) e a configuração gRPC do balanceador de carga do Google Cloud.
Defina variáveis de ambiente
Estas variáveis de ambiente são usadas nos comandos nas subsecçõ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
Adicionar segurança
A segurança do proxy é alcançada através da adição de uma política ao seu proxy. Para mais informações sobre políticas, consulte o artigo O que é uma política. Para mais informações sobre segurança, consulte o artigo Proteger um proxy.
Para adicionar uma política de segurança ao seu proxy:
Apigee na Cloud Console
- Crie um proxy conforme descrito no artigo Criar um proxy de API.
- Adicione uma política de segurança, conforme descrito numa das secções indicadas em Proteger um proxy. As políticas de segurança mais comuns usadas são as chaves da API e o OAuth2.
IU do Apigee Classic
Na página Políticas comuns do assistente Criar proxy, selecione o tipo de autorização de segurança que quer adicionar. A tabela seguinte resume as opções disponíveis:
Autorização de segurança | Descrição |
---|---|
Chave de API | Adiciona uma validação simples da chave da API ao proxy da API que está a definir. Em resposta, a plataforma de API adiciona uma política VerifyAPIKey e uma política AssignMessage ao seu proxy de API. A política VerifyAPIKey valida as chaves de API apresentadas pelas apps que fazem pedidos. A política AssignMessage remove a chave da API, fornecida na chamada da API como um parâmetro de consulta, do pedido encaminhado para o servidor de back-end. |
OAuth 2.0 | Adiciona autenticação baseada no OAuth 2.0 ao seu proxy de API. O Apigee adiciona automaticamente as seguintes políticas ao seu proxy de API: uma política para validar um token de acesso e outra política para remover o token de acesso da mensagem antes de a encaminhar para o seu serviço de back-end. Para saber como obter um token de acesso, consulte o artigo OAuth. |
Passar (sem autorização) | Não é necessária autorização. Os pedidos são transmitidos ao back-end sem verificações de segurança no Apigee. |
Adicionar suporte para CORS
A partilha de recursos de origem cruzada (CORS) é um mecanismo padrão que permite que um navegador de Internet faça pedidos diretos a outro domínio. A norma CORS define um conjunto de cabeçalhos HTTP que os navegadores e os servidores Web usam para implementar a comunicação entre domínios.
Pode adicionar compatibilidade com CORS adicionando a política CORS ao request PreFlow do ProxyEndpoint.
Para obter informações mais detalhadas sobre o suporte de CORS, incluindo a adição de suporte de verificação prévia de CORS a um proxy, consulte o artigo Adicionar suporte de CORS a um proxy de API.
Adicionar quotas
As quotas protegem o seu serviço de back-end contra tráfego elevado em Quota. Consulte as quotas. (Não disponível se a autorização de encaminhamento estiver selecionada.)
Usar especificações da OpenAPI para gerar proxies
Esta secção aborda a opção Usar OpenAPI, que está disponível para gerar a partir de uma especificação OpenAPI os seguintes tipos de proxies de API: reverso ou sem destino.
O que é uma especificação OpenAPI?
"A Open API Initiative (OAI) está focada na criação, evolução e promoção de um formato de descrição de API neutro em relação ao fornecedor
com base na especificação Swagger." Para mais informações, consulte o artigo
OpenAPI Initiative.
Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Escrita no formato JSON ou YAML, uma especificação OpenAPI é legível por computador, mas também é fácil de ler e compreender para os humanos. A especificação descreve elementos da API, como o caminho base, os caminhos e os verbos, os cabeçalhos, os parâmetros de consulta, as operações, os tipos de conteúdo, as descrições das respostas e muito mais. Além disso, uma especificação OpenAPI é usada frequentemente para gerar documentação da API.
O fragmento seguinte de uma especificação OpenAPI descreve o serviço de destino simulado do Apigee, http://mocktarget.apigee.net. Para mais informações, consulte a especificação OpenAPI para o exemplo 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 ...
Através do assistente Criar proxy, pode importar uma especificação OpenAPI e usá-la para gerar um proxy de API. Depois de gerar o proxy, pode usar a IU do Apigee para o desenvolver ainda mais, adicionando políticas, implementando código personalizado, etc., tal como qualquer proxy do Apigee.
Criar um proxy de API a partir de uma especificação OpenAPI
Crie os seus proxies de API a partir de uma especificação OpenAPI. Com apenas alguns cliques, tem um proxy de API com os caminhos, os parâmetros, os fluxos condicionais e os pontos finais de destino gerados automaticamente. Em seguida, pode adicionar funcionalidades como segurança OAuth, limitação de taxa e colocação em cache.
No assistente Criar proxy, clique em Usar especificação OpenAPI e siga o assistente para criar um proxy inverso ou sem destino a partir de uma especificação OpenAPI. Para obter detalhes, consulte o artigo Criar um proxy de API a partir de uma especificação OpenAPI.
Criar uma nova revisão de um proxy de API
Para criar uma nova revisão de um proxy de API, siga estes passos:
- Abra a IU do Apigee.
- Inicie sessão na IU do Apigee.
- Na barra de navegação, selecione Desenvolver > Proxies de API.
- Clique no proxy de API na lista que quer copiar.
-
Clique no separador Desenvolver.
- Selecione o botão Guardar e, de seguida, Guardar como nova revisão.
Apigee na Cloud Console
Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.
IU do Apigee Classic
Fazer uma cópia de segurança de um proxy de API
Pode fazer uma cópia de segurança de um proxy de API existente como um conjunto de ficheiros XML num pacote de proxy de API. Depois de exportado para um pacote, pode importar o proxy de API para um novo proxy, conforme descrito em Importar um proxy de API de um pacote de proxy de API anteriormente nesta secção. Para mais informações, consulte o artigo Transfira proxies de API.
Criar um proxy de API através da API
Para criar um proxy de API através da API, consulte o artigo Criar um proxy de API.
Acerca da ausência de proxies de destino
Os proxies de destino no Apigee são úteis quando quer processar pedidos no próprio Apigee sem os encaminhar para um serviço de back-end. É importante compreender quando esta abordagem é adequada.
Exemplos de utilização comuns
- Interagir com dados geridos pelo Apigee: Um proxy sem destino é útil nos casos em que só precisa de interagir com dados geridos pelo Apigee, como dados armazenados num mapa de chave-valor (KVM) ou na cache do Apigee. Por exemplo, pode usar um proxy sem destino para obter dados, como dados de sessão do utilizador ou dados de configuração, do KVM. Neste caso, não é necessário chamar um serviço de back-end. Só precisa de uma política KeyValueMapOperations no fluxo do proxy. Por exemplo, pode querer que o autor da chamada peça que a cache seja limpa. Pode fazê-lo invocando a política InvalidateCache, sem necessidade de estabelecer ligação a um destino.
- Usar APIs simuladas: pode criar APIs simuladas para simular o comportamento da API antes de a implementação de back-end estar concluída, o que permite que o desenvolvimento de front-end avance de forma independente. Para saber mais sobre a criação de APIs simuladas, consulte o proxy de API simulada OpenAPI.
- Gestão de tokens: o Apigee pode emitir tokens OAuthV2, o que é normalmente feito através de um proxy sem destino.
- Testar o comportamento das políticas: um proxy sem destino pode ser útil quando quer experimentar políticas do Apigee para testar o respetivo comportamento.