GSP844

Visão geral

A Apigee é uma plataforma para desenvolvimento e gerenciamento de APIs. Ela pode ajudar você a proteger o acesso às suas APIs e limitar a taxa de acesso a elas. A Apigee também oferece recursos que são usados para proteger o acesso interno aos dados da API.

Neste laboratório, você vai criar uma API que exige tokens OAuth para acesso. Você vai usar a política SpikeArrest para limitar a taxa de chamadas de API por aplicativo, além de variáveis particulares e mascaramento de dados para ocultar dados sensíveis de usuários que depuram o tráfego da API.

Objetivos

Neste laboratório, você vai aprender a fazer o seguinte:

• Proteger o acesso às APIs exigindo um token OAuth.
• Limitar a taxa geral de tráfego e a taxa por aplicativo com a política SpikeArrest.
• Usar variáveis particulares e mascaramento de dados para ocultar dados sensíveis durante a depuração de chamadas de API.
• Restringir as chamadas ao back-end a recursos especificados.
• Reescrever mensagens de erro de back-end para proteção contra vazamento de dados.

Configuração e requisitos

Antes de clicar no botão Começar o Laboratório

Leia estas instruções. Os laboratórios são cronometrados e não podem ser pausados. O timer é ativado quando você clica em Iniciar laboratório e mostra por quanto tempo os recursos do Google Cloud vão ficar disponíveis.

Este laboratório prático permite que você realize as atividades em um ambiente real de nuvem, e não em uma simulação ou demonstração. Você vai receber novas credenciais temporárias para fazer login e acessar o Google Cloud durante o laboratório.

Confira os requisitos para concluir o laboratório:

• Acesso a um navegador de Internet padrão (recomendamos o Chrome).

Observação: para executar este laboratório, use o modo de navegação anônima (recomendado) ou uma janela anônima do navegador. Isso evita conflitos entre sua conta pessoal e de estudante, o que poderia causar cobranças extras na sua conta pessoal.

• Tempo para concluir o laboratório: não se esqueça que, depois de começar, não será possível pausar o laboratório.

Observação: use apenas a conta de estudante neste laboratório. Se usar outra conta do Google Cloud, você poderá receber cobranças nela. Observação: recomendamos usar uma nova janela anônima para realizar este laboratório.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Ativar o Cloud Shell

O Cloud Shell é uma máquina virtual com várias ferramentas de desenvolvimento. Ele tem um diretório principal permanente de 5 GB e é executado no Google Cloud. O Cloud Shell oferece acesso de linha de comando aos recursos do Google Cloud.

1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.

2. Clique nas seguintes janelas:

   • Continue na janela de informações do Cloud Shell.
   • Autorize o Cloud Shell a usar suas credenciais para fazer chamadas de APIs do Google Cloud.

Depois de se conectar, você verá que sua conta já está autenticada e que o projeto está configurado com seu Project_ID, . A saída contém uma linha que declara o projeto PROJECT_ID para esta sessão:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

A gcloud é a ferramenta de linha de comando do Google Cloud. Ela vem pré-instalada no Cloud Shell e aceita preenchimento com tabulação.

3. (Opcional) É possível listar o nome da conta ativa usando este comando:

gcloud auth list

4. Clique em Autorizar.

Saída:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Opcional) É possível listar o ID do projeto usando este comando:

gcloud config list project

Saída:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Observação: consulte a documentação completa da gcloud no Google Cloud no guia de visão geral da gcloud CLI.

Abrir o console da Apigee

Para fazer isso:

• No campo Pesquisar no console do Google Cloud, digite Apigee e clique em gerenciamento de APIs da Apigee nos resultados da pesquisa.

O console da Apigee será aberto, e a página de destino vai mostrar links rápidos para locais usados com frequência.

• No Menu de navegação (), ao lado de Apigee, clique em Favorito ().

A Apigee foi adicionada como favorita ao menu de navegação.

Tarefa 1: configurar um proxy para o serviço de back-end usando um proxy de API da Apigee

Nesta tarefa, você vai criar um proxy de API da Apigee que vai funcionar como uma fachada para um serviço de back-end. O proxy de API vai usar uma conta de serviço para fornecer tokens de identidade do OpenID Connect ao serviço Cloud Run.

Um serviço de back-end chamado simplebank-rest já foi criado e implantado no Cloud Run. Uma conta de serviço também foi criada para você.

Criar o proxy da Apigee

1. No Cloud Shell, use o comando abaixo para recuperar o URL do serviço de back-end:

   gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)'

   Salve esse URL para usá-lo ao criar o proxy de API.

2. Acesse a interface da Apigee no console do Cloud.

3. No menu de navegação à esquerda, selecione Desenvolvimento de proxies > Proxies de API.

4. Para criar um proxy usando o assistente de proxy, clique em + Criar.

   Você vai criar um proxy reverso para o serviço de back-end. Esse proxy de API vai usar uma especificação OpenAPI para criar uma estrutura da API.

5. Na caixa Modelo de proxy, em Modelo de especificação OpenAPI, selecione Proxy reverso (mais comum).

6. Para Arquivo OpenAPI, abra o URL em um navegador e o arquivo YAML de especificação OpenAPI será baixado no seu computador:

   https://storage.googleapis.com/spls/gsp844/simplebank-backend.yaml

7. Clique em Procurar e, para Arquivo OpenAPI, selecione o arquivo baixado no computador e clique em Avançar.

8. Especifique as informações abaixo em Detalhes do proxy:

   Propriedade	Valor
   Nome do proxy	bank-v1
   Caminho base	/bank/v1
   Descrição	API somente leitura do SimpleBank
   Destino (API atual)	URL do back-end

   Observação: verifique se você está usando /bank/v1 como caminho base, não /bank-v1.

   O destino precisa ser o URL do back-end que você conferiu anteriormente na tarefa. O destino será parecido com este:

   https://simplebank-rest-nu7rb74j5a-uw.a.run.app

9. Clique em Avançar.

10. Mantenha as outras configurações como padrão e clique em Criar.

11. Clique na guia Desenvolver.

    Observação: os fluxos foram adicionados ao endpoint de proxy, cada um especificando um verbo e uma condição de caminho de uma das operações da especificação OpenAPI.

Modificar o destino do envio de um token de identidade do OpenID Connect

Como o serviço de back-end foi implantado para exigir o acesso autenticado, não é possível chamá-lo sem um token de identidade do OpenID Connect válido.

O HTTPTargetConnection especifica o destino de back-end do serviço.

1. No menu de navegação do proxy, acesse a seção Endpoints de destino e clique em PreFlow.

2. Localize o código abaixo (seu URL será diferente):

   <HTTPTargetConnection> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> </HTTPTargetConnection> Observação: se a seção HTTPTargetConnection não aparecer, clique em PreFlow na seção Endpoints de destino, não na seção Endpoints de proxy.

3. Abaixo do URL, adicione uma seção Autenticação parecida com esta:

   <Authentication> <GoogleIDToken> <Audience>AUDIENCE</Audience> </GoogleIDToken> </Authentication>

4. Substitua AUDIENCE pelo valor do URL presente na seção HTTPTargetConnection. Seu código vai ser parecido com este, mas os elementos URL e Audience terão seu URL específico:

   <TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> <Authentication> <GoogleIDToken> <Audience>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</Audience> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </TargetEndpoint>

5. Clique em Salvar.

Clique em Verificar meu progresso para conferir o objetivo. Criar o proxy de API

Tarefa 2: adicionar OAuth ao proxy de API

Nesta tarefa, você vai adicionar uma política OAuthV2 ao proxy de API. Uma política OAuthV2 que usa a operação VerifyJWTAccessToken aplica a verificação de tokens de acesso no ambiente de execução para permitir que apenas aplicativos com um token de acesso OAuth válido acessem a API.

A política OAuthV2 pode criar e verificar tokens opacos e JSON Web Tokens (JWTs). Esse proxy de API vai usar JWTs para os tokens de acesso.

Um conjunto de propriedades será usado para armazenar o secret de assinatura utilizado na criação e verificação do JWT.

Criar o secret de assinatura no conjunto de propriedades

O JWT será assinado usando um código de autenticação de mensagem baseado em hash (HMAC). Esse tipo de assinatura criptográfica exige um secret.

1. No menu de navegação do proxy, ao lado de Recursos, clique em +.

2. No menu suspenso Tipo de recurso, selecione Property Set.

3. Especifique oauth.properties em Nome do recurso e clique em Adicionar.

4. No painel de código de oauth.properties, adicione a seguinte propriedade:

   secret=thisisnotagoodsecret,useabettersecretinproduction

   Esse valor pode ser acessado no código usando a variável de fluxo propertyset.oauth.secret.

   Observação: os valores do conjunto de propriedades são armazenados em texto simples. Em um ambiente de produção, você armazenaria o secret do HMAC em um local criptografado e usaria um secret mais seguro (aleatório).

Adicionar uma política AssignMessage para recuperar o valor do conjunto de propriedades

O secret de assinatura precisa ser fornecido à política OAuth em uma variável particular, mas a variável propertyset.oauth.secret não é particular. Essa política AssignMessage vai criar uma variável particular com base na variável do conjunto de propriedades.

1. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por padrão e clique em PreFlow.

   O pré-fluxo de solicitação no endpoint de proxy padrão é o primeiro fluxo executado quando uma solicitação chega ao proxy de API.

   A política OAuthV2 exige o secret e é executada logo de início no proxy de API.

2. No painel Fluxo, clique no botão + ao lado de PreFlow no fluxo de solicitação.

3. Selecione Criar política e, no menu suspenso Selecionar política, escolha Atribuir mensagem na seção Mediação. Em seguida, defina o Nome de exibição e o Nome como AM-GetSecret.

4. Clique em Adicionar. Clique em AM-GetSecret em Políticas no menu de navegação.

   A configuração da política AssignMessage é mostrada no painel Código.

5. Mude a configuração da política para o seguinte:

   <AssignMessage name="AM-GetSecret"> <AssignVariable> <Name>private.secretkey</Name> <Ref>propertyset.oauth.secret</Ref> </AssignVariable> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>

   A configuração AssignVariable copia a variável propertyset.oauth.secret para a variável private.secretkey.

   A configuração IgnoreUnresolvedVariables faz com que a política AssignMessage gere uma falha quando não for possível resolver propertyset.oauth.secret.

Adicionar a política OAuthV2 para verificar um token

1. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por padrão e clique em PreFlow.

   A política OAuthV2 precisa ser executada depois da política AssignMessage.

2. No painel Fluxo, clique no botão + ao lado de PreFlow no fluxo de solicitação.

3. Selecione Criar política e, no menu suspenso Selecionar política, escolha OAuth v2.0 na seção Segurança. Em seguida, defina o Nome de exibição e o Nome como OA-VerifyToken.

4. Clique em Adicionar e em OA-VerifyToken em Políticas no menu de navegação.

   A configuração da política OAuthV2 é mostrada no painel Código.

5. Mude a configuração da política OAuthV2 para o seguinte:

   <OAuthV2 name="OA-VerifyToken"> <Operation>VerifyJWTAccessToken</Operation> <Algorithm>HS256</Algorithm> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> </OAuthV2>

   A configuração especifica que o token de acesso JWT vai usar o algoritmo HS256 (HMAC-SHA256), com a variável particular criada na política AssignMessage como chave secreta.

6. Clique em Salvar.

Clique em Verificar meu progresso para conferir o objetivo. Adicionar políticas para verificar tokens

Tarefa 3: adicionar políticas para gerar tokens

Outro endpoint de proxy também vai ser adicionado ao proxy de API para permitir a criação dos tokens JWT.

Adicionar um endpoint de proxy para operações de token

Em geral, outro proxy é criado nos ambientes de produção para gerar tokens. Neste laboratório, você vai criar o fluxo de geração de tokens em outro endpoint de proxy no mesmo proxy de API.

1. No menu de navegação do proxy, na linha Endpoints de proxy, clique no botão +.

   Observação: não clique no botão + ao lado de Padrão.

   Isso cria um endpoint de proxy que é usado ao gerar um JWT.

2. Em Nome, especifique token e clique em Adicionar.

   O novo endpoint de proxy chamado token vai aparecer no painel Código.

3. Mude toda a configuração do fluxo de token de:

   <ProxyEndpoint name="token"> . . . </ProxyEndpoint>

   para:

   <ProxyEndpoint name="token"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <Flows/> <HTTPProxyConnection> <BasePath>/token</BasePath> </HTTPProxyConnection> <RouteRule name="noTarget"/> </ProxyEndpoint>

4. Clique em Salvar.

   Essa configuração atualizada resulta em duas mudanças específicas:

   • O BasePath está definido como /token. Esse é o caminho base que será usado ao criar um token.
   • A RouteRule não faz mais referência a um endpoint de destino. O proxy de API cria um token sem chamar o serviço de back-end.

Criar um fluxo para gerar um token

1. No fluxo do proxy, acesse a seção Endpoints do proxy: token e clique em + ao lado de /token.

2. Para o novo fluxo condicional, especifique os seguintes valores:

   Propriedade	Valor
   Nome do fluxo	generateToken
   Tipo de condição	Selecione Personalizado.

3. Para Condição, especifique este valor:

   (proxy.pathsuffix MatchesPath "/") and (request.verb = "POST") and (request.formparam.grant_type = "client_credentials")

   Apenas solicitações de token com credenciais de cliente válidas são permitidas.

4. Clique em Adicionar.

Anexar a política AssignMessage para recuperar o valor do conjunto de propriedades

A política OAuthV2 que vai gerar tokens também precisa de acesso à variável private.secretkey.

1. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por token e clique em generateToken.

2. No painel Fluxo, clique no botão + à direita de generateToken no fluxo de solicitação.

3. Em Selecionar política, escolha Selecionar política atual e clique em AM-GetSecret.

4. Clique em Adicionar.

   A mesma política AssignMessage é anexada ao endpoint do proxy de token PreFlow.

Adicionar uma política OAuthV2 para gerar um token

1. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por token e clique em generateToken.

2. No painel Fluxo, clique no botão + à direita de generateToken no fluxo de solicitação.

3. Em Selecionar política, escolha Criar política e clique em OAuth v2.0 na seção Segurança. Em seguida, defina o Nome de exibição e o Nome como OA-GenerateToken.

4. Clique em Adicionar e em OA-GenerateToken em Políticas.

   A configuração da política OAuthV2 é mostrada no painel Código.

5. Mude a configuração da política OAuthV2 para o seguinte:

   <OAuthV2 name="OA-GenerateToken"> <Operation>GenerateJWTAccessToken</Operation> <Algorithm>HS256</Algorithm> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <SupportedGrantTypes> <!-- pass client_id and client_secret via basic auth header --> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <!-- 1800000 ms = 1800 s = 30 min --> <ExpiresIn>1800000</ExpiresIn> <GenerateResponse enabled="true"/> <RFCCompliantRequestResponse>true</RFCCompliantRequestResponse> </OAuthV2>

   Essa configuração permite a criação de um token JWT OAuth que expira em 30 minutos.

Gerar uma falha para uma solicitação de token inválida

1. No fluxo do proxy, acesse a seção Endpoints do proxy: token e clique em + ao lado de /token.

2. Para o novo fluxo condicional, especifique os seguintes valores:

   Propriedade	Valor
   Nome do fluxo	invalidRequest
   Tipo de condição	Selecione Personalizado.
   Condição	DELETETHIS

   A condição será excluída assim que o fluxo for adicionado, porque qualquer solicitação generateToken inválida precisa passar por ele.

3. Clique em Adicionar.

4. No fluxo invalidRequest, remova esta linha:

   <Condition>DELETETHIS</Condition>

5. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por token e clique em invalidRequest.

6. No painel Fluxo, clique no botão + ao lado de invalidRequest no fluxo de solicitação.

7. Selecione Criar política e Gerar falha na seção Mediação. Em seguida, defina o Nome de exibição e o Nome como RF-InvalidTokenRequest.

8. Clique em Adicionar e em RF-InvalidTokenRequest em Políticas.

   A configuração da política RaiseFault é mostrada no painel Código.

9. Mude a configuração da política RaiseFault para o seguinte:

   <RaiseFault name="RF-InvalidTokenRequest"> <FaultResponse> <Set> <StatusCode>400</StatusCode> <ReasonPhrase>Bad Request</ReasonPhrase> <Payload contentType="application/json">{ "error":"Bad request: use POST /token" }</Payload> </Set> </FaultResponse> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </RaiseFault>

   Isso vai criar uma resposta 400 Bad Request se a solicitação for inválida.

10. Clique em Salvar.

Clique em Verificar meu progresso para conferir o objetivo. Adicionar políticas para gerar tokens

Tarefa 4: implantar o proxy OAuth

Nesta tarefa, você vai implantar o proxy de API e verificar se o acesso exige um token OAuth.

Confirmar se a instância de ambiente de execução está disponível

1. No Cloud Shell, cole e execute o seguinte conjunto de comandos:

   export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***";

   Essa série de comandos usa a API Apigee para determinar quando a instância de ambiente de execução da Apigee foi criada e o ambiente de avaliação foi anexado.

2. Aguarde até que a instância esteja pronta.

   Quando o texto ***ORG IS READY TO USE*** for mostrado, a instância estará pronta. Como é possível que a organização (org) da Apigee tenha sido criada antes de você iniciar o laboratório, talvez não seja necessário aguardar a criação da instância.

   Enquanto espera a organização ficar pronta, você pode conferir mais informações sobre OAuth, política SpikeArrest, mascaramento e ocultação de dados e tokens opacos e JWTs.

Implantar o proxy de API

1. Acesse a Apigee no console do Cloud.

2. No menu de navegação à esquerda, selecione Desenvolvimento de proxies > Proxies de API e clique em bank-v1.

3. Clique na guia Desenvolver.

4. Clique em Implantar e, em Ambiente, selecione avaliação.

   Uma caixa de diálogo vai pedir para você confirmar a implantação.

5. Em Conta de serviço, especifique o endereço de e-mail da conta de serviço:

   apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

6. Clique em Implantar e em Confirmar.

7. Clique na guia Visão geral e aguarde o status de implantação da avaliação indicar que o proxy foi implantado.

Clique em Verificar meu progresso para conferir o objetivo. Implantar o proxy de API

Testar o proxy de API

É possível chamar o ambiente de avaliação na organização da Apigee usando o nome do host eval.example.com. A entrada DNS para esse nome do host foi criada no projeto e é resolvida para o endereço IP da instância de ambiente de execução da Apigee. Essa entrada DNS foi criada em uma zona particular, o que faz com que ela seja visível apenas na rede interna.

Como o Cloud Shell não está na rede interna, os comandos do Cloud Shell não conseguem resolver essa entrada DNS. Uma máquina virtual (VM) na sua organização tem acesso ao DNS da zona particular. Uma máquina virtual chamada apigeex-test-vm foi criada automaticamente. É possível usar essa máquina para chamar o proxy de API.

1. No Cloud Shell, estabeleça uma conexão SSH com a VM de teste:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Se for necessário autorizar, clique em Autorizar.

2. Para cada pergunta feita no Cloud Shell, clique em Enter ou Return para especificar a entrada padrão.

   Sua identidade conectada é a proprietária do projeto, então o SSH para essa máquina será permitido.

   Sua sessão do Cloud Shell agora está sendo executada na VM.

3. Chame o proxy de API bank-v1 implantado no ambiente de avaliação:

   curl -i -k -X GET "https://eval.example.com/bank/v1/customers"

   A opção -k informa ao curl que ele deve ignorar a verificação do certificado TLS. Neste laboratório, o ambiente de execução da Apigee está usando um certificado autoassinado em vez de um certificado criado por uma autoridade de certificação (AC) confiável.

   Observação: não use a opção -k para ignorar a verificação de certificados em casos de uso de produção.

   Essa API tenta recuperar uma lista de clientes. Agora você vai receber uma resposta 401 Unauthorized parecida com esta:

   HTTP/2 401 content-type: application/json www-authenticate: Bearer realm="null",error="invalid_token",error_description="oauth.v2.InvalidAccessToken: Invalid access token" x-request-id: 99263881-d0f7-4495-b886-0253f28a2e05 content-length: 101 date: Tue, 11 Jan 2022 18:59:01 GMT via: 1.1 google {"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

   Essa resposta indica que o proxy de API bloqueou o acesso ao serviço de back-end porque o token de acesso não foi fornecido.

4. Insira o comando exit para sair da sessão SSH e retornar ao Cloud Shell.

Tarefa 5: adicionar um produto de API, um desenvolvedor e um aplicativo

Nesta tarefa, você vai adicionar um produto de API para fornecer acesso à API. Você também vai criar um desenvolvedor e um aplicativo a ser associado ao produto de API.

Criar um produto de API

1. Acesse a Apigee no console do Cloud.

2. No menu de navegação à esquerda, selecione Distribuição > Produtos de API.

3. Para criar um produto de API, clique em + Criar.

4. No painel Detalhes do produto, especifique o seguinte:

   Propriedade	Valor
   Nome	bank-readonly
   Nome de exibição	bank (acesso de leitura)
   Ambiente	Selecione avaliação.
   Acesso	Selecione Público.

   Mantenha marcada a opção Aprovar automaticamente solicitações de acesso.

5. Na seção Operações, clique em + Adicionar uma operação.

   As operações são usadas para especificar quais solicitações em quais proxies de API são permitidas para um aplicativo associado ao produto de API.

   Observação: verifique se o botão está na seção Operações, não em Operações do GraphQL.

6. Especifique o seguinte:

   Propriedade	Valor
   Proxy de API	Selecione o proxy de API bank-v1.
   Caminho	/**
   Métodos	select GET

   A expressão de caminho /\*\* indica que qualquer solicitação que corresponda ao caminho base será permitida.

   Em um ambiente de produção, você pode adicionar cada operação permitida separadamente, em vez de usar essa expressão de caminho curinga.

7. Clique em Salvar para salvar a operação.

8. Para salvar o produto de API, clique em Salvar na parte de cima da página Detalhes do produto.

9. Volte à página Distribuição > Produtos de API.

   O produto de API vai estar listado.

Criar um desenvolvedor de apps

Antes de criar um app, é necessário ter um desenvolvedor de apps.

1. No menu de navegação à esquerda, clique em Distribuição > Desenvolvedores.

2. Para criar um desenvolvedor de apps, clique em + Criar.

3. Especifique o seguinte:

   Propriedade	Valor
   Nome	Joe
   Sobrenome	Desenvolvedor
   Nome de usuário	joe
   E-mail	joe@example.com

4. Clique em Adicionar para criar o desenvolvedor de apps.

Criar um app com acesso a bank-v1

1. No menu de navegação à esquerda, clique em Distribuição > Apps.

2. Para criar um app, clique em + Criar.

3. No painel Detalhes do app, especifique o seguinte:

   Propriedade	Valor
   Nome	readonly-app
   Desenvolvedor	Selecione joe@example.com.

4. No painel Credenciais, clique em Adicionar credenciais > Adicionar produtos, escolha bank (acesso de leitura) no menu suspenso e selecione Adicionar.

5. Clique em Criar no canto superior direito para criar o app.

   A chave e o secret agora estão configurados para o app.

6. Clique nos ícones Mostrar ao lado de Chave e Secret.

   Essa API exige um token de acesso OAuth. A chave e o secret são usados como as credenciais do app, permitindo que ele crie um token de acesso OAuth.

Clique em Verificar meu progresso para conferir o objetivo. Adicionar o produto de API e criar um app

Testar a API

1. No Cloud Shell, estabeleça uma conexão SSH com a VM de teste:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Se for necessário autorizar, clique em Autorizar.

   Sua sessão do Cloud Shell agora está sendo executada na VM.

2. Para ter acesso ao secret e à chave do cliente do aplicativo, execute os seguintes comandos:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null); echo "PROJECT_ID=${PROJECT_ID}" export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output); echo "CONSUMER_KEY=${CONSUMER_KEY}" export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output); echo "CONSUMER_SECRET=${CONSUMER_SECRET}"

   O primeiro comando lê a configuração da gcloud para ter acesso ao projeto atual. O segundo e o terceiro comandos recuperam a chave do cliente e o secret usando a API Apigee. A solicitação é autorizada porque você envia um token de acesso com as permissões do usuário conectado.

   Para o tipo de concessão de credenciais do cliente OAuth, o aplicativo cliente precisa enviar o secret e a chave do cliente em um cabeçalho de autorização para gerar um token de acesso.

3. Para gerar um token de acesso JWT, execute o seguinte comando:

   export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"); echo ${TOKEN_RESPONSE} export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output); echo "JWT_TOKEN=${JWT_TOKEN}"

   O primeiro comando chama o endpoint de token e salva a resposta. Em seguida, o token é extraído da resposta JSON e armazenado em JWT_TOKEN.

4. Para testar uma solicitação usando o token JWT, use o seguinte comando:

   curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers"

   A chamada de API agora vai retornar uma lista de clientes.

   Observação: se você receber uma resposta que indica que o cliente não tem permissão para acessar o URL solicitado, verifique se o público-alvo foi definido corretamente na tarefa 1.

5. Insira o comando exit para sair da sessão SSH e retornar ao Cloud Shell.

Tarefa 6: adicionar limitação de taxa

Nesta tarefa, você vai adicionar uma política SpikeArrest que vai usar a configuração de cota do produto de API para limitar a taxa de chamadas à API.

Na política SpikeArrest, é possível especificar uma taxa máxima de tráfego permitida para proteger suas APIs e seus back-ends contra aumentos de tráfego. Essa política pode ser usada para garantir que o back-end não seja sobrecarregado por um tráfego que não consegue processar.

Adicionar uma política SpikeArrest para geração de tokens

Essa política SpikeArrest especifica um limite de taxa geral para o tráfego de chamadas à API /token.

1. Acesse a Apigee no console do Cloud.

2. No menu de navegação à esquerda, selecione Desenvolvimento de proxies > Proxies de API e clique em bank-v1.

3. Clique na guia Desenvolver.

4. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por token e clique em PreFlow.

   A política SpikeArrest precisa ser executada antes das políticas de fluxo condicional.

5. No painel Fluxo, clique no botão + ao lado de PreFlow no fluxo de solicitação.

6. Selecione Criar política e SpikeArrest na seção Gerenciamento de tráfego. Em seguida, defina o Nome de exibição e o Nome como SA-LimitTokenRate.

7. Clique em Adicionar e em SA-LimitTokenRate na seção Políticas.

   A configuração da política SpikeArrest é mostrada no painel Código.

8. Mude a configuração da política SpikeArrest para o seguinte:

   <SpikeArrest name="SA-LimitTokenRate"> <Rate>5pm</Rate> <UseEffectiveCount>false</UseEffectiveCount> </SpikeArrest>

   A configuração especifica que a taxa máxima permitida de solicitações é de cinco por minuto. Todo o tráfego será limitado por essa política SpikeArrest.

   Observação: são usadas cinco solicitações por minuto para facilitar o teste. Em geral, os limites de SpikeArrest neste laboratório são muito baixos para cenários reais.

   Quando UseEffectiveCount está definido como false, isso significa que a política SpikeArrest está usando o algoritmo Token Bucket. É possível equilibrar o tráfego dividindo a taxa em intervalos menores. Cinco solicitações por minuto significam uma solicitação a cada um quinto de um minuto ou uma solicitação a cada 12 segundos. Quando uma segunda solicitação chega a um processador de mensagens menos de 12 segundos após a anterior, ela pode ser rejeitada.

Adicionar uma política SpikeArrest para solicitações de API

Essa política SpikeArrest especifica um limite de taxa para o tráfego de chamadas à API /bank/v1. A taxa é aplicada por aplicativo.

1. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por padrão e clique em PreFlow.

   A política SpikeArrest precisa ser executada no início da chamada, mas depois da política OAuthV2 VerifyJWTAccessToken para limitar a taxa com base no aplicativo.

2. No painel Fluxo, clique no botão + ao lado de PreFlow no fluxo de solicitação.

3. Selecione Criar política e SpikeArrest na seção Gerenciamento de tráfego. Em seguida, defina o Nome de exibição e o Nome como SA-LimitRateByApp.

4. Clique em Adicionar e em SA-LimitRateByApp na seção Políticas.

   A configuração da política SpikeArrest é mostrada no painel Código.

5. Mude a configuração da política SpikeArrest para o seguinte:

   <SpikeArrest name="SA-LimitRateByApp"> <Rate>5pm</Rate> <Identifier ref="client_id" /> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>

   Assim como a política anterior, a configuração especifica que a taxa máxima permitida de solicitações é de cinco por minuto. No entanto, essa política especifica um identificador, que mantém a taxa de SpikeArrest separadamente para cada client_id. O ID do cliente é preenchido pela política OA-VerifyToken e é exclusivo para cada aplicativo do desenvolvedor.

   Quando UseEffectiveCount está definido como true, ele especifica que a contagem de taxa deve ser mantida para todo o tráfego na região. A política mantém um contador de solicitações recebidas por período, que abrange um minuto ao usar uma taxa de solicitações por minuto. O cálculo da taxa é baseado em uma janela deslizante.

   

   Para o exemplo acima, imagine que você está usando uma taxa de 50 solicitações por minuto. Os contadores usam um período de um minuto, mas esse período seria de um segundo se a taxa tivesse sido especificada por segundo. Imagine que já se passaram 10 segundos do minuto atual. Isso é representado pela seta. O minuto anterior teve 48 solicitações e o período atual teve cinco solicitações até agora.

   Para permitir outra solicitação, a taxa precisa ser menor que 50 solicitações por minuto. Confira abaixo a taxa calculada:

   request_rate = (48 * (60-10)/60) + 6 = 46

   Como apenas 10 segundos se passaram dos 60 segundos do período atual, os outros 50 segundos são calculados usando a taxa do período anterior. Ao calcular quanto é 5/6 de 48, você chega ao resultado 40. Se uma solicitação for permitida, a contagem do período atual será 5 + 1, ou seja, 6. O cálculo da taxa de solicitação de 46 indica que a solicitação é permitida porque a taxa é menor que 50 solicitações por minuto.

6. Clique em Salvar > Salvar como nova revisão.

7. Clique em Implantar e selecione avaliação em Ambiente.

8. Em Conta de serviço, especifique o endereço de e-mail da conta de serviço:

apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

9. Clique em Implantar e em Confirmar.
10. Clique na guia Visão geral e aguarde o status de implantação da avaliação indicar que o proxy foi implantado.

Clique em Verificar meu progresso para conferir o objetivo. Adicionar a política SpikeArrest

Testar a limitação de taxa

1. No Cloud Shell, estabeleça uma conexão SSH com a VM de teste:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Se for necessário autorizar, clique em Autorizar.

   Sua sessão do Cloud Shell agora está sendo executada na VM.

2. Para ter acesso ao secret e à chave do cliente do aplicativo, execute os seguintes comandos:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null); echo "PROJECT_ID=${PROJECT_ID}" export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output); echo "CONSUMER_KEY=${CONSUMER_KEY}" export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output); echo "CONSUMER_SECRET=${CONSUMER_SECRET}"

3. Gere vários tokens de acesso executando o comando abaixo várias vezes:

   curl -i -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"

   Você vai receber rapidamente uma resposta 429 Too Many Requests, que indica que a taxa foi excedida. Como UseEffectiveCount é false para essa política, o impacto do tráfego é reduzido com o algoritmo Token Bucket. Você provavelmente vai receber a violação da SpikeArrest antes da quinta solicitação.

4. Para salvar um token de acesso JWT, execute este comando:

   export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"); echo ${TOKEN_RESPONSE} export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output); echo "JWT_TOKEN=${JWT_TOKEN}"

5. Para testar a política SpikeArrest em chamadas de API, envie repetidamente este comando:

   curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers"

   Como UseEffectiveCount é true, essa política usa o algoritmo de janela deslizante. Você provavelmente vai receber cinco solicitações antes do bloqueio.

6. Insira o comando exit para sair da sessão SSH e retornar ao Cloud Shell.

Tarefa 7: mascaramento de dados

Nesta tarefa, você vai criar uma máscara de dados para ocultar campos específicos em uma sessão de depuração.

Iniciar uma sessão de depuração

A Depuração é uma ferramenta de solução de problemas e monitoramento de proxies de API em execução na Apigee. Com ela, é possível analisar os detalhes de cada etapa durante uma chamada de API.

1. No menu de navegação à esquerda, selecione Desenvolvimento de proxies > Proxies de API e clique em bank-v1.

2. Clique na guia Depurar.

3. No painel Iniciar sessão de depuração, clique em Iniciar sessão de depuração. No menu suspenso de ambientes, selecione o ambiente de avaliação.

4. Clique em Iniciar.

   Pode demorar um pouco para a sessão de depuração começar a capturar solicitações.

   Observação: mesmo que você receba mensagens de erro em caixas vermelhas na parte de cima da tela, com descrições como "Erro ao buscar transações de depuração" ou "Erro de transação da sessão de depuração da lista", sua sessão de depuração ainda poderá funcionar corretamente.

   Você vai fazer solicitações de API e analisar a sessão de depuração.

Depurar uma solicitação

1. No Cloud Shell, estabeleça uma conexão SSH com a VM de teste:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Se for necessário autorizar, clique em Autorizar.

   Sua sessão do Cloud Shell agora está sendo executada na VM.

2. Para receber o token do aplicativo, execute estes comandos:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null); echo "PROJECT_ID=${PROJECT_ID}" export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output); echo "CONSUMER_KEY=${CONSUMER_KEY}" export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output); echo "CONSUMER_SECRET=${CONSUMER_SECRET}" export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"); echo ${TOKEN_RESPONSE} export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output); echo "JWT_TOKEN=${JWT_TOKEN}"

3. Faça esta solicitação à API:

   curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers/abe@example.org/accounts"

4. Volte à página da interface da Apigee.

   A página de depuração deve mostrar duas solicitações: uma POST (que gera o token) e uma GET (que recupera as contas de um usuário).

5. Clique na solicitação GET.

   Os detalhes dessa solicitação serão mostrados.

6. Clique na primeira política, a AM-GetSecret, que copia a variável propertyset.oauth.secret para a variável private.secretkey.

   

   Os detalhes da fase não mostram a variável particular porque as variáveis prefixadas com "private." ficam ocultas na sessão de depuração. No entanto, a variável do conjunto de propriedades tem os mesmos dados sensíveis, e pode ser útil ocultá-la de usuários que estão depurando o tráfego.

7. Clique na resposta do back-end, indicada pelo círculo à esquerda do ícone de fábrica.

   

   A resposta contém as contas do usuário, incluindo os saldos.

Criar uma máscara de depuração

1. Abra uma nova guia na mesma janela do navegador e acesse a referência da API Apigee.

   Ela fornece detalhes sobre as várias chamadas de API que podem ser usadas para gerenciar a Apigee e pode ser utilizada para fazer chamadas à API Apigee. Essa página mostra as chamadas de API organization.environments.

2. Role até a parte de baixo da página e clique em updateDebugmask.

   Essa chamada de API vai atualizar a máscara de depuração do ambiente.

3. No painel Testar esta API, use o seguinte para o parâmetro de solicitação name:

   organizations/{{{ project_0.project_id | PROJECT }}}/environments/eval/debugmask

4. Para o corpo da solicitação, insira o seguinte:

   { "responseJSONPaths": [ "$[*].balance" ], "variables": [ "propertyset.oauth.secret" ] }

   Esse payload vai mascarar a variável propertyset.oauth.secret e cada campo balance na matriz de objetos no payload da resposta.

5. Clique em Executar.

   Se uma caixa pop-up pedir para você escolher uma conta, selecione a conta de estudante.

6. Clique em Permitir para que a página use as credenciais de estudante.

Testar a máscara de depuração

1. No menu de navegação à esquerda da interface da Apigee, selecione Desenvolvimento de proxies > Proxies de API e clique em bank-v1.

2. Clique na guia Depurar.

3. No painel Iniciar sessão de depuração, selecione avaliação no menu suspenso de ambientes.

4. Clique em Iniciar.

5. No Cloud Shell, se a conexão SSH com a VM de teste tiver sido encerrada, estabeleça uma nova:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

6. Depois de receber um token, faça novamente a solicitação de API:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers/abe@example.org/accounts"

7. Volte à página de depuração na interface da Apigee e clique na solicitação GET.

8. Clique na política AM-GetSecret.

   A variável propertyset.oauth.secret foi mascarada.

   

9. Clique em Fluxo de resposta do proxy iniciado para a resposta do back-end.

   Cada campo balance é mascarado.

   

Tarefa 8: tratamento de erros

Nesta tarefa, você vai criar um fluxo condicional padrão para restringir chamadas a recursos de back-end específicos e reescrever uma mensagem de erro de back-end.

Testar a API

1. No Cloud Shell, se a conexão SSH com a VM de teste tiver sido encerrada, estabeleça uma nova:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. Digite Y para continuar e pressione ENTER duas vezes para deixar a senha longa vazia.

3. Depois de receber um token, faça uma solicitação GET para /users:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/users"

   O serviço de back-end não reconhece a solicitação GET /users e retorna uma resposta 404 parecida com esta:

   HTTP/2 404 x-powered-by: Express content-security-policy: default-src 'none' x-content-type-options: nosniff content-type: text/html; charset=utf-8 x-cloud-trace-context: 7e96528757cc5053ba4fc8853037b02d;o=1 date: Wed, 19 Jan 2022 01:49:53 GMT server: Google Frontend content-length: 144 x-request-id: 2d8c8002-3152-4fc2-a60b-1729dd5483d8 via: 1.1 google <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Error</title> </head> <body> <pre>Cannot GET /users</pre> </body> </html>

   A resposta retorna um payload HTML, que não corresponde ao formato do payload RF-InvalidTokenRequest. Além disso, uma resposta de back-end pode conter dados sensíveis. Por isso, é uma prática recomendada reescrever as respostas de erro dos serviços de back-end.

Reescrever um erro 404 Não encontrado

É possível usar as regras de falha para detectar erros e reescrever mensagens de erro.

Uma política RaiseFault será usada para definir a nova resposta.

1. Acesse a Apigee no console do Cloud.

2. No menu de navegação à esquerda, selecione Desenvolvimento de proxies > Proxies de API e clique em bank-v1.

3. Clique na guia Desenvolver.

4. No menu de navegação do proxy, ao lado de Políticas, clique em +.

5. Selecione RaiseFault na seção Mediation e defina o Nome de exibição e o Nome como RF-404NotFound.

6. Clique em Criar. Clique em RF-404NotFound na seção Políticas.

7. Mude a configuração da política RaiseFault para o seguinte:

   <RaiseFault name="RF-404NotFound"> <FaultResponse> <Remove> <Headers/> </Remove> <Set> <StatusCode>404</StatusCode> <ReasonPhrase>Not Found</ReasonPhrase> <Headers> <Header name="FaultName">{fault.name}</Header> </Headers> <Payload contentType="application/json">{ "error": "{request.verb} {proxy.pathsuffix} not found" }</Payload> </Set> </FaultResponse> <AssignTo createNew="true" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </RaiseFault>

   A seção Remover primeiro remove todos os cabeçalhos que podem ter vindo do serviço de back-end. Em seguida, a seção Definir cria a resposta. O cabeçalho FaultName foi adicionado para mostrar o valor da variável fault.name quando a falha é gerada. A variável fault.name especifica o nome da falha.

Criar a FaultRule

1. No menu de navegação do proxy, acesse a seção Endpoints de destino e clique em padrão.

   O endpoint de destino padrão contém a chamada de destino do back-end que está retornando a resposta 404. Um erro 404 é tratado como um código de falha. O endpoint vai gerar uma falha e as FaultRules especificadas no endpoint de destino poderão ser usadas para reescrever a resposta da API.

2. Na configuração TargetEndpoint, diretamente abaixo da tag TargetEndpoint, adicione a seção FaultRules abaixo:

   <FaultRules> <FaultRule name="404"> <Step> <Name>RF-404NotFound</Name> </Step> <Condition>response.status.code == 404</Condition> </FaultRule> </FaultRules>

   O início do TargetEndpoint vai ficar assim:

   <TargetEndpoint name="default"> <FaultRules> <FaultRule name="404"> <Step> <Name>RF-404NotFound</Name> </Step> <Condition>response.status.code == 404</Condition> </FaultRule> </FaultRules>

3. Clique em Salvar > Salvar como nova revisão.

4. Clique em Implantar e selecione avaliação em Ambiente.

5. Em Conta de serviço, especifique o endereço de e-mail da conta de serviço:

   apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

6. Clique em Implantar e em Confirmar.

7. Clique na guia Visão geral e aguarde o status de implantação da avaliação indicar que o proxy foi implantado.

Testar a falha na resposta do endpoint

1. No Cloud Shell, se a conexão SSH com a VM de teste tiver sido encerrada, estabeleça uma nova:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. Depois de receber um token, faça uma solicitação GET para /users:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/users"

   A resposta foi reescrita e ficou assim:

   HTTP/2 404 faultname: ErrorResponseCode content-type: application/json x-request-id: 8d9db301-b3c7-4957-816d-93e796306dfb content-length: 39 date: Tue, 18 Jan 2022 06:42:23 GMT via: 1.1 google { "error": "GET /users not found" }

   A resposta agora usa JSON. O cabeçalho faultname tem o valor ErrorResponseCode, que é o valor da variável fault.name especificada quando o destino retorna um código de falha. Assim que a resposta 404 foi recebida do serviço de back-end, uma falha foi gerada e as regras de falha do endpoint de destino foram avaliadas. Em seguida, a regra de falha 404 reescreveu a resposta.

Adicionar um fluxo condicional para 404

Em vez de esperar uma resposta do back-end quando uma solicitação inesperada é enviada, você pode adicionar um novo fluxo condicional ao final dos fluxos condicionais do endpoint de proxy para gerar uma falha quando nenhum dos outros fluxos condicionais corresponder às condições. Assim, você garante que apenas as operações listadas nos fluxos condicionais sejam transmitidas ao back-end. Esse padrão permite que você conceda acesso apenas a um subconjunto dos recursos do serviço de back-end.

1. No menu de navegação do proxy, acesse Endpoint de proxy: padrão, navegue até a seção do fluxo e clique em + ao lado de /bank/v1.

2. Para o novo fluxo condicional, especifique os seguintes valores:

   Propriedade	Valor
   Nome do fluxo	404NotFound
   Tipo de condição	Selecione Personalizado.
   Condição	DELETETHIS

3. Clique em Adicionar.

4. No fluxo 404NotFound, remova esta linha:

   <Condition>DELETETHIS</Condition>

   Se nenhuma das condições anteriores de fluxo condicional for correspondente, o fluxo 404NotFound será executado.

5. No menu de navegação do proxy, acesse a seção Endpoints do proxy, procure por padrão e clique em 404NotFound.

6. No painel Fluxo, clique no botão + ao lado do fluxo de solicitação 404NotFound.

7. Em Selecionar política, escolha Selecionar política atual e clique em RF-404NotFound.

8. Clique em Adicionar.

9. Clique em Salvar > Salvar como nova revisão.

10. Clique em Implantar e selecione avaliação em Ambiente.

11. Em Conta de serviço, especifique o endereço de e-mail da conta de serviço:

    apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

12. Clique em Implantar e em Confirmar.

13. Clique na guia Visão geral e aguarde o status de implantação da avaliação indicar que o proxy foi implantado.

Clique em Verificar meu progresso para conferir o objetivo. Adicionar o tratamento de erros

Testar o fluxo condicional de 404

1. No Cloud Shell, se a conexão SSH com a VM de teste tiver sido encerrada, estabeleça uma nova:

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. Depois de receber um token, faça uma solicitação GET para /users:

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/users"

   A resposta foi reescrita e ficou assim:

   HTTP/2 404 faultname: RaiseFault content-type: application/json x-request-id: d6bbd48f-65bd-4551-9236-636fad03a609 content-length: 39 date: Tue, 18 Jan 2022 07:07:58 GMT via: 1.1 google alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 { "error": "GET /users not found" }

   O cabeçalho faultname agora tem o valor RaiseFault, que é o valor de fault.name usado quando uma política RaiseFault causa a geração da falha. A política RaiseFault no fluxo condicional de 404NotFound gerou a resposta.

Parabéns!

Neste laboratório, você protegeu uma API exigindo um token JWT OAuth. Você também limitou o tráfego adicionando políticas SpikeArrest. Além disso, você usou variáveis particulares e mascaramento de dados para ocultar dados sensíveis em sessões de depuração. Por fim, você também reescreveu uma mensagem de erro de back-end e usou um fluxo condicional de 404 para restringir as chamadas ao back-end a recursos específicos.

Próximas etapas / Saiba mais

• OAuth
• Política SpikeArrest
• Como mascarar e ocultar dados
• Tokens opacos e JWTs
• Gerenciamento de falhas

Manual atualizado em 6 de agosto de 2025

Laboratório testado em 6 de agosto de 2025

Copyright 2026 Google LLC. Todos os direitos reservados. Google e o logotipo do Google são marcas registradas da Google LLC. Todos os outros nomes de produtos e empresas podem ser marcas registradas das respectivas empresas a que estão associados.