GSP842

Visão geral

Com a plataforma de APIs da Apigee do Google Cloud, é possível modernizar os aplicativos atuais com a adição de novas funcionalidades às APIs existentes.

Neste laboratório, vamos implantar um serviço de back-end no Cloud Run. O serviço de back-end implementa uma API REST que armazena e recupera dados bancários, como clientes, contas, caixas eletrônicos e transações, em um banco de dados do Firestore. Você cria um proxy de API da Apigee que encaminha as solicitações para o serviço de back-end. Você também desenvolve um fluxo compartilhado que recupera o conteúdo de um serviço externo e o armazena em cache. Na sequência, você chama o fluxo compartilhado via proxy de API e modifica a resposta da API usando código JavaScript.

Objetivos

Neste laboratório, você aprenderá a realizar as seguintes tarefas:

• Implantar um serviço de back-end no Cloud Run
• Encaminhar solicitações para o serviço de back-end usando um proxy da Apigee X
• Criar um fluxo compartilhado com funcionalidades que podem ser usadas por vários proxies
• Armazenar dados de configuração em um conjunto de propriedades
• Usar uma política de chamada de serviço para recuperar conteúdo de um serviço
• Usar políticas de cache para armazenar informações reutilizáveis
• Usar código JavaScript para modificar um payload de resposta

Configuração

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.

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.

Tarefa 1: implantar um serviço de back-end no Cloud Run

Nesta tarefa, vamos implantar um serviço de back-end no Cloud Run.

O serviço implementa uma API para o SimpleBank. Esta API simula um banco de forma simplificada, com dados de clientes, contas, transações e caixas eletrônicos. O serviço SimpleBank foi criado usando Node.js e armazena dados no Firestore. O código é empacotado em um contêiner do Docker, que é implantado no Cloud Run.

Clonar o repositório de código

1. Para clonar o repositório que contém o código do serviço SimpleBank, execute o seguinte comando no Cloud Shell:

   git clone --depth 1 https://github.com/GoogleCloudPlatform/training-data-analyst

2. Crie um link flexível para o diretório de trabalho:

   ln -s ~/training-data-analyst/quests/develop-apis-apigee ~/develop-apis-apigee

3. Para acessar o diretório que contém o back-end REST, execute o seguinte comando:

   cd ~/develop-apis-apigee/rest-backend

4. Para atualizar a região presente no arquivo de configuração, execute o seguinte comando:

   sed -i "s/us-west1/{{{ project_0.default_region | "REGION" }}}/g" config.sh

Inicializar o projeto

O script de inicialização, init-project.sh, ativa as APIs no projeto. Essas APIs são um requisito para a implantação de serviços do Cloud Run.

O serviço vai usar o Firestore no modo Nativo como banco de dados. Cada projeto pode hospedar um banco de dados do Firestore, seja no modo Nativo ou Datastore. Com este script, o banco de dados do Firestore vai ser criado no modo Nativo.

1. Para conferir os comandos executados pelo script init-project.sh, digite:

   cat init-project.sh

   O script ativa as APIs e cria o banco de dados do Firestore no modo Nativo.

2. Para executar o script, digite o comando:

   ./init-project.sh

Clique em Verificar meu progresso para conferir o objetivo. Ative a API do Cloud Run e crie o banco de dados do Firestore.

Inicializar o serviço

O script de inicialização do serviço, init-service.sh, cria uma conta de serviço chamada simplebank-rest. Esta conta de serviço é usada como a identidade para o serviço do Cloud Run. A conta de serviço recebe o papel roles/datastore.user, que autoriza leitura e atualização de dados no Firestore.

É uma prática recomendada criar uma conta de serviço para cada serviço e conceder permissões à conta usando o princípio de privilégio mínimo. Esse princípio determina que uma conta deve ter apenas os privilégios essenciais para executar sua função específica.

1. Para conferir os comandos executados pelo script init-service.sh, digite:

   cat init-service.sh

   O script cria a conta de serviço usada pelo serviço e concede papéis a ela.

2. Para executar o script, digite o comando:

   ./init-service.sh

Implantar o serviço de back-end

O script de implantação, deploy.sh, cria o aplicativo de serviço simplebank com o código presente no diretório atual e o implanta no Cloud Run usando a conta de serviço simplebank-rest. O script de implantação deve ser executado sempre que você atualizar o código do aplicativo.

O serviço foi implantado com exigência de autenticação, portanto, não é possível acessá-lo sem um token de identidade do OpenID Connect válido.

1. Para conferir os comandos executados pelo script deploy.sh no Cloud Shell, digite:

   cat deploy.sh

   O script cria e implanta o serviço simplebank-grpc no Cloud Run.

Observação: o script de implantação usa o parâmetro “max-instances” para limitar o número de instâncias no cluster do Cloud Run a 1. Em um ambiente de produção real, não seria recomendável definir um limite tão baixo.

2. Para implantar o script no Cloud Run, digite o comando:

   ./deploy.sh

Clique em Verificar meu progresso para conferir o objetivo. Implante o serviço de back-end.

Testar o serviço

1. Para verificar se o serviço está em execução, realize uma solicitação curl que o chame:

   export RESTHOST=$(gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)') echo "export RESTHOST=${RESTHOST}" >> ~/.bashrc curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/_status"

   O comando responsável por atribuir valor à variável RESTHOST usa gcloud para recuperar o nome do host do serviço simplebank-rest do Cloud Run. Posteriormente, a variável é adicionada ao arquivo .bashrc, garantindo que RESTHOST seja carregada novamente se o Cloud Shell for reiniciado.

   O comando GET /_status retorna uma resposta JSON que indica que a API está ativa e em execução. Nessa chamada, você usou o comando gcloud auth print-identity-token para recuperar um token de identidade do OpenID Connect do usuário autenticado no Cloud Shell. Você fez login com o papel de proprietário do projeto, que concede permissões muito abrangentes.

2. Para verificar se o serviço tem permissão para gravar no Firestore, realize uma solicitação “curl” que cria um cliente:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -H "Content-Type: application/json" -X POST "${RESTHOST}/customers" -d '{"lastName": "Diallo", "firstName": "Temeka", "email": "temeka@example.com"}'

   O comando POST /customers é responsável por criar um cliente. Os parâmetros lastName, firstName e email são obrigatórios. O endereço de e-mail deve ser exclusivo e é usado como o identificador do cliente. O registro do cliente é armazenado no Firestore.

   Observação: se você receber um erro “AlreadyExist”, pode significar que o banco de dados do Firestore ainda não foi criado corretamente. O banco de dados é criado ao executar o script “init-project.sh”.

3. Para verificar se o serviço pode ler do Firestore, realize uma solicitação “curl” para recuperar o cliente recém-criado:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/customers/temeka@example.com"

   O comando GET /customers/ é usado para recuperar um registro de cliente armazenado no Firestore.

4. Para carregar dados de amostra adicionais no Firestore, digite o comando:

   gcloud firestore import gs://spls/shared/firestore-simplebank-data/firestore/example-data

   O comando gcloud usa o recurso de importação/exportação do Firestore para importar clientes, contas e caixas eletrônicos ao banco de dados.

5. Para recuperar a lista de caixas eletrônicos, execute o seguinte comando “curl”:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/atms"

6. Para recuperar um único caixa eletrônico, execute o seguinte comando “curl”:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" -X GET "${RESTHOST}/atms/spruce-goose"

   A solicitação recupera um caixa eletrônico pelo nome, e a resposta contém suas coordenadas de latitude e longitude, mas não inclui um endereço:

   {"name":"spruce-goose","longitude":-118.408207,"description":"","latitude":33.977601}

   Em uma tarefa futura, você vai usar a Apigee e a API Geocoding para adicionar um endereço à resposta retornada ao recuperar um caixa eletrônico específico.

Tarefa 2: encaminhar solicitações para o serviço de back-end com um proxy de API da Apigee

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

Criar uma conta de serviço para o proxy de API da Apigee

1. Para criar uma conta de serviço que possa ser usada pelo proxy de API da Apigee, digite o comando:

   gcloud iam service-accounts create apigee-internal-access \ --display-name="Service account for internal access by Apigee proxies" \ --project=${GOOGLE_CLOUD_PROJECT}

   O comando gcloud cria uma conta de serviço chamada apigee-internal-access, que o proxy da Apigee vai usar para chamar o serviço de back-end.

2. Para conceder o papel que autoriza o acesso ao serviço, digite o comando:

   gcloud run services add-iam-policy-binding simplebank-rest \ --member="serviceAccount:apigee-internal-access@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com" \ --role=roles/run.invoker --region={{{project_0.default_region |REGION}}} \ --project=${GOOGLE_CLOUD_PROJECT}

   O comando gcloud concede à conta de serviço o papel roles/run.invoker para o serviço simplebank-rest do Cloud Run, autorizando a invocação do serviço.

3. Para recuperar o URL do serviço de back-end, use o seguinte comando:

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

   Salve esse URL. Ele vai ser usado na criação do proxy de API.

Clique em Verificar meu progresso para conferir o objetivo. Pode ocorrer um pequeno atraso antes que o perfil concedido seja reconhecido. Crie uma conta de serviço para o proxy de API da Apigee.

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 Fixar ().

A Apigee agora está fixada no menu de navegação.

Criar o proxy da Apigee

1. No menu de navegação, selecione Desenvolvimento de proxy > Proxies de API.

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

   Você vai criar um proxy reverso para o serviço de back-end.

3. Em Modelo de proxy, selecione Modelo geral > Proxy reverso (mais comum).

   Observação: evite usar a opção Proxy reverso (mais comum) na seção Modelo de especificação da OpenAPI.

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

   Propriedade	Valor
   Nome do proxy	bank-v1
   Caminho base	/bank/v1
   Destino (API atual)	URL do back-end

   Observação: confirme que o caminho base usado é “/bank/v1” e não “/bank-v1”.

   O destino deve ser o URL do back-end que você recuperou anteriormente na tarefa e ter um formato semelhante a:

   https://simplebank-rest-mtdtzt7yzq-ue.a.run.app

5. Clique em Próxima.

6. Mantenha as configurações da opção Implantar (opcional) nos valores padrão e clique em Criar.

Confirmar se a instância do 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***";

   Esta série de comandos usa a API da Apigee para determinar quando a instância do 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. É possível que a organização (org) da Apigee tenha sido criada antes de você iniciar o laboratório, por isso talvez não seja necessário aguardar a criação da instância.

   Se estiver esperando a organização ser configurada, aproveite para conhecer mais informações sobre a Apigee, a arquitetura da Apigee X ou as APIs e os proxies de API.

Implantar o proxy de API

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

2. Clique em Implantar.

3. Em Ambiente, selecione avaliação.

4. 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

5. Clique em Implantar e depois em Confirmar.

6. Aguarde o status de implantação da avaliação indicar que o proxy foi implantado.

Testar o proxy de API

É possível acessar 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 do ambiente de execução da Apigee. Esta 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, seus comandos não conseguem resolver essa entrada DNS. Uma máquina virtual (VM) do seu projeto 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

   O primeiro comando gcloud recupera a zona da VM de teste, e o segundo estabelece a conexão SSH com a VM.

2. Se solicitado, clique em Autorizar.

   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.

   A sessão do Cloud Shell está em execução na VM.

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

   curl -i -k "https://eval.example.com/bank/v1/_status"

   A opção -k instrui o curl a ignorar a verificação do certificado TLS. Neste laboratório, o ambiente de execução da Apigee usa um certificado autoassinado em vez de um certificado criado por uma autoridade certificadora (CA) confiável.

   Observação: você não deve usar a opção -k para ignorar a verificação de certificados em casos de uso em ambientes de produção.

   Um código de status 403 Proibido é retornado, com uma mensagem de erro que informa que o cliente não tem permissão para acessar o URL. A solicitação ao serviço de back-end foi rejeitada porque o cliente não forneceu o token exigido. O proxy de API está em execução com a identidade correta, mas o envio do token de identidade do OpenID Connect ainda precisa ser realizado na solicitação.

4. Retorne ao proxy bank-v1 e clique na guia Desenvolver.

5. No menu à esquerda do proxy, na seção Endpoints de destino > Padrão, clique em PreFlow.

6. Localize o código a seguir (o URL será diferente):

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

7. Na seção HTTPTargetConnection, abaixo do URL, adicione uma seção Autenticação com o seguinte formato:

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

8. Substitua AUDIENCE pelo valor do URL presente na seção HTTPTargetConnection. Seu código deve ser semelhante a este, com a diferença de que os elementos “URL” e “Audience” conterão seu URL específico:

   <TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <Properties/> <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>

9. Clique em Salvar e depois em Salvar como nova revisão.

10. Clique em Implantar.

11. Em Ambiente, use avaliação.

12. 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

13. Clique em Implantar e depois em Confirmar.

14. Clique na guia Visão geral e aguarde o status de implantação da avaliação indicar que a nova revisão foi implantada.

Clique em Verificar meu progresso para conferir o objetivo. Crie o proxy da Apigee.

14. Se o seu login SSH expirou, execute este comando no Cloud Shell para restabelecer a conexão:

    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

15. Execute novamente o comando para verificar o status na VM:

    curl -i -k "https://eval.example.com/bank/v1/_status"

    Agora você deverá ver uma resposta bem-sucedida (200) semelhante a esta:

    HTTP/2 200 x-powered-by: Express content-type: application/json; charset=utf-8 etag: W/"41-x4uozCo6q/yN+kzizriXxryNZvc" x-cloud-trace-context: 5c810a7faa3353bcc085473fd58805b7 date: Thu, 11 Nov 2021 22:54:35 GMT server: Google Frontend content-length: 65 x-request-id: cf109193-6d6f-49a1-b323-7f66f63c5e28 via: 1.1 google {"serviceName":"simplebank-rest","status":"API up","ver":"1.0.0"}

    Essa resposta indica que o proxy de API está chamando o serviço de back-end com êxito.

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

Tarefa 3: ativar o uso da API Geocoding do Google Cloud

Nesta tarefa, vamos ativar a API Geocoding, que vai ser usada no proxy de API para adicionar informações de endereço à resposta ao recuperar um caixa eletrônico do serviço SimpleBank.

1. Para ativar a API Geocoding no Cloud Shell, execute o comando:

   gcloud services enable geocoding-backend.googleapis.com

   Em seguida, você vai criar uma chave de API para acessar a API Geocoding.

2. Para criar a chave de API, execute o comando:

   API_KEY=$(gcloud alpha services api-keys create --project=${GOOGLE_CLOUD_PROJECT} --display-name="Geocoding API key for Apigee" --api-target=service=geocoding_backend --format "value(response.keyString)") echo "export API_KEY=${API_KEY}" >> ~/.bashrc echo "API_KEY=${API_KEY}" Observação: se você receber um erro indicando que a propriedade do projeto está definida como uma string vazia, verifique se você saiu da sessão SSH da VM e retornou ao Cloud Shell.

   O comando gcloud cria a chave de API com a permissão para enviar solicitações à API Geocoding. Ao fornecer o parâmetro --format, você seleciona o campo “keyString” na resposta e armazena o valor na variável de shell API_KEY. Em seguida, a variável API_KEY é armazenada no arquivo .bashrc no Cloud Shell.

Clique em Verificar meu progresso para conferir o objetivo. Ative o uso da API Geocoding do Google Cloud.

3. Para recuperar as informações de geocodificação correspondentes a uma latitude e longitude específicas, execute o comando “curl”:

   curl "https://maps.googleapis.com/maps/api/geocode/json?key=${API_KEY}&latlng=37.404934,-122.021411"

   Esse comando chama a API Geocoding, fornecendo a chave de API e a latitude e longitude desejadas. A resposta apresenta uma matriz de resultados, e cada item contém um endereço formatado. No proxy de API, você vai usar o endereço formatado do primeiro resultado ao adicionar um endereço à resposta da API quando recuperar os detalhes de um único caixa eletrônico.

Tarefa 4: Criar um fluxo compartilhado para chamar a API Geocoding

Nesta tarefa, vamos criar um fluxo compartilhado para chamar a API Geocoding do Google. Os fluxos compartilhados permitem combinar políticas e recursos em um único fluxo, para que possam ser usados por vários proxies de API ou outros fluxos compartilhados.

O fluxo compartilhado segue este padrão:

O número de caixas eletrônicos no banco de dados é limitado, e suas latitudes e longitudes permanecem inalteradas. Para evitar chamadas excessivas à API Geocoding, o endereço recuperado vai ser armazenado em cache, usando a latitude e a longitude como chave. Se o endereço não estiver presente no cache para a latitude e longitude especificadas, a API Geocoding vai ser chamada, e o endereço retornado armazenado no cache.

Criar o fluxo compartilhado

1. No menu de navegação, selecione Apigee > Desenvolvimento de proxy > Fluxos compartilhados.
2. Clique em +Criar.
3. Defina o nome como get-address-for-location e depois clique em Criar.
4. Clique na guia Desenvolver.

Adicionar uma política LookupCache

A política LookupCache recupera um endereço se ele tiver sido armazenado em cache anteriormente.

1. No menu à esquerda do fluxo compartilhado, na seção Fluxos compartilhados, clique em padrão.

2. No painel sharedflows/default.xml, clique em Adicionar etapa de política ().

3. Selecione Criar nova política.

4. Em Selecionar política, escolha Gerenciamento de tráfego > Lookup Cache.

5. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	LC-LookupAddress
   Nome de exibição	LC-LookupAddress

6. Clique em Adicionar e depois selecione LC-LookupAddress.

   A política é adicionada ao fluxo, e o XML de configuração correspondente é mostrado no painel abaixo do fluxo.

7. Verifique se a configuração LookupCache está no painel e realize a substituição por:

   <LookupCache continueOnError="false" enabled="true" name="LC-LookupAddress"> <CacheResource>AddressesCache</CacheResource> <Scope>Exclusive</Scope> <CacheKey> <KeyFragment ref="geocoding.latitude"/> <KeyFragment ref="geocoding.longitude"/> </CacheKey> <AssignTo>geocoding.address</AssignTo> </LookupCache>

   A política procura no AddressesCache uma entrada correspondente à latitude e longitude especificadas e, se encontrada, atribui o valor à variável “address”.

Adicionar uma política Service Callout

A política Service Callout chama a API Geocoding do Google.

1. No menu à esquerda do fluxo compartilhado, na seção Fluxos compartilhados, clique em padrão.

2. No painel sharedflows/default.xml, clique em Adicionar etapa de política ().

3. Selecione Criar nova política.

4. Em Selecionar política, escolha Extensão > Service Callout.

5. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	SC-GoogleGeocode
   Nome de exibição	SC-GoogleGeocode

6. Mantenha o campo “Destino HTTP” inalterado, clique em Adicionar e depois selecione SC-GoogleGeocode.

7. Verifique se a configuração ServiceCallout está no painel e realize a substituição por:

   <ServiceCallout continueOnError="false" enabled="true" name="SC-GoogleGeocode"> <Request> <Set> <QueryParams> <QueryParam name="latlng">{geocoding.latitude},{geocoding.longitude}</QueryParam> <QueryParam name="key">{geocoding.apikey}</QueryParam> </QueryParams> <Verb>GET</Verb> </Set> </Request> <Response>calloutResponse</Response> <HTTPTargetConnection> <URL>https://maps.googleapis.com/maps/api/geocode/json</URL> </HTTPTargetConnection> </ServiceCallout>

   Essa política chama a API Geocoding usando as variáveis geocoding.latitude, geocoding.longitude e geocoding.apikey. A resposta da chamada de API é armazenada na variável calloutResponse.

Adicionar uma política ExtractVariables

A política ExtractVariables extrai o endereço formatado da resposta da API Geocoding do Google.

1. No menu à esquerda do fluxo compartilhado, na seção Fluxos compartilhados, clique em padrão.

2. No painel sharedflows/default.xml, clique em Adicionar etapa de política ().

3. Selecione Criar nova política.

4. Em Selecionar política, escolha Mediação > Extract Variables.

5. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	EV-ExtractAddress
   Nome de exibição	EV-ExtractAddress

6. Clique em Adicionar e depois selecione EV-ExtractAddress.

7. Verifique se a configuração ExtractVariables está no painel e realize a substituição por:

   <ExtractVariables continueOnError="false" enabled="true" name="EV-ExtractAddress"> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <JSONPayload> <Variable name="address"> <JSONPath>$.results[0].formatted_address</JSONPath> </Variable> </JSONPayload> <Source clearPayload="false">calloutResponse.content</Source> <VariablePrefix>geocoding</VariablePrefix> </ExtractVariables>

   A política usa JSONPath para extrair o formatted_address do primeiro resultado no payload JSON da mensagem calloutResponse. O endereço é armazenado na variável geocoding.address.

Adicionar uma política PopulateCache

A política PopulateCache armazena o endereço em cache.

1. No menu à esquerda do fluxo compartilhado, na seção Fluxos compartilhados, clique em padrão.

2. No painel sharedflows/default.xml, clique em Adicionar etapa de política ().

3. Selecione Criar nova política.

4. Em Selecionar política, escolha Gerenciamento de tráfego > PopulateCache.

5. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	PC-StoreAddress
   Nome de exibição	PC-StoreAddress

6. Clique em Adicionar e depois selecione PC-StoreAddress.

7. Verifique se a configuração PopulateCache está no painel e realize a substituição por:

   <PopulateCache continueOnError="false" enabled="true" name="PC-StoreAddress"> <CacheResource>AddressesCache</CacheResource> <Scope>Exclusive</Scope> <Source>geocoding.address</Source> <CacheKey> <KeyFragment ref="geocoding.latitude"/> <KeyFragment ref="geocoding.longitude"/> </CacheKey> <ExpirySettings> <TimeoutInSec>3600</TimeoutInSec> </ExpirySettings> </PopulateCache>

   A política armazena o valor da variável address no AddressesCache usando fragmentos de chave da latitude e longitude semelhantes aos empregados pela política LookupCache, na mesma ordem. A configuração ExpirySettings/TimeoutInSec especifica que os dados armazenados serão mantidos em cache por 3.600 segundos, ou seja, uma hora.

Ignorar políticas com base em condições

Quando o endereço for encontrado no cache para uma latitude e longitude específicas (uma ocorrência em cache), as políticas ServiceCallout, ExtractVariables e PopulateCache não são necessárias e devem ser ignoradas.

1. No menu à esquerda do fluxo compartilhado, na seção Fluxos compartilhados, clique em padrão.

   O painel Código contém o fluxo padrão, que lista as quatro políticas anexadas:

   <SharedFlow name="default"> <Step> <Name>LC-LookupAddress</Name> </Step> <Step> <Name>SC-GoogleGeocode</Name> </Step> <Step> <Name>EV-ExtractAddress</Name> </Step> <Step> <Name>PC-StoreAddress</Name> </Step> </SharedFlow>

   Cada Step especifica uma política que foi anexada. O campo Name especifica o nome da política anexada. Também é possível adicionar um elemento Condition, que especifica uma condição booleana para determinar se a política deve ser executada.

   Considere o padrão de fluxo compartilhado no início da tarefa. Se a busca pelo endereço for bem-sucedida, não é necessário chamar o serviço nem armazenar os dados novamente em cache. Nesse caso, as etapas dois a quatro da política devem ser ignoradas.

   A política LookupCache define uma variável para indicar se o item foi encontrado no cache. Se a variável lookupcache.{policyName}.cachehit tiver o valor “false”, significa que o item não foi localizado. As políticas nas etapas dois a quatro devem ser executadas apenas se não houver uma ocorrência em cache.

2. Para cada uma das etapas de dois a quatro, adicione a seguinte condição no elemento Step:

   <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition>

   Depois de adicionar todos os itens, o fluxo compartilhado deve ser semelhante a:

   <SharedFlow name="default"> <Step> <Name>LC-LookupAddress</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>SC-GoogleGeocode</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>EV-ExtractAddress</Name> </Step> <Step> <Condition>lookupcache.LC-LookupAddress.cachehit == false</Condition> <Name>PC-StoreAddress</Name> </Step> </SharedFlow>

3. Clique em Salvar.

4. Clique em Implantar.

5. Em Ambiente, use avaliação.

6. Mantenha o campo Conta de serviço em branco, clique em Implantar e depois selecione Confirmar.

   Como o fluxo compartilhado usa uma chave de API para fazer chamadas à API Geocoding, não é necessário ter uma conta de serviço.

   O fluxo compartilhado só pode ser testado quando chamado de um proxy de API.

Clique em Verificar meu progresso para conferir o objetivo. Crie um fluxo compartilhado para chamar a API Geocoding.

Tarefa 5: adicionar o endereço do caixa eletrônico ao recuperar um único caixa eletrônico

Nesta tarefa, vamos adicionar uma política FlowCallout ao proxy de API para chamar o fluxo compartilhado recém-criado. Ao consultar um caixa eletrônico específico, o proxy de API deve extrair a latitude e a longitude da resposta do serviço do Cloud Run e chamar o fluxo compartilhado para recuperar o endereço correspondente. Depois, uma política JavaScript vai adicionar o endereço à resposta da API.

Adicionar um conjunto de propriedades para a chave de API

Com um conjunto de propriedades, é possível armazenar dados que não expiram e que são facilmente acessados no proxy de API. Um valor do conjunto de propriedades vai armazenar a chave de API.

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

2. Clique em bank-v1 e depois selecione a guia Desenvolver.

3. No menu à esquerda do proxy, na seção Recursos, clique em Adicionar recurso ().

4. No menu suspenso Tipo de recurso, selecione Conjunto de propriedades.

5. Em Nome do recurso, especifique geocoding.properties e depois clique em Adicionar.

6. No painel geocoding.properties, adicione a seguinte propriedade:

   apikey=<APIKEY>

7. Substitua <APIKEY> pela API_KEY criada na Tarefa 3.

8. Você pode recuperar a API_KEY usando este comando no Cloud Shell:

   echo ${API_KEY}

   O arquivo geocoding.properties deve ser parecido com este:

   apikey=AIzaSyC8-B6nt7M240wwZtsxR2O5sb0xznuhQWc

Criar um fluxo condicional

1. No menu à esquerda do proxy, na seção Endpoints de proxy, clique em padrão.

2. No painel proxy-endpoints/default.xml, ao lado de Endpoint de proxy: padrão, clique em Adicionar fluxo condicional ().

3. Na caixa de diálogo Adicionar fluxo condicional, especifique os seguintes valores:

   Propriedade	Valor
   Nome do fluxo	GetATM
   Descrição	recuperar um único caixa eletrônico
   Tipo de condição	selecione Caminho e verbo
   Caminho	/atms/{name}
   Verbo	selecione GET

   Mantenha o campo URL de destino em branco.

4. Clique em Adicionar.

   Um proxy de API é composto por diversos fluxos. Cada fluxo fornece um local para a anexação de políticas como etapas. Confira a seguir um diagrama representando um proxy de API:

   

   Uma configuração de fluxo condicional será executada apenas quando a condição for verdadeira. Neste fluxo condicional, a variável proxy.pathsuffix deve corresponder ao formato /atms/{name}, e a variável request.verb deve estar definida como GET.

   Você vai anexar políticas ao fluxo condicional GetATM para que sejam executadas exclusivamente para solicitações GET /atms/{name}. As políticas devem ser executadas após a chamada ao serviço de back-end, portanto, é necessário anexá-las a um fluxo condicional de resposta do endpoint de proxy.

Extrair a latitude e a longitude

1. No fluxo Endpoint de proxy: padrão, na seção Resposta, à direita de GetATM, clique em Adicionar etapa de política ().

   Observação: confirme que a etapa está sendo adicionada no lado da seção Resposta, e não na seção Solicitação.

2. Selecione Criar nova política.

3. Em Selecionar política, escolha Mediação > Extract Variables.

4. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	EV-ExtractLatLng
   Nome de exibição	EV-ExtractLatLng

5. Clique em Adicionar e depois selecione EV-ExtractLatLng.

6. Verifique se a configuração ExtractVariables está no painel e realize a substituição por:

   <ExtractVariables name="EV-ExtractLatLng"> <Source>response</Source> <JSONPayload> <Variable name="latitude"> <JSONPath>$.latitude</JSONPath> </Variable> <Variable name="longitude"> <JSONPath>$.longitude</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>

   A política extrai a latitude e a longitude da resposta JSON GET /atms/{name} do serviço de back-end. O elemento IgnoreUnresolvedVariables está definido como “true”, o que permite que o processamento prossiga mesmo na ausência dos valores de latitude e longitude na resposta.

Chamar o fluxo compartilhado

1. No fluxo Endpoint de proxy: padrão, na seção Resposta, à direita de GetATM, clique em Adicionar etapa de política ().

2. Selecione Criar nova política.

3. Em Selecionar política, escolha Extensão > Flow Callout.

4. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	FC-GetAddress
   Nome de exibição	FC-GetAddress
   Fluxo compartilhado	selecione get-address-for-location
   Condição	latitude != null AND longitude != null

   Se a latitude ou a longitude não forem recuperadas para um caixa eletrônico, não é possível determinar o endereço, e a etapa da política é ignorada.

5. Clique em Adicionar e depois selecione FC-GetAddress.

6. Verifique se a configuração FlowCallout está no painel e realize a substituição por:

   <FlowCallout continueOnError="false" enabled="true" name="FC-GetAddress"> <Parameters> <Parameter name="geocoding.latitude">{latitude}</Parameter> <Parameter name="geocoding.longitude">{longitude}</Parameter> <Parameter name="geocoding.apikey">{propertyset.geocoding.apikey}</Parameter> </Parameters> <SharedFlowBundle>get-address-for-location</SharedFlowBundle> </FlowCallout>

   A política define as variáveis latitude, longitude e apikey como parâmetros do fluxo compartilhado e o chama. O fluxo compartilhado define a variável geocoding.address.

Adicionar o endereço

1. No fluxo Endpoint de proxy: padrão, na seção Resposta, à direita de GetATM, clique em Adicionar etapa de política ().

2. Selecione Criar nova política.

3. Em Selecionar política, escolha Extensão > JavaScript.

4. Na seção Detalhes, especifique o seguinte:

   Propriedade	Valor
   Nome	JS-AddAddress
   Nome de exibição	JS-AddAddress
   Arquivo JavaScript	selecione Criar novo recurso

5. Na seção Adicionar recurso, especifique o seguinte:

   Propriedade	Valor
   Origem	selecione Criar novo arquivo
   Nome do recurso	addAddress.js

6. Clique em Adicionar e depois selecione addAddress.js.

7. Em Condição, especifique latitude != null AND longitude != null.

8. Clique em Adicionar e depois selecione JS-AddAddress.

9. No menu à esquerda do proxy, na seção Recursos > jsc, clique em addAddress.js.

   O painel de código para addAddress.js está vazio.

10. Adicione o código JavaScript a seguir para incluir o endereço na resposta:

    // obtém a variável de fluxo 'geocoding.address' var address = context.getVariable('geocoding.address'); // analisa o payload da resposta no objeto responsePayload var responsePayload = JSON.parse(context.getVariable('response.content')); try { // adiciona o endereço à resposta responsePayload.address = address; // converte o objeto de resposta novamente para JSON context.setVariable('response.content', JSON.stringify(responsePayload)); } catch(e) { // captura qualquer exceção print('Ocorreu um erro ao tentar adicionar o endereço à resposta.'); }

    O código analisa o payload da resposta JSON e o converte em um objeto, adiciona um campo de endereço ao objeto, o converte novamente em uma string JSON e, em seguida, armazena o resultado na resposta.

    Um bloco try/catch é usado para que uma exceção não seja propagada de forma externa à política JavaScript. Se uma exceção não for capturada, ocorrerá uma falha que vai cancelar a execução do proxy de API.

Validar se as políticas são ignoradas com base em condições

1. No menu à esquerda do proxy, na seção Endpoints de proxy > Padrão, clique em GetATM.

   O painel Código contém o fluxo Get ATM, que lista as três políticas anexadas, com condições aplicadas à segunda e à terceira política:

   <Flow name="GetATM"> <Description>retrieve a single ATM</Description> <Request/> <Response> <Step> <Name>EV-ExtractLatLng</Name> </Step> <Step> <Condition>latitude != null AND longitude != null</Condition> <Name>FC-GetAddress</Name> </Step> <Step> <Condition>latitude != null AND longitude != null</Condition> <Name>JS-AddAddress</Name> </Step> </Response> <Condition>(proxy.pathsuffix MatchesPath "/atms/{name}") and (request.verb = "GET")</Condition> </Flow>

2. Clique em Salvar e depois em Salvar como nova revisão.

3. Clique em Implantar.

4. Em Ambiente, use avaliaçã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 depois em Confirmar.

7. Clique na guia Visão geral e aguarde o status de implantação da avaliação indicar que a nova revisão foi implantada.

Clique em Verificar meu progresso para conferir o objetivo. Adicione o endereço do caixa eletrônico ao recuperar um único caixa eletrônico.

Testar o proxy de API atualizado

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

2. Use o comando a seguir para chamar o proxy bank-v1 e recuperar todos os caixas eletrônicos:

   curl -i -k "https://eval.example.com/bank/v1/atms"

   A resposta não contém endereços porque a solicitação não usa o fluxo GET /atms/{name}.

3. Recupere um único caixa eletrônico:

   curl -i -k "https://eval.example.com/bank/v1/atms/spruce-goose"

   Agora a resposta contém o endereço que foi adicionado no proxy de API:

   {"longitude":-118.408207,"latitude":33.977601,"description":"","name":"spruce-goose","address":"5865 S Campus Center Dr, Los Angeles, CA 90094, USA"}

Parabéns!

Neste laboratório, você implantou um serviço de back-end no Cloud Run. Você criou um proxy de API da Apigee que atua como proxy do serviço de back-end. Você criou um fluxo compartilhado que recuperou e armazenou em cache o conteúdo de um serviço externo. Na sequência, você chamou o fluxo compartilhado via proxy de API e modificou a resposta da API usando código JavaScript.

Próximas etapas / Saiba mais

• O que é a Apigee?
• Arquitetura da Apigee X
• APIs e proxies de API

Manual atualizado em 16 de julho de 2024

Laboratório testado em 16 de julho de 2024

Copyright 2025 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.