GSP845

Visão geral

A Apigee é uma plataforma para desenvolvimento e gerenciamento de APIs. A Apigee facilita o uso de serviços do Google Cloud, como o Pub/Sub, o Cloud Logging ou qualquer outro serviço de nuvem que disponibiliza uma API REST. Neste laboratório, o proxy de API da Apigee aproveita diversos serviços do Google Cloud.

Nesse laboratório, você vai usar vários serviços do Google Cloud em um proxy de API da Apigee para processar comentários de usuários.

Objetivos

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

• Ativar as APIs obrigatórias do Google Cloud
• Criar uma conta de serviço e atribuir os papéis adequados
• Chamar um serviço do Google Cloud usando a API REST do Google Cloud
• Realizar análise de sentimento ao chamar a API Cloud Natural Language
• Publicar uma mensagem do Pub/Sub usando a política PublishMessage
• Registrar mensagens de erro no Cloud Logging

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.

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: ativar APIs do Google Cloud

Nesta tarefa, vamos ativar as APIs que serão usadas pelo proxy de API da Apigee.

1. No console do Cloud, acesse o menu de navegação () e selecione APIs e serviços > Biblioteca.

   Nesta página, você pode ativar as APIs necessárias para o proxy de API da Apigee.

2. Na caixa de diálogo Pesquisar APIs e serviços, insira Cloud Natural Language e pressione Enter.

   A API Cloud Natural Language fornece insights de linguagem natural, como análise de sentimento e reconhecimento de entidades. Esta API será usada para identificar comentários que indicam insatisfação do usuário.

3. Clique em API Cloud Natural Language.

   A API já está pronta para uso.

   Você também pode usar o comando gcloud para ativar APIs.

4. Para ativar as APIs necessárias no Cloud Shell, execute o comando:

   gcloud services enable language.googleapis.com pubsub.googleapis.com logging.googleapis.com

   Além da API Cloud Natural Language, você está ativando a API Pub/Sub e a API Cloud Logging.

   Quando a API Natural Language indicar que um usuário está insatisfeito, o Pub/Sub vai publicar uma mensagem em um tópico. É possível criar uma função do Cloud que executa uma ação para cada mensagem, contatando o usuário para tentar resolver o problema e aumentar a satisfação do cliente.

   Vamos usar o Cloud Logging para capturar uma entrada de registro a cada comentário recebido. Os registros podem conter detalhes internos da API que facilitam a identificação de problemas em serviços ou aplicativos.

Tarefa 2: criar uma conta de serviço

Nesta tarefa, vamos criar uma conta de serviço para ser usada pelo proxy da Apigee.

Criar a conta de serviço do IAM

1. No menu de navegação (), acesse IAM e administrador > Contas de serviço.

2. Clique em + Criar conta de serviço.

3. No campo Nome da conta de serviço, especifique o seguinte:

   apigee-gc-service-access

   Com esta conta de serviço, o proxy de API da Apigee acessa os serviços do Google Cloud especificados.

4. Clique em Criar e continuar.

5. Em Selecionar um papel, escolha Pub/Sub > Publicador do Pub/Sub.

   O proxy de API da Apigee vai publicar em um tópico do Pub/Sub.

6. Clique em + Adicionar outro papel.

7. Em Selecionar um papel, escolha Logging > Gravador de registros.

   O proxy de API da Apigee vai gravar mensagens de registros no Cloud Logging.

Observação: não é necessário atribuir um perfil para chamar a API Natural Language.

8. Clique em Concluído.

   A conta de serviço foi criada.

Clique em Verificar meu progresso para conferir o objetivo. Criar a conta de serviço e atribuir papéis.

Tarefa 3: criar um proxy de API

Nesta tarefa, vamos criar o proxy de API da Apigee. Como o proxy de API vai usar políticas para chamar os serviços, não será necessário configurar um destino.

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 de API 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.

3. Em Modelo de proxy, selecione Modelo geral > Nenhum destino.

   O proxy não vai usar um serviço de back-end. Vamos empregar políticas para realizar toda a comunicação com serviços externos.

Observação: evite usar a opção Nenhum destino na seção Modelo de especificação da OpenAPI.

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

   Propriedade	Valor
   Nome do proxy	services-v1
   Caminho base	/services/v1

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

5. Clique em Próxima.

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

Criar um novo fluxo condicional

1. Clique na guia Desenvolver no Editor de Proxy.

2. Selecione Endpoints do proxy > Padrão no painel à esquerda.

3. Clique no botão + localizado acima do painel Resposta.

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

   Propriedade	Valor
   Nome do fluxo	postComment
   Descrição	publicar um comentário em uma categoria determinada
   Tipo de condição	selecione Caminho e verbo
   Caminho	/comments
   Verbo	selecione POST

   Mantenha o campo URL de destino em branco.

5. Clique em Adicionar.

Implantar a API

1. Clique em Salvar. Ao receber a notificação de que o proxy foi salvo como nova revisão, clique em Salvar como nova revisão.

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-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Clique em Implantar e depois em Confirmar.

   Aguarde até que a implantação seja concluída.

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

Tarefa 4: Chamar a API Natural Language

Nesta tarefa, vamos adicionar uma política ServiceCallout para chamar a API Natural Language e identificar o sentimento de um comentário recebido.

Extrair os parâmetros de entrada

O recurso POST /comments vai usar um payload JSON com dois parâmetros: comment, que contém o texto livre enviado por um usuário, e category, que especifica o tipo de comentário. Uma política ExtractVariables será usada para extrair os dados de entrada.

1. No painel Fluxo, clique no ícone + ao lado do fluxo postComment no painel Solicitação.

2. Na caixa de diálogo Adicionar etapa de política, clique em Criar nova política.

3. No menu suspenso Selecionar política, escolha o tipo de política Extrair variáveis na seção Mediação.

4. Especifique o seguinte:

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

5. Clique em Adicionar.

6. Clique na política EV-ExtractRequest e substitua a configuração em XML da política ExtractVariables por:

<ExtractVariables name="EV-ExtractRequest"> <Source>request</Source> <JSONPayload> <Variable name="comment"> <JSONPath>$.comment</JSONPath> </Variable> <Variable name="category"> <JSONPath>$.category</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </ExtractVariables>

Essa política extrai os parâmetros comment e category da solicitação JSON POST /comments. O elemento IgnoreUnresolvedVariables está definido com o valor “false”, o que provoca uma falha se essas duas entradas não forem especificadas.

Observação: em uma API de produção, é recomendável adicionar tratamento de falhas para corrigir a maioria dos erros gerados por políticas. Nesse laboratório, não vamos adicionar o tratamento de falhas.

Chamar a API Natural Language

Uma política ServiceCallout vai ser usada para chamar a API Natural Language e retornar o sentimento do comentário.

1. Clique no fluxo postComment se ele não estiver destacado e depois selecione o ícone + ao lado do fluxo postComment no painel Resposta.

   A resposta da chamada realizada pela API Natural Language vai ser retornada ao autor da chamada.

2. Na caixa de diálogo Adicionar etapa de política, clique em Criar nova política.

3. No menu suspenso Selecionar política, escolha o tipo de política Service Callout na seção Extensão.

4. Especifique o seguinte:

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

5. Clique em Adicionar.

   O fluxo deve ser semelhante a este:

   

6. Clique na política SC-NaturalLanguage.

7. Substitua a configuração em XML da política ServiceCallout por:

   <ServiceCallout name="SC-NaturalLanguage"> <Request clearPayload="true"> <Set> <Verb>POST</Verb> <Payload contentType="application/json">{ "document": { "content": "{comment}", "type": "PLAIN_TEXT" } } </Payload> </Set> </Request> <Response>response</Response> <HTTPTargetConnection> <Properties/> <URL>https://language.googleapis.com/v1/documents:analyzeSentiment</URL> <Authentication> <GoogleAccessToken> <Scopes> <Scope>https://www.googleapis.com/auth/cloud-language</Scope> </Scopes> </GoogleAccessToken> </Authentication> </HTTPTargetConnection> </ServiceCallout>

   A seção Solicitação da política ServiceCallout especifica a solicitação POST enviada para o serviço. O formato deste payload é específico para a API Natural Language.

   O elemento Resposta indica que a resposta da API Natural Language vai ser armazenada na mensagem de resposta.

   A seção HTTPTargetConnection especifica o URL do serviço que está sendo chamado. O URL e os formatos de solicitação e resposta estão disponíveis na referência da API Natural Language.

   A seção Autenticação especifica a autenticação da API do Google Cloud. Um token de acesso do OAuth do Google vai ser adicionado automaticamente à solicitação de chamada. O Escopo especifica que o token de acesso vai ser usado para fornecer acesso à API Natural Language.

8. Clique em Salvar.

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

• 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 Apigee para determinar quando a instância do ambiente de execução da Apigee foi criada e o ambiente de avaliação foi anexado.

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 os produtos e serviços de IA no Google Cloud.

Implantar a API

1. Retorne ao proxy de API services-v1 e clique na guia Desenvolver.

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-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Clique em Implantar e em Confirmar.

6. 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. Chamar a API Natural Language

Testar a 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 de 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, os comandos do Cloud Shell 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

   Se aparecer a pergunta Do you want to continue (Y/n)?, digite Y.

2. Para cada pergunta feita no Cloud Shell, pressione 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 services-v1 implantado no ambiente de avaliação:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"A Jane foi gentil o suficiente para voltar ao carro e me trazer molho picante extra. Obrigado, Jane!", "category":"delivery-reviews"}'

   A resposta da API Natural Language é semelhante a:

{ "documentSentiment": { "magnitude": 1.8, "score": 0.9 }, "language": "en", "sentences": [ { "documentSentiment": { "magnitude": 1.8, "score": 0.9 }, "language": "en", "sentences": [ { "text": { "content": "A Jane foi gentil o suficiente para voltar ao carro e me trazer molho picante extra.", "beginOffset": -1 }, "sentiment": { "magnitude": 0.9, "score": 0.9 } }, { "text": { "content": "Obrigado, Jane!", "beginOffset": -1 }, "sentiment": { "magnitude": 0.9, "score": 0.9 } } ] } ] }

A pontuação de documentSentiment varia de 1 a -1, com 1 representando uma avaliação extremamente positiva e -1 uma avaliação extremamente negativa. Neste caso, o sentimento é extremamente positivo.

4. Realize uma nova chamada ao proxy de API:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"O motorista nunca chegou com meu jantar. :(", "category":"delivery-reviews"}'

   Neste comentário, o sentimento é extremamente negativo.

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

Tarefa 5: publicar uma mensagem no Pub/Sub para comentários negativos

Nesta tarefa, vamos adicionar uma política PublishMessage para publicar uma mensagem em um tópico do Pub/Sub sempre que um comentário negativo for recebido. Assinantes do tópico podem gerar um fluxo de trabalho para tentar solucionar o problema do usuário que fez o comentário.

Criar um tópico do Pub/Sub para avaliações de entrega

Cada categoria terá um tópico específico do Pub/Sub. É necessário criar um tópico antes de publicar uma mensagem nele.

1. No menu de navegação (), acesse Pub/Sub > Tópicos.

2. Clique em + Criar tópico.

3. No campo ID do tópico, digite apigee-services-v1-delivery-reviews e depois clique em Criar.

   Um tópico e uma assinatura novos são criados.

Extrair a pontuação da resposta da API Natural Language

1. Retorne à Apigee no console do Cloud.

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

3. Abra a guia Desenvolver. Clique no fluxo postComment.

4. No painel Fluxo, clique no ícone + ao lado do fluxo postComment no painel Resposta.

5. Na caixa de diálogo Adicionar etapa de política, clique em Criar nova política.

6. No menu suspenso Selecionar política, escolha o tipo de política Extrair variáveis na seção Mediação.

7. Especifique o seguinte:

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

8. Clique em Adicionar e depois escolha a política EV-ExtractSentiment.

9. Substitua a configuração em XML da política ExtractVariables por:

   <ExtractVariables name="EV-ExtractSentiment"> <Source>response</Source> <JSONPayload> <Variable name="sentimentScore"> <JSONPath>$.documentSentiment.score</JSONPath> </Variable> </JSONPayload> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>

Adicionar uma política PublishMessage

1. Clique no fluxo postComment e depois no botão + localizado abaixo do fluxo Resposta.

2. Na seção Extensão, selecione o tipo de política Publicar mensagem.

3. Especifique o seguinte:

   Propriedade	Valor
   Nome de exibição	PM-PublishScore
   Nome	PM-PublishScore

4. Clique em Adicionar e depois escolha a política PM-PublishScore.

5. Substitua a configuração em XML da política PublishMessage por:

   <PublishMessage continueOnError="true" name="PM-PublishScore"> <Source>{response.content}</Source> <CloudPubSub> <Topic>projects/{organization.name}/topics/apigee-services-v1-{category}</Topic> </CloudPubSub> </PublishMessage>

6. Clique em Salvar. Ao receber a notificação de que o proxy foi salvo como nova revisão, clique em Salvar como nova revisão.

   O response.content é o payload retornado pela API Natural Language e vai ser enviado como mensagem no Pub/Sub. A categoria da solicitação é usada para criar o nome do tópico no Pub/Sub.

   Categorias incorretas vão resultar em um nome de tópico inexistente. Em uma API de produção, é recomendável verificar as categorias especificadas antes de publicar uma mensagem no Pub/Sub. Nesse caso, como continueOnError está definido como “true” na política, nenhum erro será gerado quando o tópico não existir.

Adicionar uma verificação condicional para a política PublishMessage

É possível usar condições para ignorar políticas em um fluxo, quando necessário.

1. No menu de navegação do proxy, em Endpoints do proxy, clique em padrão.

   A configuração do ProxyEndpoint será apresentada.

2. Para adicionar uma condição à etapa PM-PublishScore, substitua o código abaixo:

<Step> <Name>PM-PublishScore</Name> </Step>

por este código:

<Step> <Name>PM-PublishScore</Name> <Condition>sentimentScore LesserThan 0.0</Condition> </Step>

A política PublishMessage vai ser executada somente quando a pontuação de sentimento for inferior a 0.

Implantar a API

1. Clique em Salvar. Ao receber a notificação de que o proxy foi salvo como nova revisão, clique em Salvar como nova revisão.

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-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Clique em Implantar e em Confirmar.

Clique em Verificar meu progresso para conferir o objetivo. Publicar uma mensagem no Pub/Sub para comentários negativos.

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 solicitado, clique em Autorizar.

2. Chame o proxy de API services-v1 implantado no ambiente de avaliação:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"O motorista nunca chegou com meu jantar. :(", "category":"delivery-reviews"}'

3. No menu de navegação (), acesse Pub/Sub > Tópicos.

4. Clique no tópico apigee-services-v1-delivery-reviews.

5. Role até o final da página e depois selecione a assinatura apigee-services-v1-delivery-reviews-sub.

6. Clique na guia Mensagens e depois em Pull.

7. Na mensagem, selecione o botão Visualizar todo o conteúdo da linha do menu suspenso.

   É possível conferir o payload em JSON enviado para comentários com sentimentos negativos.

Tarefa 6: Adicionar uma política MessageLogging

Nesta tarefa, vamos adicionar uma política MessageLogging para registrar uma mensagem no Cloud Logging.

Criar um PostClientFlow

Existe um fluxo opcional chamado PostClientFlow no ProxyEndpoint. As políticas anexadas a este fluxo são executadas depois que a resposta é retornada ao autor da chamada. Esse ponto é ideal para registrar mensagens, já que o registro não adicionaria latência extra à solicitação.

1. Retorne à guia Apigee e, se necessário, acesse novamente a página Desenvolver do services-v1.

2. No menu de navegação do proxy, em Endpoints do proxy, clique em padrão.

   A configuração do ProxyEndpoint será apresentada.

3. Logo acima da seção HTTPProxyConnection, adicione a seguinte linha:

   <PostClientFlow/>

   Ao adicionar a linha, a base do seu código ProxyEndpoint deve ser semelhante a isto:

<PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <PostClientFlow/> <HTTPProxyConnection> <BasePath>/services/v1</BasePath> </HTTPProxyConnection> <RouteRule name="noroute"/> </ProxyEndpoint>

Com esse comando, um PostClientFlow vazio é adicionado ao ProxyEndpoint.

Adicionar uma política MessageLogging

1. No menu de navegação do proxy, em Endpoints do proxy, clique em PostClientFlow e depois no botão + localizado abaixo do fluxo Resposta.

2. Na caixa de diálogo Adicionar etapa de política, clique em Criar nova política.

3. No menu suspenso Selecionar política, escolha o tipo de política Gerar registro de mensagens na seção Extensão.

4. Especifique o seguinte:

   Propriedade	Valor
   Nome de exibição	ML-LogToCloudLogging
   Nome	ML-LogToCloudLogging

5. Clique em Adicionar e depois selecione a política ML-LogToCloudLogging.

6. Substitua a configuração em XML da política PublishMessage por:

   <MessageLogging name="ML-LogToCloudLogging"> <CloudLogging> <LogName>projects/{organization.name}/logs/apiproxy-{apiproxy.name}</LogName> <Message contentType="application/json">{ "messageid": "{messageid}", "environment": "{environment.name}", "apiProxy": "{apiproxy.name}", "proxyRevision": "{apiproxy.revision}", "uri": "{request.uri}", "statusCode": "{response.status.code}", "category": "{category}", "score": "{sentimentScore}", "publishFailed": "{publishmessage.failed}" }</Message> <Labels> <Label> <Key>proxyName</Key> <Value>services-v1</Value> </Label> </Labels> </CloudLogging> </MessageLogging>

   A seção CloudLogging especifica as informações que serão registradas no Cloud Logging. O nome do proxy é usado como parte do LogName na política, o que facilita a busca no Cloud Logging.

   A mensagem dessa política é em JSON, mas qualquer formato de mensagem de texto pode ser usada nos registros. Geralmente, o conteúdo dos registros inclui variáveis de fluxo do proxy que facilitam a depuração de problemas. Por exemplo, a variável publishmessage.failed será “true” se a mensagem do Pub/Sub não for enviada.

   Também é possível adicionar rótulos à mensagem registrada para classificar o conteúdo dela.

Implantar a API

1. Clique em Salvar. Ao receber a notificação de que o proxy foi salvo como nova revisão, clique em Salvar como nova revisão.

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-gc-service-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

5. Clique em Implantar e em Confirmar.

   Aguarde até que a implantação seja concluída.

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

Testar a API

1. Se a conexão SSH no Cloud Shell for encerrada, estabeleça uma nova 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 solicitado, clique em Autorizar.

2. Chame o proxy de API services-v1 implantado no ambiente de avaliação:

   curl -i -k -X POST -H "Content-Type: application/json" 'https://eval.example.com/services/v1/comments' -d '{"comment":"O motorista nunca chegou com meu jantar. :(", "category":"invalid-category"}'

   A categoria fornecida (invalid-category) não está associada a um tópico do Pub/Sub.

3. No menu de navegação (), acesse Logging > Análise de registros.

4. Na caixa de diálogo Consulta, insira a seguinte consulta:

   "invalid-category"

5. Clique em Executar consulta.

6. Expanda a entrada de registro no painel Resultados da consulta e depois expanda jsonPayload.

Expandir a entrada de registros apresenta a mensagem registrada em JSON e outros metadados. O jsonPayload deve ser semelhante a:

{ "apiProxy": "services-v1", "category": "invalid-category", "environment": "eval", "messageid": "32c1eda7-f661-98f4-8d66-3c1c158dc620", "proxyRevision": "4", "publishFailed": "true", "score": "-0.8", "statusCode": "200", "uri": "/services/v1/comments" }

A variável publishFailed está definida como “true” porque não existe um tópico para essa categoria. Registros bem elaborados ajudam a identificar problemas nos proxies de API e serviços de back-end.

Parabéns!

Nesse laboratório, você ativou as APIs do Google Cloud e criou uma conta de serviço. Você chamou a API Cloud Natural Language usando uma política ServiceCallout, com a autenticação da conta de serviço fornecida pela Apigee. Você usou a política PublishMessage para publicar uma mensagem em um tópico do Pub/Sub. Por último, você usou a política MessageLogging para registrar uma mensagem no Cloud Logging.

Próximas etapas / Saiba mais

• Pub/Sub
• Cloud Logging
• Produtos de IA e machine learning, como a API Cloud Natural Language

Manual atualizado em 8 de agosto de 2025

Manual testado em 8 de agosto de 2025

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.