Visão geral

Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Escrita em formato JSON ou YAML, uma especificação OpenAPI é legível por máquina, mas também é fácil de ler e entender por pessoas.

A especificação detalha os elementos de uma API, incluindo o caminho base, caminhos e verbos de recursos, operações, cabeçalhos, parâmetros de consulta e respostas. Além disso, uma especificação OpenAPI é comumente usada para gerar a documentação da API.

Neste laboratório, vamos analisar uma especificação OpenAPI para um serviço de back-end de varejo. Você usará essa especificação OpenAPI para criar um proxy de API, que vai servir para adicionar recursos e segurança à API de back-end.

Objetivos

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

• Conhecer uma especificação OpenAPI e entender os diferentes componentes.
• Criar um proxy de API com base em uma especificação OpenAPI usando o assistente de proxy.
• Rastrear um proxy de API.

Configuração

Para cada laboratório, você recebe um novo projeto do Google Cloud e um conjunto de recursos por um determinado período sem custo financeiro.

1. Faça login no Google Skills usando uma janela anônima.

2. Confira o tempo de acesso do laboratório (por exemplo, 1:15:00) e finalize todas as atividades nesse prazo. Não é possível pausar o laboratório. Você pode reiniciar o desafio, mas vai precisar refazer todas as etapas.

3. Quando tudo estiver pronto, clique em Começar o laboratório.

4. Anote as credenciais (Nome de usuário e Senha). É com elas que você vai fazer login no Console do Google Cloud.

5. Clique em Abrir Console do Google.

6. Clique em Usar outra conta e copie e cole as credenciais deste laboratório nos locais indicados. Se você usar outras credenciais, vai receber mensagens de erro ou cobranças.

7. Aceite os termos e pule a página de recursos de recuperação.

Ative o Google Cloud Shell

O Google Cloud Shell é uma máquina virtual com 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. No console do Cloud, clique no botão "Abrir o Cloud Shell" na barra de ferramentas superior direita.

   

2. Clique em Continuar.

O provisionamento e a conexão do ambiente podem demorar um pouco. Quando você estiver conectado, já estará autenticado, e o projeto estará definido com seu PROJECT_ID. Exemplo:

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

• Para listar o nome da conta ativa, use este comando:

gcloud auth list

Saída:

Credentialed accounts: - @.com (active)

Exemplo de saída:

Credentialed accounts: - google1623327_student@qwiklabs.net

• Para listar o ID do projeto, use este comando:

gcloud config list project

Saída:

[core] project =

Exemplo de saída:

[core] project = qwiklabs-gcp-44776a13dea667a6 Observação: a documentação completa da gcloud está disponível no guia com informações gerais sobre a gcloud CLI .

Tarefa 1: examinar a especificação OpenAPI do serviço de back-end

Nesta tarefa, você vai analisar a especificação OpenAPI criada para um serviço de back-end que será usado nos seus proxies de API.

Baixar a especificação OpenAPI

• No Cloud Shell, baixe a especificação OpenAPI do serviço de back-end usando este comando curl:

  curl https://storage.googleapis.com/cloud-training/developing-apis/specs/retail-backend.yaml?$(date +%s) --output ~/retail-backend.yaml

  Esse comando curl baixa um arquivo chamado retail-backend.yaml e o armazena em um arquivo com o mesmo nome no diretório principal. Mais tarde no laboratório, você vai usar essa mesma especificação ao criar um proxy de API.

  Observação: "?$(date +%s)" adiciona um parâmetro de consulta ao URL, que é uma representação em string da data/hora atual. Essa variável, que muda dinamicamente, altera o URL e força o curl a recuperar a versão mais recente de um arquivo, mesmo que uma versão anterior esteja em cache.

Visualizar a especificação OpenAPI no Cloud Shell Editor

1. No Cloud Shell, clique em Abrir editor.

   

2. No editor, selecione o arquivo retail-backend.yaml.

   

Conheça as seções da especificação

1. Examinar a especificação OpenAPI.

   Essa é a especificação OpenAPI do serviço de back-end que será usado em muitos dos laboratórios do curso. Vamos conhecer as seções da especificação OpenAPI.

   O campo openapi especifica a versão da especificação OpenAPI. Esta é uma especificação da OpenAPI versão 3, como indicado pelo número da versão na parte de cima do arquivo:

   openapi: "3.0.0"

   O objeto info fornece metadados sobre a própria API. A versão mostrada é a da especificação do back-end de varejo:

   info: version: 1.0.0 title: Retail Backend description: Retail backend database used for Developing APIs course contact: name: Google Cloud (Apigee) email: apigee@example.org url: https://cloud.google.com/apigee license: name: MIT url: https://opensource.org/licenses/MIT

   A matriz servers contém uma lista de objetos de servidor que especificam informações de conectividade para servidores de destino. Essa especificação contém um único serviço de back-end, que seu proxy de API vai chamar:

   servers: - url: "https://gcp-cs-training-01-test.apigee.net/training/db" description: Retail backend for Developing APIs course

   A matriz tags adiciona metadados às tags usadas nas operações, que são mostradas abaixo. As tags podem ser compartilhadas por várias operações e podem ser usadas para fornecer descrições detalhadas ou links para documentação externa.

   tags: - name: categories description: Product Categories - name: products description: Products - name: orders description: Orders - name: stores description: Stores

   O objeto paths armazena os caminhos relativos para endpoints individuais e as respectivas operações. Um desses caminhos, /categories/{categoryId}, é usado para especificar uma única categoria. Aqui, mostramos uma operação get especificada para receber uma categoria por ID. O objeto "get" mostra parâmetros e respostas. Para operações que contêm um corpo de solicitação, como PATCH /products/{productId}, o corpo da solicitação também será especificado.

   /categories/{categoryId}: get: summary: Get a specific category operationId: getCategoryById tags: - categories parameters: - name: categoryId in: path required: true description: category id schema: type: integer responses: '200': description: Selected category content: application/json: schema: $ref: "#/components/schemas/Category" '404': description: Category not found content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error"

   O objeto components contém objetos reutilizáveis para diferentes partes da especificação OpenAPI. O objeto de componente securitySchemes contém definições de diferentes tipos de esquemas de segurança usados pelas operações. Essa especificação define um único esquema de autenticação básica, que é referenciado na operação PATCH /products/{productId}. O objeto de componente schemas contém tipos de dados de entrada e saída. Consulte abaixo o objeto Category, que é retornado quando a operação GET /categories/{categoryId} dá certo:

   components: securitySchemes: basicAuth: type: http description: basic auth scheme: basic schemas: Category: type: object description: product category required: - color - id - name properties: color: description: use this color for displaying this category type: string id: description: integer id (used for access) type: integer format: int32 minimum: 0 name: description: category name type: string

   Confira a especificação ou a documentação da especificação OpenAPI.

2. Para mais detalhes sobre essa especificação OpenAPI, use o painel do Gemini Code Assist no editor. Expanda o item de contexto na seção Comandos e confirme se o arquivo retail-backend.yaml atual está selecionado.

3. No comando, digite:

   Explain the contents of this file.

4. Clique em Enviar ().

   O Gemini gera uma resposta que descreve o conteúdo da especificação OpenAPI de back-end. Um resumo geral e as seções principais foram incluídos para explicar a finalidade das seções definidas.

Baixar a especificação OpenAPI na sua máquina

1. Clique em Abrir terminal.

2. Selecione o menu Mais () do Cloud Shell e clique em Baixar.

3. Insira retail-backend.yaml e clique em Baixar.

   O arquivo é salvo na máquina local.

Tarefa 2: criar um proxy de API usando a especificação OpenAPI

Nesta tarefa, você vai criar um proxy de API usando a especificação OpenAPI para o serviço de back-end.

Fixar a página do console da Apigee

1. No console do Google Cloud, no Menu de navegação (), procure Apigee na seção Produtos preferidos.

   A página do console da Apigee será aberta.

2. Se a opção Apigee não estiver na lista, pesquise Apigee na barra de pesquisa superior e acesse o serviço Apigee.

3. Para fixar a Apigee no console, clique no ícone de favorito ().

   A página do console da Apigee agora vai aparecer na lista de produtos preferidos do menu de navegação.

Usar o assistente de proxy para criar um proxy

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

2. Para iniciar o assistente de proxy, clique em +Criar.

3. Em Modelo de proxy, selecione Modelo de especificação OpenAPI > Proxy reverso (mais comum).

4. Em Especificações OpenAPI, clique em Procurar, selecione o arquivo retail-backend.yaml que você baixou e clique em Abrir.

5. Clique em Avançar.

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

   Propriedade	Valor
   Nome do proxy	retail-v1
   Caminho base	/retail/v1
   Descrição	Minha API de varejo

   O destino foi retirado da matriz servers na especificação da OpenAPI. Deixe o destino inalterado.

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

7. Clique em Avançar.

   As operações encontradas na especificação OpenAPI estão listadas.

8. Em Fluxos, na linha do cabeçalho, clique em Selecionar todas as linhas.

   Todos os fluxos precisam estar selecionados.

9. Clique em Avançar.

10. Em Ambientes de implantação, selecione o ambiente avaliação e clique em OK.

    Observação: deixe o campo "Conta de serviço" vazio.

11. Clique em Criar.

    Seu proxy será gerado e marcado para implantação.

A disponibilidade do ambiente de execução pode ser adiada

O provisionamento completo de uma organização do Apigee geralmente leva 30 minutos ou mais. A maior parte do tempo é gasto provisionando o cluster e o banco de dados do ambiente de execução, além dos serviços usados para executar os proxies de API. Ao criar uma organização de longa duração da Apigee, esse atraso no provisionamento completo não é um problema. Mas você não precisa aguardar meia hora antes de iniciar cada laboratório.

Às vezes, você vai perceber que a organização já está totalmente provisionada quando entrar no laboratório. Outras vezes, a organização da Apigee só começa o provisionamento quando você inicia o laboratório.

As operações no plano de gerenciamento da organização ficam disponíveis alguns minutos após o processo de provisionamento. Em vez de esperar que o ambiente de execução seja totalmente provisionado, esses laboratórios permitem que você execute operações como edições de proxy antes que o ambiente de execução esteja disponível. Quando você implanta um proxy em um ambiente antes que o ambiente de execução esteja disponível, ele não pode receber tráfego até que o provisionamento seja concluído.

Quando você mantém o cursor sobre o ícone Status de um proxy implantado, conforme mostrado abaixo, talvez não haja instâncias informando o status. Isso é normal até que o ambiente de execução da organização da Apigee seja totalmente provisionado.

Saiba mais sobre a implantação de proxy da Apigee

Para saber mais sobre o processo de implantação de proxy de API em um ambiente da Apigee, use o Gemini Cloud Assist no console do Google Cloud.

Abrir o Gemini Cloud Assist

1. Para abrir o Gemini Cloud Assist, no console do Google Cloud, clique em Abrir ou fechar o chat do Gemini Cloud Assist ().

2. Se solicitado no painel do Cloud Assist, clique em Usar o Gemini Cloud Assist.

3. Se quiser, veja quais são as APIs obrigatórias e recomendadas para ativação.

4. Clique em Ativar o Gemini Cloud Assist sem custo financeiro.

5. Clique em Iniciar a conversa.

Perguntar ao Gemini

1. No comando, digite:

   In Apigee X, explain the deployment process of an API proxy to an Apigee environment.

2. Clique em Enviar ().

   Leia a resposta gerada pelo Gemini Cloud Assist.

3. Opcionalmente, clique em Mostrar conteúdo relacionado para navegar pela documentação relacionada.

Verificar o status da implantação

Um proxy implantado e pronto para receber tráfego terá um status verde na guia "Visão geral".

Quando um proxy é marcado como implantado, mas o ambiente de execução ainda não está disponível e o ambiente de avaliação não está anexado, um sinal de aviso vermelho pode aparecer. Mantenha o ponteiro sobre o ícone Status para ver o status atual.

Se o proxy estiver implantado e aparecer em verde, ele estará pronto para o tráfego de API. Se o proxy não for implantado porque não há pods do ambiente de execução, verifique o status de provisionamento.

Verificar o status de provisionamento

• No Cloud Shell, para confirmar que a instância do ambiente de execução foi instalada e o ambiente de avaliação foi anexado, execute os seguintes comandos:

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; 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/${PROJECT_ID}/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/${PROJECT_ID}/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***"; Esses comandos usam a API Apigee para determinar quando a instância do ambiente de execução foi criada e o ambiente de avaliação foi anexado a ela. Copie e cole esse comando no Cloud Assist se quiser que o Gemini explique como ele funciona.

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

Enquanto você espera

• Web API Design: The Missing Link (Design de API da web: o elo perdido, em tradução livre): um e-book sobre princípios de design de API
• Especificação OpenAPI

Tarefa 3: analisar e rastrear o proxy de API

Iniciar a ferramenta de depuração

1. Selecione a guia Desenvolver.

   Essa guia é usada para editar o proxy gerado. Fluxos condicionais foram criados para cada uma das operações na especificação OpenAPI. Esses fluxos condicionais aparecem no endpoint de proxy no navegador à esquerda. Quando você clica em um fluxo condicional, as seções de solicitação e resposta são selecionadas no painel do editor visual. O código default.xml mostrado abaixo é a representação do código dos fluxos do endpoint de proxy.

   

   Você vai atualizar muitos desses fluxos condicionais em laboratórios futuros.

2. Selecione a guia Depuração.

   A ferramenta de depuração é usada para rastrear solicitações de API que são processadas pelo proxy.

3. Clique em Iniciar sessão de depuração.

4. No painel Iniciar sessão de depuração, vá até o menu suspenso "Ambiente" e selecione avaliação.

   O número da revisão implantada também vai aparecer no menu suspenso.

5. Clique em Iniciar.

   A sessão de depuração será executada por 10 minutos.

Testar o proxy de API usando o DNS particular

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

Como o Cloud Shell não está na rede interna, 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 para essa finalidade. Nela, você pode fazer chamadas de proxy de API.

O comando curl será usado para enviar solicitações a um proxy de API. A opção -k do curl informa que ele deve ignorar a verificação do certificado TLS. Neste laboratório, o ambiente de execução da Apigee usa um certificado autoassinado. Em um ambiente de produção, use certificados criados por uma autoridade certificadora (AC) confiável.

1. No Cloud Shell, abra uma nova guia e 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, digite Y para continuar.

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

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

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

Chamar o proxy de API

1. Para fazer uma chamada ao proxy hospedado no ambiente de avaliação, na sessão SSH do Cloud Shell, envie uma solicitação ao proxy de API usando este comando:

   curl -i -k -X GET https://eval.example.com/retail/v1/categories

   Uma transação para essa solicitação vai aparecer no painel Transações à esquerda. Quando uma transação é selecionada, um rastreamento da solicitação e da resposta é exibido na Apigee. Vai aparecer um código de status 200 se o URL do back-end foi definido corretamente e você atualizou o URL "Enviar solicitações" de forma correta.

   Observação: o tráfego da sessão de depuração da Apigee é recuperado com uma pesquisa assíncrona de novas chamadas de API. Por isso, pode haver um intervalo entre a conclusão de uma solicitação de API e a exibição dela na ferramenta de depuração.

2. Clique nos botões Voltar e Avançar para navegar pelas etapas da transação.

   A solicitação era GET /retail/v1/categories. Essa solicitação foi enviada ao back-end, que respondeu com uma matriz JSON contendo as categorias.

Parabéns!

Neste laboratório, você aprendeu sobre as especificações OpenAPI e conheceu alguns dos recursos delas. Você usou uma especificação OpenAPI para um serviço de back-end de varejo para criar um proxy de API e rastreou chamadas por ele.

Finalize o laboratório

Após concluir o laboratório, clique em Terminar o laboratório. O Google Skills remove os recursos usados e limpa a conta para você.

Você poderá classificar sua experiência neste laboratório. Basta selecionar o número de estrelas, digitar um comentário e clicar em Enviar.

O número de estrelas indica o seguinte:

• 1 estrela = muito insatisfeito
• 2 estrelas = insatisfeito
• 3 estrelas = neutro
• 4 estrelas = satisfeito
• 5 estrelas = muito satisfeito

Feche a caixa de diálogo se não quiser enviar feedback.

Para enviar seu feedback, fazer sugestões ou correções, use a guia Suporte.

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