Como testar a API

OpenAPI   |  gRPC

Em 21 de março de 2022, o Portal do Cloud Endpoints foi descontinuado. O Portal do Cloud Endpoints não estará mais disponível após 21 de março de 2023. O tráfego de API gerenciado pelo Cloud Endpoints não é afetado por essa mudança. Para mais informações, consulte Descontinuação de recursos.

Além de visualizar a documentação de referência da API SmartDocs, os desenvolvedores podem usar o painel Testar esta API para interagir com a API sem sair da respectiva documentação. No portal, os desenvolvedores podem enviar solicitações para a API e ver as respostas. Testar a API no portal ajuda seus usuários a entender o que precisam fazer para que o código deles funcione com a API.

Se sua API exigir uma chave de API ou autenticação, configure seu portal para que os usuários possam interagir com sua API. Esta página descreve os requisitos e a configuração que você precisa fazer para que os desenvolvedores possam usar Testar esta API. Para a conclusão de cada tarefa, são fornecidos os papéis mínimos exigidos do Identity and Access Management. Para mais informações sobre as permissões do IAM, consulte o seguinte:

• Como entender os papéis
• Como conceder, alterar e revogar acesso a recursos
• Como criar e gerenciar papéis personalizados

Pré-requisitos

• Você precisa implantar o back-end da API.
• Se a API exigir uma chave, o documento do OpenAPI precisa estar configurado conforme descrito em Como restringir o acesso à API com chaves de API.
• Se sua API exigir autenticação, seu documento OpenAPI precisará ser configurado com o método de autenticação escolhido. Consulte Como escolher um método de autenticação.

• Sua API precisa ser acessível por meio de DNS.

  • Se você implantou a API no ambiente flexível do App Engine, uma entrada de DNS com um nome no formato YOUR_PROJECT_ID.appspot.com será criada automaticamente. No exemplo anterior, YOUR_PROJECT_ID é o ID do projeto do Google Cloud para o qual você implantou sua API. Isso significa que é possível testar a API no próprio portal sem nenhuma configuração adicional.
  • Para outros back-ends (como Compute Engine ou GKE), se sua API não estiver configurada para usar um nome de domínio personalizado (por exemplo, myapi.mycompany.com), configure sua API para usar o domínio cloud.goog.

Como definir as configurações do APIs Explorer

Se a API exigir uma chave de API e/ou autenticação do Firebase ou Auth0, você precisará definir essas configurações para que os usuários possam testá-la. Nesta seção, descrevemos como definir uma chave de API e as configurações de autenticação.

Permissões exigidas para a tarefa

Para executar essa tarefa, é preciso ter o papel de editor do projeto.

Como configurar uma chave de API

Para configurar uma chave de API no seu portal, siga estas instruções:

1. No Console do Google Cloud, acesse APIs & Serviços > Credenciais.

   Acessar a página "Credenciais"

2. Na lista suspensa Project, na parte superior da janela do console do Google Cloud, selecione o projeto do Google Cloud em que você criou a API.

   • Se você tiver uma chave de API que queira usar:

     1. Clique em Editar chave de API ao lado da chave de API que você quer usar.
     2. À direita da chave de API, clique em Copiar para copiar a chave de API para a área de transferência.
     3. Clique em Cancelar.

   • Se você precisar criar uma chave de API, siga estas etapas:

     1. Clique em Criar credenciais e, em seguida, selecione Chave de API.
     2. Copie a chave para a área de transferência.
     3. Clique em Fechar.

3. Volte para o portal.

4. Clique em Configurações.

5. Clique na guia APIs e selecione sua API na lista suspensa.

6. Na seção Configurações do APIs Explorer, cole a chave de API no campo Chave de API do Google.

7. Clique em Save.

Como configurar o Firebase

Para configurar o Firebase, siga estas etapas:

1. Abra o console do Firebase.

   • Se você não tiver um projeto do Firebase:

     1. Clique em Adicionar projeto e selecione o nome do projeto do Google Cloud em que sua API se encontra.
     2. No cartão Autenticação, clique em Primeiros passos.
     3. Clique na guia Método de login.
     4. Na seção Provedores de login, ative os provedores que você quer usar.
     5. Na seção Domínios autorizados, clique em Adicionar domínio e adicione o nome de domínio do portal (por exemplo, endpointsportal.example-api.example.com).
     6. Clique em Configuração da Web. O snippet de código personalizado é exibido. Como você precisará usar as informações do snippet nas etapas a seguir, mantenha o Console do Firebase aberto.

   • Se você já tiver um projeto do Firebase, siga estas etapas:

     1. Acesse Desenvolver > Autenticação.
     2. Clique na guia Método de login.
     3. Na seção Domínios autorizados, clique em Adicionar domínio e adicione o nome de domínio do portal (por exemplo, endpointsportal.example-api.example.com).
     4. Clique em Configuração da Web. O snippet de código personalizado é exibido. Como você precisará usar as informações do snippet nas etapas a seguir, mantenha o Console do Firebase aberto.

2. Abra outra guia no navegador e acesse o portal.

3. Clique em Configurações.

4. Na página Configurações, clique na guia APIs e selecione sua API na lista suspensa.

5. Siga estas etapas na seção Configurações do APIs Explorer:

   1. Copie o valor do campo apiKey do snippet de código do Firebase e cole-o no campo Chave de API do Google.
   2. Copie o valor do campo authDomain do snippet de código do Firebase e cole-o no campo domínio Auth do Firebase.

6. Clique em Save.

Consulte a documentação do Firebase para mais informações.

Como configurar o Auth0

Use a seguinte lista geral de tarefas para configurar o Auth0 e seu portal:

Tarefa 1: verificar se há uma API Auth0 para o serviço do Cloud Endpoints.

Tarefa 2: configurar o aplicativo do Auth0.

Tarefa 3: configurar o Auth0 no portal.

Tarefa 1: verificar se há uma API Auth0 para o serviço do Cloud Endpoints

1. Faça login no painel do Auth0.

2. Na barra de navegação esquerda, clique em APIs. Se houver um público-alvo da API no formato https://SERVICE_NAME, em que SERVICE_NAME for o nome do seu serviço do Endpoints, você já terá criado uma API. Continue com a próxima tarefa para definir as configurações do aplicativo Auth0.

   Caso contrário, crie uma API:

   1. Clique em + Criar API.
   2. Insira um nome.

   3. No campo Identificador, insira um URL no formato https://SERVICE_NAME.

      Substitua SERVICE_NAME pelo nome do serviço do Endpoints. Se você não tiver certeza do nome do serviço, consulte Como conseguir o nome e o ID de configuração do serviço para saber como encontrar o nome do seu serviço do Endpoints.

   4. Clique em Criar.

Tarefa 2: configurar o aplicativo do Auth0

1. No Painel do Auth0, clique em Aplicativos na barra de navegação à esquerda.
2. Selecione seu aplicativo do Auth0 ou clique em + Criar aplicativo para criar um novo.

3. Na guia Configurações do seu aplicativo, role para baixo e adicione o URL de redirecionamento OAuth do portal ao campo URLs de callback permitidos. O URL de redirecionamento OAuth do portal é o URL do seu portal mais /oauth/redirect (por exemplo, https://endpointsportal.example-api.example.com/oauth/redirect).

   O campo URLs de callback permitidos aceita vários URLs separados por uma vírgula. Verifique se o URL inserido não inclui o caractere / à direita.

4. Clique em Save Changes.

   Como você precisará dessas informações nas etapas a seguir, mantenha a guia do navegador Configurações do Auth0 aberta.

Tarefa 3: configurar o Auth0 no portal

1. Abra outra guia no navegador e acesse o portal.
2. Clique em Configurações.
3. Na página Configurações, clique na guia APIs e selecione sua API na lista suspensa.

4. Siga estas etapas na seção Configurações do APIs Explorer:

   1. Copie o valor do campo ID do cliente no Painel do Auth0 e cole-o no campo ID do cliente do Auth0.
   2. Copie o valor do campo Domínio no Painel do Auth0 e cole-o no campo Domínio do Auth0.

5. Clique em Save.

Para mais informações sobre como configurar o Auth0, consulte Visão geral do painel do Auth0 (em inglês) na documentação do Auth0.