Chamar APIs de um projeto do Google Cloud

1. Antes de começar

Este codelab mostra como criar um projeto do Google Cloud e, em seguida, chamar as APIs do Google Cloud nele.

Pré-requisitos

• Saber navegar no console do Google Cloud.

O que você vai aprender

• Como criar um projeto do Google Cloud.
• Como configurar uma conta de faturamento.
• Como configurar o Cloud Shell.
• Como ativar uma API.
• Como autorizar uma API com uma chave de API.
• Como autorizar uma API com uma conta de serviço.

O que é necessário

• Uma Conta do Google, como uma conta do Gmail ou do Google Workspace.
• Acesso a uma conta do Cloud Billing ou um cartão de crédito para usar para se inscrever no programa de teste sem custo financeiro.

2. Começar a configuração

Esta seção mostra como criar um projeto do Google Cloud, definir uma conta de faturamento e configurar o Cloud Shell.

Criar um projeto do Google Cloud e configurar uma conta de faturamento

Observação:se você ainda não tiver uma conta do Gmail ou do Google Workspace, crie uma primeiro.

1. Faça login no console do Cloud e selecione ou crie um projeto.

Aviso:se você reutilizar um projeto e concluir este codelab, poderá permitir que alguns usuários acessem os recursos dele se não forem desativados após a conclusão.

Lembre-se do ID do projeto, que é mostrado no campo Nome do projeto. O ID é um nome exclusivo em todos os projetos do Google Cloud (o nome acima já foi usado) e será mencionado mais adiante neste codelab como PROJECT_ID.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos do Google Cloud.

Embora este codelab não tenha um custo muito alto, siga as instruções na seção Limpar para encerrar os recursos e evitar custos além deste. Observe que novos usuários do Google Cloud estão qualificados para o teste sem custo financeiro de US$300.

Configurar o Cloud Shell

Neste codelab, você vai usar o Cloud Shell, um ambiente de linha de comando executado no Google Cloud. O Cloud Shell é uma máquina virtual baseada em Debian. Ele contém todas as ferramentas de desenvolvimento necessárias. Ele oferece um diretório principal persistente de 5 GB, o que melhora bastante o desempenho e a autenticação da rede. Isso significa que você só precisa de um navegador para este codelab.

Para ativar o Cloud Shell no Console do Cloud:

1. Clique em Ativar o Cloud Shell.

O provisionamento e a conexão do ambiente podem levar alguns instantes.

Depois de se conectar ao Cloud Shell, você já estará autenticado e o projeto estará configurado com seu PROJECT_ID.

2. Gere uma lista de contas credenciadas:

gcloud auth list

A saída vai ser esta:

Credentialed accounts:
 - <MY_ACCOUNT>@<MY_DOMAIN>.com (active)

Observação:a ferramenta da CLI gcloud vem pré-instalada no Cloud Shell e ajuda a criar e gerenciar recursos do Google Cloud. Para mais informações, consulte a visão geral da ferramenta gcloud.

3. Para ver uma lista dos seus projetos, digite este comando.

gcloud config list project

A saída vai ser esta:

[core]
project = <PROJECT_ID>

Se, por algum motivo, o projeto não estiver configurado, execute este comando para configurá-lo.

gcloud config set project <PROJECT_ID>

O PROJECT_ID é o ID usado nas etapas de configuração. Também é possível procurá-lo no painel do Console do Cloud:

O Cloud Shell também define algumas variáveis de ambiente por padrão, o que pode ser útil quando você executar comandos no futuro.

4. Para ver o ID do projeto, digite o seguinte comando.

echo $GOOGLE_CLOUD_PROJECT

Você verá esta resposta:

<PROJECT_ID>

5. Defina a zona padrão e a configuração do projeto:

gcloud config set compute/zone us-central1-f

É possível escolher uma variedade de zonas diferentes. Para mais informações, consulte Regiões e zonas.

Observação:quando você executa a ferramenta da CLI gcloud na sua máquina, as definições de configuração são mantidas em todas as sessões. No entanto, no Cloud Shell, você precisa definir essas configurações para cada nova sessão ou reconexão.

3. Chamar uma API de um projeto

Este codelab mostra como usar uma API de exemplo (a API Natural Language) para encontrar entidades (como pessoas, lugares e eventos) em um texto e como aproximar o sentimento (nível de aceitação) desse texto. Você vai aprender como:

• Ativar APIs do Google Cloud
• Consiga autorização para a API com chaves de API e contas de serviço.
• Chame a API com curl e bibliotecas de cliente.

Ativar uma API

1. Selecione APIs e Serviços no menu principal do console do Cloud.

2. Selecione + ATIVAR APIS E SERVIÇOS na parte de cima da tela.

3. Agora é possível filtrar e navegar pelas APIs ou acessar diretamente uma com a caixa de pesquisa. Pesquise Natural Language e selecione API Cloud Natural Language.

4. Clique em TESTAR ESTA API.

Se o botão TESTAR ESTA API não aparecer, clique em um dos métodos listados.

Crie uma chave de API

Como você usa curl para enviar uma solicitação à API Natural Language, é necessário gerar uma chave de API para transmitir o URL da solicitação.

1. No console do Cloud, selecione Menu de navegação > APIs e Serviços > Credenciais.

2. Clique em CRIAR CREDENCIAIS e selecione Chave de API:

3. Copie a chave de API gerada e clique em Fechar.

Usar a chave de API para chamar a API

1. Na linha de comando do Cloud Shell, exporte sua chave de API.

export API_KEY=<YOUR_API_KEY>

Substitua <YOUR_API_KEY> pela chave gerada anteriormente.

2. Crie uma solicitação para a API no editor do Cloud Shell ou com um editor do Linux, como o Vim ou o Emacs. Veja os detalhes dos parâmetros em Method: documents.analyzeEntities. Salve a saída em um arquivo chamado request.json:

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Google, headquartered in Mountain View (1600 Amphitheatre Pkwy, Mountain View, CA 940430), unveiled the new Android phone for $799 at the Consumer Electronic Show. Sundar Pichai said in his keynote that users love their new Android phones."
  },
  "encodingType":"UTF8"
}

3. Chame a API com as informações da solicitação.

curl "https://language.googleapis.com/v1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

4. Execute novamente o comando, redirecione a saída para um arquivo e examine o resultado. Os detalhes da saída do arquivo JSON também estão em Method: documents.analyzeEntities.
5. Para mudar o texto a ser analisado no arquivo request.json, substitua o valor content pelo texto de sua escolha.

4. Autorizar com uma conta de serviço

Geralmente, as contas de serviço têm preferência sobre as chaves de API, porque elas oferecem autenticação e autorização. Pense nas contas de serviço como endereços de e-mail para seu app.

1. Volte à seção "Credenciais" da página APIs e Serviços.
2. Selecione Criar credenciais, mas agora selecione Conta de serviço.

3. Forneça um Nome da conta de serviço que descreva a finalidade dela, como "Natural Language Service Account". O sistema sugere um ID. Você também pode adicionar uma descrição. À medida que você aprende mais sobre contas de serviço, fornece à conta de serviço acesso a projetos e concede aos usuários acesso à conta de serviço. Por enquanto, basta clicar em Concluído para criar a conta de serviço.
4. Para criar um par de chaves para a conta de serviço, clique em para editá-la.

Os detalhes da sua conta de serviço serão exibidos.

5. Copie o endereço de e-mail da conta de serviço e volte ao Cloud Shell.
6. No Cloud Shell, crie um par de chaves para sua conta de serviço e defina uma variável de ambiente que aponte para ela:

gcloud iam service-accounts keys create ~/key.json \
  --iam-account <your service account email>
export GOOGLE_APPLICATION_CREDENTIALS="/home/$USER/key.json"

O Google Cloud usa essa variável de ambiente para encontrar as credenciais. Portanto, elas não precisam ser incluídas na chamada de API.

7. Agora você pode chamar a API com o comando:

gcloud ml language analyze-entities --content="Michelangelo Caravaggio, Italian painter, is known for 'The Calling of Saint Matthew'." 

O resultado será o mesmo de antes.

Muitas APIs têm extensas bibliotecas de cliente das quais extrair esses detalhes. Para saber mais sobre bibliotecas de cliente, consulte Bibliotecas de cliente do Cloud. Você também pode ler a documentação das APIs que usa para ver quais bibliotecas de cliente estão disponíveis para elas.

5. Limpar

Não é uma prática recomendada ter uma chave de API irrestrita para projetos. Se alguém tiver acesso a ele, essa pessoa poderá usá-lo sem necessidade de autenticação.

Para excluir essa chave de API:

1. Clique em Menu de navegação > APIs e Serviços > Credenciais.
2. Em Chaves de API, selecione a chave a ser excluída e clique em Excluir.
3. Da mesma forma, em vez de se preocupar com a chave privada da conta de serviço estar desprotegida, em Contas de serviço, selecione a conta de serviço a ser excluída e clique em Excluir.

6. Parabéns

Parabéns! Você aprendeu a criar um projeto do Google Cloud e a chamar uma API dentro do projeto.