Chamar APIs de um projeto do Google Cloud

1. Antes de começar

Neste codelab, você vai aprender a criar um projeto do Google Cloud e chamar as APIs do Google Cloud dele.

Pré-requisitos

• Capacidade de 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 a um cartão de crédito para se inscrever no programa de teste sem custo financeiro.

2. Começar a configuração

Nesta seção, mostramos como criar um projeto do Google Cloud, configurar uma conta de faturamento e 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 recursos nesse projeto se eles não forem desativados quando você terminar.

Guarde o ID do projeto, que aparece no campo Nome do projeto. O ID é um nome exclusivo em todos os projetos do Google Cloud. O nome acima já foi escolhido e é chamado de PROJECT_ID neste codelab.

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 deva custar muito, se tiver algum custo, siga as instruções na seção Limpeza para encerrar os recursos e evitar custos além deste codelab. Novos usuários do Google Cloud podem aproveitar 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 com todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, o que melhora muito o desempenho e a autenticação da rede. Isso significa que tudo que você precisa para este codelab é um navegador.

Para ativar o Cloud Shell no Console do Cloud:

1. Clique em Ativar o Cloud Shell.

O provisionamento e a conexão com o 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

Você vai ver esta saída:

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

Observação:a ferramenta de 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 conferir uma lista dos seus projetos, digite este comando.

gcloud config list project

Você vai ver esta saída:

[core]
project = <PROJECT_ID>

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

gcloud config set project <PROJECT_ID>

O PROJECT_ID é o ID que você usou nas etapas de configuração. Você também pode pesquisar 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 ao executar comandos futuros.

4. Para conferir o ID do projeto, insira 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 de linha de comando gcloud na sua máquina, as configurações de configuração são mantidas em todas as sessões. No entanto, no Cloud Shell, é necessário configurar essas opçõ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 favorabilidade) desse texto. Você vai aprender a:

• Ativar APIs do Google Cloud
• Receba 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. Neste ponto, você pode filtrar e navegar pelas APIs ou acessar uma API diretamente com a caixa Pesquisar. Pesquise Natural Language e selecione API Cloud Natural Language.

4. Clique em TESTAR ESTA API.

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

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.

Use a chave de API para chamar a API

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

export API_KEY=<YOUR_API_KEY>

Substitua <YOUR_API_KEY> pela chave que você gerou anteriormente.

2. Crie uma solicitação para a API no editor do Cloud Shell ou com um editor do Linux, como Vim ou Emacs. Confira 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 o comando novamente, redirecione a saída para um arquivo e examine o resultado. Os detalhes da saída do arquivo JSON também estão em Método: documents.analyzeEntities.
5. Para mudar o texto a ser analisado no arquivo request.json, substitua o valor content pelo texto que você quiser.

4. Autorizar com uma conta de serviço

As contas de serviço são preferíveis às chaves de API porque 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" do menu APIs e serviços.
2. Selecione Criar credenciais, mas desta vez, 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 as contas de serviço, é possível conceder acesso a projetos e usuários. Por enquanto, clique 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 editar a conta.

Os detalhes da sua conta de serviço vão aparecer.

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 para apontar para ele:

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, então elas não precisam ser incluídas na chamada de API.

7. Agora é possível 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 precisa ser o mesmo de antes.

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

5. Limpar

É uma prática ruim ter uma chave de API irrestrita para projetos. Se alguém tiver acesso a ele, poderá usá-lo sem precisar de mais 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 que você quer excluir e clique em Excluir.
3. Da mesma forma, em vez de se preocupar com a falta de proteção da chave privada da conta de serviço, em Contas de serviço, selecione a conta que você quer excluir e clique em Excluir.

6. Parabéns

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