GSP294

Visão geral

As APIs (interfaces de programação de aplicativos) são programas de software que permitem aos desenvolvedores acessar recursos e dados de computação. As empresas de diversas áreas disponibilizam APIs públicas para permitir que devs integrem bibliotecas, ferramentas ou serviços especializados a codebases e aplicativos próprios.

Neste laboratório, trataremos da arquitetura e do funcionamento básico das APIs. Você vai aprender na prática como configurar e executar métodos da API Cloud Storage no Google Cloud Shell e entender os princípios fundamentais sobre comunicação, arquitetura e autenticação das APIs. A experiência prática adquirida com APIs também poderá ser aplicada em outros laboratórios ou projetos.

O que é uma API e por que usar?

Devs conseguem fazer muito mais quando têm acesso a dados e recursos de computação. É muito mais fácil usar uma API em vez de criar um programa, método ou conjunto de dados a partir do zero. As APIs são desenvolvidas com base no princípio da abstração, ou seja, se quiser usá-las no seu ambiente, você não precisa saber como funcionam nem sobre sua complexidade.

O público-alvo das APIs são devs e, por isso, elas não costumam ter uma interface gráfica do usuário (GUI). Mas essa nem sempre é a regra. Com o APIs Explorer, uma ferramenta do Google, é possível trabalhar com várias APIs do Google de maneira interativa. Se quiser saber mais, confira o laboratório APIs Explorer: Qwik Start.

APIs do Cloud

O Google oferece APIs que podem ser aplicadas a várias áreas e setores diferentes. Elas são bastante utilizadas em fluxos de trabalho de desenvolvimento da Web, machine learning, ciência de dados e administração de sistemas. No entanto, esses são apenas alguns dos casos de uso. Por exemplo, se acessar o site AnyAPI, você vai encontrar muitas APIs disponíveis.

Quando provisiona um novo projeto do Google Cloud para uma instância de laboratório, o Qwiklabs ativa a maioria das APIs em segundo plano para você já começar a trabalhar nas tarefas. No entanto, se criar projetos do GCP sem usar o Qwiklabs, será preciso ativar algumas APIs por conta própria.

À medida que sua experiência no Google Cloud aumentar, você vai usar mais APIs no seu fluxo de trabalho, até passar a integrar e usar praticamente só as APIs do Cloud nos ambientes locais, raramente usando o console do Cloud para executar ferramentas e serviços. Há dezenas de laboratórios disponíveis que ensinam na prática a usar várias APIs do Google em diferentes linguagens.

Neste laboratório, você vai consultar na Biblioteca de APIs quais APIs do Google estão disponíveis.

Objetivos

Neste laboratório, você vai aprender sobre:

• APIs do Google
• Arquitetura das APIs
• Protocolo e métodos HTTP
• Endpoints
• REST (Representational State Transfer) e RESTful APIs
• JSON (JavaScript Object Notation)
• Serviços de autenticação de APIs

Pré-requisitos

Este laboratório básico é indicado para quem tem pouco ou nenhum conhecimento de APIs ou experiência com as APIs do Google. Não é obrigatório, embora seja recomendável, conhecimento sobre os ambientes de shell e das ferramentas de interface de linha de comando. Recomendamos também que você faça primeiro os laboratórios abaixo para conhecer melhor o console do Cloud e o Cloud Storage:

• Um tour pelo Qwiklabs e pelo Google Cloud
• Cloud Storage: Qwik Start – Console do Cloud

Role a tela para baixo e siga as etapas para configurar o ambiente do laboratório.

Configuração e requisitos

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.

Como iniciar seu laboratório e fazer login no console do Google Cloud

1. Clique no botão Começar o laboratório. Se for preciso pagar por ele, uma caixa de diálogo vai aparecer para você selecionar a forma de pagamento. No painel Detalhes do Laboratório, à esquerda, você vai encontrar o seguinte:

   • O botão Abrir Console do Google Cloud
   • O tempo restante
   • As credenciais temporárias que você vai usar neste laboratório
   • Outras informações, se forem necessárias

2. Se você estiver usando o navegador Chrome, clique em Abrir console do Google Cloud ou clique com o botão direito do mouse e selecione Abrir link em uma janela anônima.

   O laboratório ativa os recursos e depois abre a página Fazer Login em outra guia.

   Dica: coloque as guias em janelas separadas lado a lado.

   Observação: se aparecer a caixa de diálogo Escolher uma conta, clique em Usar outra conta.

3. Se necessário, copie o Nome de usuário abaixo e cole na caixa de diálogo Fazer login.

   {{{user_0.username | "Username"}}}

   Você também encontra o nome de usuário no painel Detalhes do Laboratório.

4. Clique em Próxima.

5. Copie a Senha abaixo e cole na caixa de diálogo de Olá.

   {{{user_0.password | "Password"}}}

   Você também encontra a senha no painel Detalhes do Laboratório.

6. Clique em Próxima.

   Importante: você precisa usar as credenciais fornecidas no laboratório, e não as da sua conta do Google Cloud. Observação: se você usar sua própria conta do Google Cloud neste laboratório, é possível que receba cobranças adicionais.

7. Acesse as próximas páginas:

   • Aceite os Termos e Condições.
   • Não adicione opções de recuperação nem autenticação de dois fatores (porque essa é uma conta temporária).
   • Não se inscreva em testes gratuitos.

Depois de alguns instantes, o console do Google Cloud será aberto nesta guia.

Observação: para acessar os produtos e serviços do Google Cloud, clique no Menu de navegação ou digite o nome do serviço ou produto no campo Pesquisar.

Ativar o Cloud Shell

O Cloud Shell é uma máquina virtual com várias 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. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.

2. Clique nas seguintes janelas:

   • Continue na janela de informações do Cloud Shell.
   • Autorize o Cloud Shell a usar suas credenciais para fazer chamadas de APIs do Google Cloud.

Depois de se conectar, você verá que sua conta já está autenticada e que o projeto está configurado com seu Project_ID, . A saída contém uma linha que declara o projeto PROJECT_ID para esta sessão:

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

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

3. (Opcional) É possível listar o nome da conta ativa usando este comando:

gcloud auth list

4. Clique em Autorizar.

Saída:

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Opcional) É possível listar o ID do projeto usando este comando:

gcloud config list project

Saída:

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Observação: consulte a documentação completa da gcloud no Google Cloud no guia de visão geral da gcloud CLI.

Definir a região do projeto

Execute este comando para escolher a região do seu projeto:

gcloud config set compute/region {{{project_0.default_region | Region}}}

Como as APIs funcionam?

Arquitetura das APIs

Uma API, ou interface de programação do aplicativo, é um conjunto de métodos que permite a comunicação entre programas. Para se comunicarem bem, eles precisam seguir um protocolo claro de transferência e interpretação de dados. A Internet é o canal de comunicação padrão que as APIs usam para transmitir solicitações e respostas. As APIs baseadas na Web usam o modelo cliente-servidor como arquitetura para a troca de informações. O cliente é um dispositivo de computação que solicita determinado recurso ou dado de computação, e o servidor é onde ficam armazenados os dados e/ou recursos de computação e que interpreta e atende à solicitação do cliente.

Protocolo e métodos HTTP

As APIs usam a Web para se comunicar, e várias delas seguem o protocolo HTTP, que especifica regras e métodos para a troca de dados entre clientes e servidores pela Internet. As APIs que utilizam o protocolo HTTP usam métodos de solicitação HTTP (ou "verbos HTTP") para transmitir solicitações de clientes a servidores. Os métodos de solicitação HTTP usados com frequência são GET, POST, PUT e DELETE. O método GET ajuda na busca de dados em um servidor, o PUT substitui dados ou cria outros, o POST é usado principalmente para gerar recursos e o DELETE remove de um servidor os dados ou recursos que o cliente especificar.

Endpoints

As APIs usam métodos HTTP para interagir com dados ou serviços de computação hospedados em um servidor. Esses métodos só serão úteis se for possível acessar recursos específicos com consistência. As APIs utilizam endpoints, ou canais de comunicação, para permitir que os clientes acessem facilmente e sem problemas os recursos que precisam. Os endpoints são pontos de acesso a dados ou recursos de computação hospedados em um servidor e assumem a forma de um URI de HTTP. Eles são adicionados ao URL de base de uma API para criar um caminho até um recurso ou contêiner de recursos. Endpoints também aceitam incluir strings de consulta, que possibilitam transmitir variáveis necessárias à solicitação feita por uma API.

APIs REST e RESTful

As APIs RESTful usam métodos de solicitação, endpoints e o protocolo HTTP. Elas ficam no servidor e implementam as solicitações do cliente. Esse modelo define uma estrutura de endpoints (substantivos) em que os métodos HTTP (verbos) atuam, e as APIs usam tal estrutura para atender a solicitações. Em resumo: uma API RESTful usa o modelo cliente-servidor, segue o protocolo HTTP, utiliza métodos de solicitação HTTP e endpoints para acessar recursos específicos.

Teste seu conhecimento

Responda às perguntas de múltipla escolha a seguir sobre os conceitos que estudamos até agora.

Tarefa 1: usar a biblioteca de APIs

Nesta seção, vamos estudar a biblioteca de APIs, e você vai ativar uma API. A biblioteca de APIs centraliza todas as APIs do Google, e com ela você consegue ativar, desativar e gerenciar as APIs dos seus projetos.

1. Para acessá-la, abra o menu de navegação e selecione APIs e serviços > Biblioteca.

A biblioteca de APIs oferece acesso rápido, documentações e opções de configuração para mais de 200 APIs do Google. Mesmo ficando no Console, pela biblioteca é possível acessar todas as APIs do Google, não somente àquelas relacionadas ao Google Cloud. Ou seja, as APIs são essenciais para os serviços do Google, mas nem todas as APIs do Cloud estão vinculadas ao Google Cloud.

Agora, para praticar, você vai ativar uma API na biblioteca de APIs. Vamos supor que você desenvolve recursos móveis para um site de exercícios físicos e quer usar a API Google Fitness para criar um app.

2. Primeiro, digite API Fitness e pressione ENTER na barra Pesquisar APIs e serviços.
3. Clique em Fitness API na lista de resultados. Depois clique em Ativar.

A página Fitness API vai abrir, e o Status da API vai ficar como Ativado.

A biblioteca de APIs tem links para tutoriais, documentações, termos de serviço e métodos interativos encontrados no APIs Explorer. No painel APIs e serviços, você pode conferir métricas e informações de uso. Nessa página, é possível conferir e solicitar cotas, controlar o acesso a recursos e dados e verificar métricas.

4. Selecione a guia COTAS E LIMITES DO SISTEMA para ver um destes recursos funcionando.

5. Aqui é possível saber quantas consultas a API permite por dia/minuto.

Parabéns! Você provisionou uma API que não faz parte do Cloud. Nas próximas seções, vamos tratar da arquitetura e do funcionamento básico das APIs. Posteriormente, você trabalhará na prática com a API Cloud Storage.

Teste seu conhecimento

Responda às perguntas de múltipla escolha a seguir sobre os conceitos que estudamos até agora.

Tarefa 2: criar um arquivo JSON no console do Cloud

Para aplicar o que aprendeu, faça chamadas da API Cloud Storage REST/JSON no Cloud Shell para criar buckets e fazer upload de conteúdo.

1. Em uma nova guia, abra API Google Cloud Storage JSON. Note que a API está ativada.

2. No Cloud Shell, execute o seguinte comando para criar e editar o arquivo values.json:

nano values.json

3. No editor de texto nano, copie e cole o seguinte, lembrando que, como o bucket precisa de um nome exclusivo, o ID do projeto será usado no nome do bucket:

{ "name": "{{{project_0.project_id | Project_ID}}}-bucket", "location": "us", "storageClass": "multi_regional" } Observação: o ID do projeto pode ser o nome do bucket porque ele é globalmente exclusivo.

4. Pressione CTRL+X, Y e ENTER para sair do nano.

Você acabou de criar um arquivo JSON com um objeto e estes três pares de chave-valor: name, location e storageClass. Esses são os mesmos valores necessários para criar um bucket com a ferramenta de linha de comando gsutil ou no console.

Para criar um bucket com a API REST/JSON do Cloud Storage, você vai precisar das políticas de autenticação e autorização adequadas.

Tarefa 3: autenticar e autorizar a API JSON/REST do Cloud Storage

Autenticação e autorização

Embora às vezes usados como sinônimos, autenticação e autorização não são a mesma coisa.

• A autenticação é a determinação da identidade de um cliente.
• A autorização é quando se determina quais permissões um cliente autenticado tem para um conjunto de recursos.

Ela identifica quem você é, e a autorização determina o que você pode fazer.

As APIs do Google usam três serviços de autenticação/autorização: "Chaves de API", "Contas de serviço" e "OAuth". As APIs usam um desses serviços de autenticação, dependendo dos recursos solicitados e de onde elas forem chamadas.

Chaves de API

As chaves de API são tokens secretos, que geralmente aparecem como uma string criptografada. Gerar e usar essas chaves é algo rápido. É comum que as APIs que usam métodos ou dados públicos para agilizar o trabalho de devs adotem chaves de API na autenticação de usuários.

No Google Cloud, essas chaves identificam o projeto que está fazendo a chamada para uma API e permitem a associação de informações de uso a ele, conseguindo rejeitar chamadas de projetos que ainda não receberam acesso ou que não foram ativados pela API.

OAuth

O formato dos tokens OAuth e das chaves de API são parecidos, mas o OAuth é mais seguro e pode ser vinculado a contas ou identidades de usuários. Esses tokens são muito utilizados com APIs que concedem ao desenvolvedor acesso a dados do usuário.

Chaves de API permitem que os desenvolvedores acessem todos os recursos de uma API, já os IDs de cliente OAuth atual com base no escopo. Identidades diferentes recebem privilégios distintos.

Contas de serviço

Uma conta de serviço é um tipo especial de Conta do Google que pertence ao seu aplicativo ou a uma máquina virtual (VM), e não a um usuário final específico. O app passa a ter a identidade da conta de serviço na hora de chamar as APIs do Google, evitando o envolvimento direto dos usuários.

Para usar uma conta de serviço, forneça a chave privada da conta ao seu aplicativo ou use as contas de serviço integradas disponíveis quando executar no Cloud Functions, Google App Engine, Compute Engine ou Google Kubernetes Engine.

O laboratório Contas de serviço e papéis: noções básicas trata especificamente de contas de serviço e papéis.

Como o Cloud Storage é uma plataforma que hospeda e dá acesso a dados do usuário, você precisa gerar um token OAuth antes de usar os serviços.

1. Abra o OAuth 2.0 Playground em uma nova guia. Esse serviço permite gerar tokens OAuth com facilidade.

2. Role a tela para baixo e selecione Cloud Storage API V1.

3. Em seguida, selecione o escopo https://www.googleapis.com/auth/devstorage.full_control:

4. Clique na caixa azul com o texto Authorize APIs. A página de login do Google vai abrir.

5. Selecione o nome de usuário e clique em Allow quando as permissões forem solicitadas.

O OAuth 2.0 Playground vai abrir, e na Etapa 2 haverá um código de autorização gerado.

6. Clique em Exchange authorization code for tokens. Se a Etapa 3 aparecer, clique no painel da etapa 2.

7. Copie o token para usar na próxima etapa.

Tarefa 4: crie um bucket com a API JSON/REST do Cloud Storage

1. Volte para a sessão do Cloud Shell. No prompt da CLI, digite ls e pressione Enter. Os arquivo values.json, que você criou, e o arquivo README-cloudshell.txt vão aparecer:

Saída:

README-cloudshell.txt values.json

2. Execute o comando abaixo para definir o token OAuth2 como uma variável de ambiente. Substitua <YOUR_TOKEN> pelo token de acesso que você gerou.

export OAUTH2_TOKEN=<YOUR_TOKEN>

3. Execute o seguinte comando para definir o ID do projeto como uma variável de ambiente:

export PROJECT_ID=$(gcloud config get-value project)

4. Agora execute o seguinte comando para criar um bucket do Cloud Storage:

curl -X POST --data-binary @values.json \ -H "Authorization: Bearer $OAUTH2_TOKEN" \ -H "Content-Type: application/json" \ "https://www.googleapis.com/storage/v1/b?project=$PROJECT_ID"

5. A saída será parecida com isso:

{ "kind": "storage#bucket", "selfLink": "https://www.googleapis.com/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7", "id": "qwiklabs-gcp-02-5d551758b5a7", "name": "qwiklabs-gcp-02-5d551758b5a7", "projectNumber": "670840659006", "metageneration": "1", "location": "US", "storageClass": "MULTI_REGIONAL", "etag": "CAE=", "timeCreated": "2020-11-11T06:41:40.901Z", "updated": "2020-11-11T06:41:40.901Z", "iamConfiguration": { "bucketPolicyOnly": { "enabled": false }, "uniformBucketLevelAccess": { "enabled": false } }, "locationType": "multi-region" } Observação: erros como "Use of this bucket name is restricted" ou "Sorry, that name is not available" indicam que há um conflito com a convenção universal de nomes de buckets. Substitua o nome do bucket no arquivo values.json.

Essa solicitação é o resultado acumulado do seu aprendizado. Você usou a ferramenta da CLI curl para fazer uma solicitação de método HTTP POST. Você transmitiu o arquivo values.json para o corpo da solicitação. Você transmitiu o token OAuth e uma especificação JSON como cabeçalhos da solicitação. Essa solicitação foi encaminhada para o endpoint do Cloud Storage, que contém um parâmetro de string de consulta configurado como o ID do seu projeto.

Conferir o bucket do Cloud Storage que você acabou de criar

• Para acessar o bucket recém-criado, selecione Cloud Storage > Buckets no menu de navegação.

Testar a tarefa concluída

Clique em Verificar meu progresso para conferir a tarefa realizada. A pontuação de avaliação vai atualizar assim que você criar um bucket com a API JSON/REST do Cloud Storage.

Criar um bucket com a API JSON/REST do Cloud Storage

Tarefa 5: fazer upload de um arquivo usando a API JSON/REST do Cloud Storage

Se quiser, use a API JSON/REST do Cloud Storage para o upload de arquivos em buckets.

1. Salve a seguinte imagem no computador com o nome demo-image.png:

2. Na sessão do Cloud Shell, clique no ícone do menu de três pontos na parte de cima à direita. Clique em Fazer upload > Escolher arquivo. Selecione o arquivo demo-image.png. Isso vai adicionar a imagem ao seu diretório.

3. Execute o seguinte comando para conseguir o caminho do arquivo de imagem:

realpath demo-image.png

A saída será parecida com isso:

/home/gcpstaging25084_student/demo-image.png

4. Execute o comando a seguir para definir o caminho do arquivo como uma variável de ambiente. Substitua <DEMO_IMAGE_PATH> pela resposta do comando anterior:

export OBJECT=<DEMO_IMAGE_PATH>

5. Execute o comando a seguir para definir o nome do bucket como uma variável de ambiente:

export BUCKET_NAME={{{project_0.project_id | Project_ID}}}-bucket

6. Agora execute o comando abaixo para fazer o upload da imagem de demonstração para o bucket do Cloud Storage:

curl -X POST --data-binary @$OBJECT \ -H "Authorization: Bearer $OAUTH2_TOKEN" \ -H "Content-Type: image/png" \ "https://www.googleapis.com/upload/storage/v1/b/$BUCKET_NAME/o?uploadType=media&name=demo-image"

A saída será parecida com isso:

{ "kind": "storage#object", "id": "qwiklabs-gcp-02-5d551758b5a7/demo-image/1605077118178936", "selfLink": "https://www.googleapis.com/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7/o/demo-image", "mediaLink": "https://www.googleapis.com/download/storage/v1/b/qwiklabs-gcp-02-5d551758b5a7/o/demo-image?generation=1605077118178936&alt=media", "name": "demo-image", "bucket": "qwiklabs-gcp-02-5d551758b5a7", "generation": "1605077118178936", "metageneration": "1", "contentType": "image/png", "storageClass": "MULTI_REGIONAL", "size": "401951", "md5Hash": "LbpHpwhnApQKQx9IEXjTsQ==", "crc32c": "j5oPrg==", "etag": "CPis3Zvy+ewCEAE=", "timeCreated": "2020-11-11T06:45:18.178Z", "updated": "2020-11-11T06:45:18.178Z", "timeStorageClassUpdated": "2020-11-11T06:45:18.178Z" }

7. Para conferir a imagem adicionada ao bucket, abra o menu de navegação e selecione Cloud Storage > Buckets.

8. Clique no nome do bucket. Você vai ver que a imagem demo-image foi adicionada:

9. Clique no nome da imagem para abrir a página Detalhes do objeto.

Testar a tarefa concluída

Clique em Verificar meu progresso para conferir a tarefa realizada. Se tiver feito corretamente o upload do arquivo usando a API JSON/REST do Cloud Storage, a pontuação da avaliação vai atualizar

Fazer upload de um arquivo usando a API JSON/REST do Cloud Storage

Parabéns!

Neste laboratório, você aprendeu os detalhes sobre APIs e testou na prática o funcionamento da API JSON/REST do Cloud Storage. Tragamos das APIs do Cloud, da arquitetura de uma API, do protocolo e dos métodos HTTP, endpoints, APIs RESTful, JSON e da autenticação de API. Agora você já pode fazer outros laboratórios sobre API no Qwiklabs.

Próximas etapas / Saiba mais

Conheça ainda mais as APIs com os laboratórios a seguir:

• APIs Explorer: Qwik Start
• API Cloud Natural Language: Qwik Start

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 26 de fevereiro de 2024

Laboratório testado pela última vez em 26 de fevereiro 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.