GSP363

Visão geral

Nos laboratórios com desafio, apresentamos uma situação e um conjunto de tarefas. Para concluí-las, em vez de seguir instruções detalhadas, você usará o que aprendeu nos laboratórios do curso. Um sistema automático de pontuação (mostrado nesta página) vai avaliar seu desempenho.

Nos laboratórios com desafio, não ensinamos novos conceitos do Google Cloud. O objetivo dessas tarefas é aprimorar aquilo que você já aprendeu, como a alteração de valores padrão ou a leitura e pesquisa de mensagens para corrigir seus próprios erros.

Para alcançar a pontuação de 100%, você precisa concluir todas as tarefas no tempo definido.

Este laboratório é recomendado para estudantes que concluíram os laboratórios do curso Desenvolver e Proteger APIs com a Apigee X. Tudo pronto para começar o desafio?

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.

Cenário do desafio

Você trabalha na área de engenharia de nuvem da Cymbal Shops, uma varejista nacional. O foco da Cymbal Shops são as vendas globais, e os serviços de tradução foram identificados como uma ferramenta essencial para ajudar a expandir os negócios no mundo todo. Você é responsável por criar a primeira versão de uma API de tradução.

Os supervisores esperam que você já tenha habilidades e conhecimento suficientes para fazer isso, portanto, não fornecem nenhum guia explicativo.

Seu desafio

Você vai criar um proxy de API da Apigee e outros recursos na organização do projeto. Leia a descrição de cada tarefa e crie a funcionalidade necessária.

Erros ao salvar

Ao salvar as mudanças no proxy de API, você poderá encontrar um erro Não foi possível salvar a nova revisão. Se você usar o botão suspenso Salvar () e selecionar Salvar como nova revisão, uma mensagem de erro vai informar o que é inválido.

Tarefa 1: criar um proxy para a API Cloud Translation

A Cymbal Shops decidiu usar a API Translation do Google Cloud como o serviço de back-end para o proxy de API.

Requisitos:

1. No Console do Google Cloud, confirme se a API Cloud Translation está ativada na Biblioteca de APIs.
2. Crie uma conta de serviço para o proxy de API chamada apigee-proxy e conceda a ela o papel Geração de registros > Gravador de registros.
3. No console do Google Cloud, no menu de navegação, selecione Apigee para abrir a interface da Apigee e criar seu proxy de API.
4. O proxy de API precisa ser um proxy reverso chamado translate-v1, com um caminho base de /translate/v1.
5. O destino do proxy de API é o URL HTTP da versão básica da API Cloud Translation (https://translation.googleapis.com/language/translate/v2).
6. Não adicione autorização, CORS ou uma cota usando a página "Políticas comuns" do assistente de proxy.
7. Na página de resumo, crie o proxy de API mantendo as configurações padrão.
8. Adicione uma seção de autenticação ao TargetEndpoint padrão, fazendo com que um token de acesso seja enviado com todas as solicitações de back-end. Use um elemento GoogleAccessToken com um escopo de https://www.googleapis.com/auth/cloud-translation.

Observação: edite o proxy e, na guia Desenvolver, na seção Endpoints de destino, edite o arquivo default.xml.

9. Use o seguinte script do Cloud Shell para confirmar se o ambiente de execução do Apigee está totalmente instalado:

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***";

Quando o script retornar ORG IS READY TO USE, siga para as próximas etapas.

Observação : se você estiver aguardando a instalação do ambiente de execução, leia e planeje o desenvolvimento para a Tarefa 2.

10. Salve e implante o proxy translate-v1 no ambiente eval usando a seguinte conta de serviço:

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

11. Teste o proxy de API.

O ambiente de avaliação na organização da Apigee pode ser chamado usando o nome do host eval.example.com. Essa entrada DNS só está disponível na rede interna. Portanto, é necessário usar uma VM criada para você.

12. No Cloud Shell, estabeleça uma conexão SSH com apigeex-test-vm:

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

13. Se for necessário autorizar, clique em Autorizar. Para cada pergunta feita no comando gcloud, pressione Enter ou Return para especificar a entrada padrão.

14. Depois de concluir a Tarefa 1, o seguinte comando curl vai traduzir o texto:

curl -i -k -X POST "https://eval.example.com/translate/v1" -H "Content-Type: application/json" -d '{ "q": "Translate this text!", "target": "es" }'

Sua resposta deve ser parecida com esta:

{ "data": { "translations": [ { "translatedText": "¡Traduce este texto!", "detectedSourceLanguage": "en" } ] } } Observação: por alguns minutos, você poderá receber uma resposta de erro 502 até que o proxy de API seja totalmente implantado.

Clique em Verificar meu progresso para conferir o objetivo. Criar um proxy para a API Cloud Translation

Observação: se uma marca de seleção verde não aparecer, clique em "Pontuação" no canto superior direito e selecione Verificar meu progresso na etapa em questão. Uma caixa pop-up vai orientar você.

Tarefa 2: mudar a solicitação e a resposta da API

A Cymbal Shops quer criar uma API diferente da interface fornecida pela API Translation. Duas chamadas da API Translation precisam ser modificadas.

A primeira chamada recupera uma lista de idiomas válidos.

Solicitação da API Cloud Translation:

REQUEST: POST https://translation.googleapis.com/language/translate/v2/languages Authorization: Bearer ACCESSTOKEN Content-Type: application/json { "target": "en" }

Resposta da API Cloud Translation:

Content-Type: application/json { "data": { "languages": [ { "language": "af", "name": "Afrikaans" }, { "language": "sq", "name": "Albanian" }, ... ] } }

Solicitação de translate-v1:

GET https://eval.example.com/translate/v1/languages

Resposta de translate-v1:

Content-Type: application/json [{"language":"af","name":"Afrikaans"},{"language":"sq","name":"Albanian"}, ... ]

O proxy de API precisa substituir o GET por um POST, remover os campos de resposta data e languages e receber o código do idioma-alvo de um conjunto de propriedades. O token de acesso foi adicionado automaticamente pela seção Autenticação na Tarefa 1.

A segunda chamada traduz texto para um idioma especificado.

Solicitação da API Cloud Translation:

POST https://translation.googleapis.com/language/translate/v2 Authorization: Bearer ACCESSTOKEN Content-Type: application/json { "q": "Hello world!", "target": "de" }

Resposta da API Cloud Translation:

Content-Type: application/json { "data": { "translations": [ { "translatedText": "Hallo Welt!", "detectedSourceLanguage": "en" } ] } }

Solicitação de translate-v1:

POST https://eval.example.com/translate/v1?lang=de Content-Type: application/json { "text": "Hello world!" }

Resposta de translate-v1:

Content-Type: application/json { "translated": "Hallo Welt!" }

O proxy de API precisa usar o idioma-alvo do parâmetro de consulta lang e mudar os nomes dos campos do texto de entrada e traduzido. O parâmetro de consulta lang pode ser omitido da solicitação de translate-v1. Nesse caso, o idioma-alvo será extraído de uma propriedade no conjunto de propriedades.

Observação: a API Translation aceita uma única string ou uma matriz de strings para o campo "q". Sua API só pode aceitar uma única string.

Requisitos:

1. No proxy de API, crie um conjunto de propriedades chamado language.properties. O conjunto de propriedades precisa ter duas propriedades: output com um valor de es e caller com um valor de en. A propriedade caller será usada para especificar o idioma-alvo ao listar idiomas (o idioma usado para o campo name). A propriedade output vai informar o idioma-alvo padrão a ser usado se o parâmetro de consulta lang não for fornecido.

2. No endpoint de proxy, crie um fluxo condicional de caminho e verbo para o recurso POST /. Dê a ele o nome de translate.

3. No endpoint de proxy, crie um fluxo condicional de caminho (sem verbo) para o recurso /languages. Dê a ele o nome de getLanguages. Não inclua um verbo. Você vai modificar o verbo da solicitação de GET (para a entrada do proxy) para POST (exigido pelo back-end). Se você incluir um verbo na condição, as políticas de resposta no fluxo não serão executadas porque request.verb não será mais igual a GET.

4. Crie uma política AssignMessage chamada AM-BuildTranslateRequest para criar a solicitação de back-end usada no fluxo condicional translate.

A política precisa atender a estes requisitos:

• Um AssignVariable com um modelo para criar variáveis que serão usadas mais tarde em uma mensagem registrada. A variável chamada text precisa usar a função de modelo de mensagem jsonPath para extrair o campo text da solicitação.

• A variável chamada language deve ser criada usando a função de modelo de mensagem firstnonnull. Essa variável precisa conter o valor do parâmetro de consulta lang, se ele existir, e a propriedade output do conjunto de propriedades de idioma para o idioma-alvo, caso o parâmetro de consulta lang não tenha sido especificado.

• Uma seção Set deve ser usada para definir o payload JSON exigido pelo serviço de back-end. As duas variáveis criadas serão usadas no payload.

• O elemento [AssignTo] precisa usar a mensagem de solicitação atual.

  As seções AssignVariable na política AssignMessage devem ser parecidas com:

  <AssignVariable> <Name>...</Name> <Template>...</Template> <AssignVariable>

5. Crie uma política AssignMessage chamada AM-BuildTranslateResponse no fluxo condicional translate para criar a resposta para o autor da chamada usando a resposta da API Translation.

A política precisa atender a estes requisitos:

• Um AssignVariable com um modelo jsonPath para criar uma variável chamada translated, extraindo o campo translatedText da resposta da API Translation. Dica: a expressão JSONPath para extrair esse campo é $.data.translations[0].translatedText.

• Defina createNew como "true".

• O novo payload JSON vai usar a variável translated.

  As seções AssignVariable na política AssignMessage devem ser parecidas com:

  <AssignVariable> <Name>...</Name> <Template>...</Template> <AssignVariable>

6. Crie uma política AssignMessage chamada AM-BuildLanguagesRequest para criar a solicitação de back-end usada no fluxo condicional getLanguages.

A política precisa atender a estes requisitos:

• Use Set para definir o verbo e o payload corretos para a solicitação de back-end.

• A propriedade caller no conjunto de propriedades language deve ser usada para o campo target no payload do back-end.

• Defina createNew como "true".

• Defina o payload da solicitação de back-end para ter um tipo de conteúdo application/json.

  As seções AssignVariable na política AssignMessage devem ser parecidas com:

  <AssignVariable> <Name>...</Name> <Set> ... </Set> </AssignVariable>

7. Crie uma política JavaScript chamada JS-BuildLanguagesResponse no fluxo condicional getLanguages para criar a resposta para o autor da chamada. O código JavaScript precisa seguir estas etapas:

• Use context.getVariable para recuperar a variável response.content.
• Use JSON.parse para converter o JSON de response.content em um objeto.
• Use JSON.stringify para converter o campo data.languages do objeto em JSON.
• Use context.setVariable para substituir response.content pelo JSON da etapa 3.

Seu código JavaScript vai ficar assim:

var payload = ...; var payloadObj = JSON.parse(...); var newPayload = JSON.stringify(...); context.setVariable(...); Observação: crie as políticas desejadas nos fluxos condicionais corretos e edite as configurações de política nos respectivos arquivos .xml.

8. Teste a API. Na máquina virtual apigeex-test-vm, use os seguintes comandos curl para testar os exemplos mostrados acima:

• Lista de idiomas:

  curl -i -k -X GET "https://eval.example.com/translate/v1/languages"

• Traduzir para o idioma especificado (alemão):

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -d '{ "text": "Hello world!" }'

• Traduzir para o idioma padrão (espanhol):

  curl -i -k -X POST "https://eval.example.com/translate/v1" -H "Content-Type:application/json" -d '{ "text": "Hello world!" }'

Clique em Verificar meu progresso para conferir o objetivo. Mudar a solicitação e a resposta da API

Observação: se uma marca de seleção verde não aparecer, clique em "Pontuação" no canto superior direito e selecione Verificar meu progresso na etapa em questão. Uma caixa pop-up vai orientar você.

Tarefa 3: adicionar verificação da chave de API e controle de cotas

O acesso a essa API precisa ser limitado a aplicativos aprovados. Por isso, adicione uma política de verificação da chave de API e uma política de cota para limitar o número de solicitações.

Requisitos:

1. Crie um produto de API com translate-product como nome de exibição e nome. Esse produto de API precisa ter acesso público, aprovar automaticamente as solicitações de acesso e estar disponível no ambiente de avaliação.

2. Adicione uma operação ao produto de API translate-product. A operação precisa permitir o acesso ao proxy translate-v1 e usar um caminho /, que permite o acesso a qualquer solicitação, incluindo /. Os métodos permitidos são GET e POST. Defina uma cota de 10 solicitações por minuto para a operação.

3. Crie um desenvolvedor com o e-mail joe@example.com. Escolha seu próprio nome, sobrenome e nome de usuário.

4. Crie um app chamado translate-app e ative o produto de API translate-product para ele. Você precisa associar o e-mail ao desenvolvedor joe@example.com.

5. Adicione uma política de verificação da chave de API chamada VA-VerifyKey ao pré-fluxo do endpoint de proxy. A chave de API é obrigatória para todas as solicitações e precisa ser enviada usando o cabeçalho Key.

6. Adicione uma política de cota chamada Q-EnforceQuota ao pré-fluxo do endpoint de proxy.

A política precisa atender a estes requisitos:

• Use um tipo de calendar. O tipo de calendar exige um elemento StartTime.
• Especifique UseQuotaConfigInAPIProduct para usar a cota do produto de API, com uma cota padrão de 5 solicitações por hora se o produto de API não especificar configurações de cota.
• Defina Distributed e Synchronous como "true" e remova o elemento AsynchronousConfiguration.

Depois que essas mudanças forem feitas, a solicitação vai retornar um erro se uma chave de API válida não for especificada no cabeçalho "Key".

7. Na máquina virtual apigeex-test-vm, use os seguintes comandos curl para testar a funcionalidade da chave de API:

• Falha (sem chave de API):

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -d '{ "text": "Hello world!" }'

• Falha (chave de API inválida):

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: ABC123" -d '{ "text": "Hello world!" }'

• Sucesso (quando a variável KEY é definida como uma chave de API válida KEY=<get this from the earlier step when setting up a Developer App>):

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

Clique em Verificar meu progresso para conferir o objetivo. Adicionar verificação da chave de API e controle de cotas

Observação: se uma marca de seleção verde não aparecer, clique em "Pontuação" no canto superior direito e selecione Verificar meu progresso na etapa em questão. Uma caixa pop-up vai orientar você.

Tarefa 4: adicionar registro de mensagens

Para entender como o serviço de tradução está sendo usado, uma política MessageLogging registra cada mensagem traduzida.

Requisitos:

1. Adicione uma política MessageLogging chamada ML-LogTranslation ao fluxo condicional translate. A política precisa ser executada após a etapa AM-BuildTranslateResponse.

Observação: não a adicione ao PostClientFlow porque os registros são criados apenas para a operação de tradução.

2. A política precisa fazer registros no Cloud Logging. Use esta documentação de política.

• O valor de LogName precisa ser:

  projects/{organization.name}/logs/translate

• A mensagem registrada precisa ter um contentType de text/plain, e o conteúdo da mensagem precisa ser:

  {language}|{text}|{translated}

Essa mensagem exige as variáveis language, text e translated criadas nas políticas AM-BuildTranslateRequest e AM-BuildTranslateResponse.

3. Valide as mensagens registradas na página Logging do console do Google Cloud. Use a consulta logName : "translate" para ver apenas os registros traduzidos.

4. Depois que a política MessageLogging for adicionada, use o seguinte comando curl:

curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

• Esse comando curl cria uma mensagem de registro com o seguinte conteúdo:

  de|Hello world!|Hallo Welt!

Observação: há um pequeno atraso antes que uma mensagem registrada apareça nos registros.

Clique em Verificar meu progresso para conferir o objetivo. Adicionar registro de mensagens

Observação: se uma marca de seleção verde não aparecer, clique em "Pontuação" no canto superior direito e selecione Verificar meu progresso na etapa em questão. Uma caixa pop-up vai orientar você.

Tarefa 5: reescrever uma mensagem de erro de back-end

Quando o parâmetro target enviado à API Translation é inválido, uma mensagem de erro 400 Bad Request é retornada:

{ "error": { "code": 400, "message": "Invalid Value", "errors": [ { "message": "Invalid Value", "domain": "global", "reason": "invalid" } ] } }

Essa mensagem de erro seria confusa para o autor da chamada. Por isso, é necessário reescrevê-la.

Requisitos:

1. Adicione uma seção FaultRules ao endpoint de destino default. Quando o back-end retorna uma resposta 400, ele avalia automaticamente todas as regras de falha correspondentes no endpoint de destino.

Observação: o menu do navegador da interface à esquerda não pode ser usado para adicionar uma seção FaultRules. É necessário adicioná-la à configuração XML do endpoint de destino.

2. Adicione uma FaultRule à seção FaultRules. A condição dessa FaultRule precisa ser configurada para ser executada se fault.name for ErrorResponseCode.

3. Crie uma política AssignMessage chamada AM-BuildErrorResponse e anexe-a à FaultRule. Use a seguinte configuração de política:

<AssignMessage name="AM-BuildErrorResponse"> <Set> <Payload contentType="application/json">{ "error": "Solicitação inválida. Verifique o parâmetro de consulta lang." }</Payload> </Set> </AssignMessage>

Depois que a política for anexada, a seção FaultRules no endpoint de destino vai ficar assim:

<FaultRules> <FaultRule name="..."> <Step> <Name>...</Name> </Step> <Condition>...</Condition> </FaultRule> </FaultRules> Observação: é necessário editar manualmente o XML do endpoint de destino. Verifique se é o TargetEndpoint, não o ProxyEndpoint.

4. Teste a API.

• Uma solicitação válida como esta ainda deve funcionar:

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=de" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

• Um parâmetro de consulta de idioma inválido como este deve retornar a mensagem de erro reescrita:

  curl -i -k -X POST "https://eval.example.com/translate/v1?lang=invalid" -H "Content-Type:application/json" -H "Key: $KEY" -d '{ "text": "Hello world!" }'

Clique em Verificar meu progresso para conferir o objetivo. Reescrever uma mensagem de erro de back-end

Observação: se uma marca de seleção verde não aparecer, clique em "Pontuação" no canto superior direito e selecione Verificar meu progresso na etapa em questão. Uma caixa pop-up vai orientar você.

Parabéns!

Neste laboratório com desafio, você demonstrou seus conhecimentos sobre como desenvolver e proteger APIs com a Apigee X.

Conquiste seu próximo selo de habilidade

Este laboratório autoguiado faz parte da Quest Desenvolver e Proteger APIs com a Apigee X. Após a conclusão, você ganha o selo de habilidade acima como reconhecimento. Compartilhe o selo no seu currículo e nas redes sociais e use a #GoogleCloudBadge para mostrar sua conquista.

Essa Quest com selo de habilidade faz parte do programa de aprendizado Desenvolvedor de APIs do Google Cloud. Para continuar sua jornada de aprendizado, inscreva-se na Quest Implantação e Gerenciamento da Apigee X.

Treinamento e certificação do Google Cloud

Esses treinamentos ajudam você a aproveitar as tecnologias do Google Cloud ao máximo. Nossas aulas incluem habilidades técnicas e práticas recomendadas para ajudar você a alcançar rapidamente o nível esperado e continuar sua jornada de aprendizado. Oferecemos treinamentos que vão do nível básico ao avançado, com opções de aulas virtuais, sob demanda e por meio de transmissões ao vivo para que você possa encaixá-las na correria do seu dia a dia. As certificações validam sua experiência e comprovam suas habilidades com as tecnologias do Google Cloud.

Manual atualizado em 10 de julho de 2024

Laboratório testado em 10 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.