Como começar a usar a biblioteca Requests em Python

Introdução

Em vários aplicativos Web, é comum conectar-se a vários serviços de terceiros usando APIs. Ao usar essas APIs, você tem acesso a dados como informações meteorológicas, placares esportivos, listas de filmes, tweets, resultados de mecanismo de busca e fotos. Também é possível usar as APIs para adicionar funcionalidades ao seu app. Exemplos dessas funcionalidades são pagamentos, agendamentos, e-mails, traduções, mapas e transferência de arquivos. Se você tivesse que criar qualquer uma dessas funcionalidades por contra própria, levaria muito tempo, mas com as APIs pode levar somente alguns minutos para se conectar a uma funcionalidade e acessar seus recursos e dados.

Neste artigo, aprenderemos sobre a biblioteca Requests (Solicitações) do Python, que permite que você envie solicitações HTTP em Python.

Uma vez que o uso de uma API implica em enviar solicitações HTTP e receber respostas, a biblioteca Requests permite que você utilize APIs no Python. Vamos demonstrar o uso de uma API de tradução de idioma aqui para você veja um um exemplo de como ela funciona.

Visão geral rápida de solicitações HTTP

As solicitações HTTP consistem na maneira como a Web funciona. Toda vez que você navega para uma página Web, seu navegador realiza várias solicitações para o servidor da página da Web. Então, o servidor responde com todos os dados necessários para renderizar a página e, na sequência, o seu navegador renderiza a página para que a veja.

O processo genérico é o que segue: um cliente (como um navegador ou um script Python usando as Requests) enviará alguns dados para um URL e, em seguida, o servidor localizado no URL irá ler os dados, decidir o que fazer com os dados e retornar uma resposta para o cliente. Por fim, o cliente pode decidir o que fazer com os dados na resposta.

Parte dos dados que o cliente envia em uma solicitação representa o método da solicitação. Alguns métodos de solicitação comuns são o GET, POST e o PUT. Normalmente, as solicitações GET são somente para leitura de dados, sem alterar nada, ao passo que as solicitações POST e PUT são geralmente usadas para modificar os dados no servidor. Por exemplo, a API Stripe permite que você utilize as solicitações POST para criar uma nova cobrança para que um usuário possa comprar algo do seu app.

Ao enviar uma solicitação de um script Python ou uma solicitação dentro de um app Web, caberá a você - o desenvolvedor - decidir o que será enviado em cada solicitação e o que será feito com a respectiva resposta. Assim, vamos explorar isso enviando primeiro uma solicitação para o Scotch.io e, depois, usando uma API de tradução de idiomas.

Instalar a Requests do Python

Antes de fazermos qualquer coisa, precisamos instalar a biblioteca. Assim, vamos prosseguir com a instalação da requests, usando o pip. Se você ainda não tiver um ambiente virtual, é uma boa ideia criar um primeiro.

pip install requests

Nossa primeira solicitação

Para começar, vamos usar a Requests para solicitar o site Scotch.io. Crie um arquivo chamado script.py e adicione o seguinte código a ele. Neste artigo, não teremos muito código para trabalhar, de modo que, quando algo mudar, você somente poderá atualizar o código existente, em vez de adicionar novas linhas.

import requests

res = requests.get('https://scotch.io')

print(res)

Dessa forma, tudo o que esse código está fazendo é enviar uma solicitação GET para o Scotch.io. Esse é o mesmo tipo de solicitação que o seu navegador enviou para visualizar essa página. A única diferença, porém, é que a biblioteca Requests, na verdade, não consegue processar páginas em HTML. Assim, em vez de processar a página, você receberá apenas o HTML bruto e outras informações de resposta.

Estamos usando a função .get() aqui, mas a Requests permite que você utilize outras funções, como .post() e .put() para também enviar essas solicitações.

Você pode executá-la executando o arquivo script.py.

python script.py

Aqui está o que você recebe como resultado:

Códigos de Status

A primeira coisa que podemos fazer é verificar o código de status. Os códigos HTTP variam de 1XX a 5XX. Os códigos de status comuns que você provavelmente viu são 200, 404 e 500.

Aqui está uma visão geral rápida do que cada código de status significa:

• 1XX - Informação
• 2XX - Sucesso
• 3XX - Redirecionar
• 4XX - Erro de cliente (você cometeu um erro)
• 5XX - Erro de servidor (eles cometeram um erro)

Geralmente, o que você está procurando ao realizar suas próprias solicitações são os códigos de status próximos do código 200.

A Requests reconhece que os códigos de status 4XX e 5XX são erros. Assim, se esses códigos de status forem retornados, significa que o objeto de resposta da solicitação retorna False.

Você pode testar se uma solicitação respondeu com sucesso, verificando se a resposta é verdadeira. Por exemplo:

if res:
    print('Response OK')
else:
    print('Response Failed')

A mensagem “Houve falha na resposta” aparecerá apenas se um código de status de 400 ou 500 for retornado. Tente alterar o URL para algo sem sentido para ver a resposta falhar com um código 404.

Você pode verificar o código de status diretamente, adicionando:

print(res.status_code)

Isso mostrará o código de status diretamente para que você mesmo possa verificar o número.

Cabeçalhos

Outra coisa que você pode receber da resposta são os cabeçalhos. Você pode verificá-los usando o dicionário de cabeçalhos no objeto de resposta.

print(res.headers)

Os cabeçalhos são enviados com a solicitação e retornados na resposta. Os cabeçalhos são usados para que o cliente e o servidor saibam como interpretar os dados que estão sendo enviados e recebidos na solicitação/resposta

Nós conseguimos ver os diversos cabeçalhos que são retornados. Muitas vezes você não precisará usar as informações do cabeçalho diretamente, mas elas ficarão disponíveis, caso precise delas.

Normalmente, o tipo de conteúdo é aquele que você pode precisar, pois ele revela o formato dos dados, por exemplo, HTML, JSON, PDF, texto, etc. O tipo de conteúdo, porém, é normalmente tratado pelas Requests para que você possa acessar os dados que são retornados.

Texto de resposta

E, por fim, se examinarmos o res.text (isto funciona para os dados de texto, como a página HTML que estamos visualizando), podemos ver tudo o que o HTML precisou para compilar a página inicial do Scotch. A página não será processada, mas podemos ver que, aparentemente, ela pertence ao Scotch. Se você salvou isso em um arquivo e o abriu, você veria algo que lembraria o site do Scotch. Em uma situação real, várias solicitações são feitas para que uma única página Web carregue coisas como imagens, scripts e folha de estilos, etc. Assim, se você salvar somente o HTML em um arquivo, a página não ficará parecida com a página do Scotch.io que você vê em seu navegador, pois só foi realizada uma solicitação para obter os dados de HTML.

print(res.text)

Usando a API de tradução

Agora, vamos prosseguir para algo mais interessante. Utilizaremos a API Yandex Translate para realizar uma solicitação para traduzir algum texto para um idioma diferente.

Para usar a API, primeiro é necessário inscrever-se. Depois de se inscrever, vá para a API Translate e crie uma chave de API. Assim que tiver a chave da API, adicione-a ao seu arquivo como uma constante. Aqui está o link onde você pode fazer todas essas coisas: https://tech.yandex.com/translate/

API_KEY = 'your yandex api key'

Precisamos de uma chave API para que o Yandex possa nos autenticar sempre que quisermos usar a API deles. A chave da API é uma forma leve de autenticação, pois ela é adicionada ao final da URL da solicitação, quando for enviada.

Para saber qual URL precisamos enviar para usar a API, podemos examinar a documentação do Yandex.

Se procurarmos lá, veremos todas as informações necessárias para usarmos a API Translate deles informação necessária para usar a API Translate deles para traduzir textos.

Quando vemos um URL com “e” comercial (&), pontos de interrogação (? ) e sinais de igual (=), é certo que o URL é feito para pedidos de GET. Esses símbolos especificam os parâmetros que acompanham o URL.

Normalmente, as coisas entre chaves ([]) serão opcionais. Neste caso, formato, opções e retorno de chamada são opcionais, enquanto chave, texto e idioma são necessários para a solicitação.

Vamos adicionar um código para enviar para aquele URL. Você pode substituir a primeira solicitação que criamos por esta:

url = 'https://translate.yandex.net/api/v1.5/tr.json/translate'
res = requests.get(url)

Existem duas maneiras de adicionar os parâmetros. Podemos anexá-los diretamente ao final do URL, ou podemos fazer com que as Requests façam isso por nós. Para fazer essa última, podemos criar um dicionário para nossos parâmetros. Os três itens que precisamos são a chave, o texto e o idioma. Vamos criar o dicionário usando a chave da API, 'Hello' para o texto e 'en-es' como o idioma, o que significa que queremos traduzir do inglês para o espanhol.

Se precisar saber qualquer outro código de idioma, procure aqui. Você está procurando pela coluna 639-1.

Criamos um dicionário de parâmetros usando a função dict() e enviando as chaves e os valores que queremos em nosso dicionário.

params = dict(key=API_KEY, text='Hello', lang='en-es')

Agora, tomamos o dicionário de parâmetros e o enviamos para a função .get().

res = requests.get(url, params=params)

Ao enviarmos os parâmetros desta maneira, as Requests prosseguirão e adicionarão os parâmetros ao URL para nós.

Agora, vamos adicionar uma instrução de impressão relacionada ao texto da resposta e visualizaremos o que será retornado na resposta.

print(res.text)

Vemos três coisas. Vemos o código de status, que é exatamente o mesmo código de status da resposta, propriamente dita; vemos o idioma que especificamos e o texto traduzido dentro da lista. Então você deverá ver 'Hola' como o texto traduzido.

Tente novamente com en-fr como o código de idioma e você deverá ver 'Bonjour' na resposta agora.

params = dict(key=API_KEY, text='Hello', lang='en-fr')

Vamos examinar os cabeçalhos dessa resposta em particular.

print(res.headers)

Obviamente, os cabeçalhos devem ser diferentes, pois estamos nos comunicando com um servidor diferente; neste caso, porém, o tipo de conteúdo é o application/json, em vez de text/html. Isso significa que os dados podem ser interpretados como JSON.

Quando o application/json for o tipo de conteúdo da resposta, conseguimos fazer com que as Requests convertam a resposta em um dicionário e uma lista, de modo que possamos acessar os dados mais facilmente.

Para ter os dados analisados como JSON, usamos o método .json() no objeto de resposta.

Se você o imprimir, verá que os dados parecem iguais, mas o formato é ligeiramente diferente.

json = res.json()
print(json)

O motivo dessa diferença está no fato de que ele n qual ele é diferente é porque ele já não é um texto simples que você obteve do res.text. Desta vez, é uma versão impressa de um dicionário.

Vamos supor que queiramos acessar o texto. Considerando que agora se trata de um dicionário, poderemos usar a sshave de texto

print(json['text'])

Agora, vemos apenas os dados dessa chave específica. Neste caso, estamos examinando uma lista de um item; assim, se quisermos pegar esse texto diretamente na lista, poderemos acessá-lo pelo índice.

print(json['text'][0])

Agora, a única coisa que vemos é a palavra traduzida.

É claro que, se alterarmos as coisas em nossos parâmetros, vamos receber resultados diferentes. Vamos alterar o texto que será traduzido de Hello para Goodbye, alterar o idioma de chegada de volta para espanhol e enviar a solicitação novamente.

params = dict(key=API_KEY, text='Goodbye', lang='en-es')

Tente traduzir um texto maior em diferentes idiomas e veja quais respostas a API dará a você.

Casos de erro da API de tradução

Por fim, vamos examinar um caso de erro. Nem sempre tudo funciona. Assim, precisamos saber reconhecer quando isso acontece.

Tente alterar sua chave de API, removendo um caractere. Quando fizer isso, sua chave de API não será mais válida. Então, tente enviar uma solicitação.

Se você examinar o código de status, eis o que você receberá:

print(res.status_code)

Portanto, quando estiver usando a API, você vai querer verificar se as coisas foram bem-sucedidas ou não, para que você possa lidar com os casos de erro de acordo com as necessidades do seu app.

Conclusão

Veja o que aprendemos hoje:

• Como as solicitações HTTP funcionam
• Os vários códigos de status possíveis em uma resposta
• Como enviar solicitações e receber respostas usando a biblioteca Requests do Python
• Como usar uma API de tradução de idioma para traduzir textos
• Como converter respostas de conteúdo application/JSON em dicionários

Se quiser fazer mais, confira esta lista para ver as diferentes APIs disponíveis e tente usá-las com a Requests do Python.