Um guia completo para a biblioteca Requests do Python

Neste guia abrangente, você vai aprender:

• O que é requests, como instalá-la e por que ela é a biblioteca cliente HTTP mais popular do Python.
• Como usá-la com diferentes métodos HTTP.
• O que ela oferece para lidar com as respostas do servidor.
• Quais personalizações de solicitação ela suporta.
• Os cenários avançados cobertos pela biblioteca requests do Python

Vamos nos aprofundar!

Introdução à Biblioteca Requests

Veja o que é Requests, como instalá-la, quando usá-la e o que ela oferece.

Definição

Requests é uma biblioteca HTTP elegante e simples para Python. Em detalhes, ela fornece uma API intuitiva para fazer solicitações (requests) HTTP e lidar com respostas de uma forma fácil e legível por humanos. Com mais de 50 mil estrelas no GitHub e milhões de downloads diários, Requests representa o cliente HTTP mais popular em Python.

Alguns dos principais recursos oferecidos por essa biblioteca incluem uma API vasta que abrange todos os métodos HTTP, tratamento de respostas, personalização de solicitações, autenticação, gerenciamento de certificados SSL e muito mais. Além disso, o módulo Python Requests suporta HTTP/1.1 pronto para uso.

Configuração

A maneira mais fácil e recomendada de instalar Requests é por meio de pip. Em particular, o pacote pip associado à biblioteca Requests é requests. Então, você pode instalar o cliente HTTP com o seguinte comando:

pip install requests

Para usar requests em seu script Python, importe-o com a linha abaixo:

import requests

Formidável! O pacote Requests está instalado e pronto para ser usado.

Casos de uso

Os principais casos de uso da biblioteca Python requests incluem:

• Fazer solicitações HTTP para servidores web: recupere dados de servidores web enviando solicitações GET.
• Consumir APIs: envie solicitações aos endpoints da API e gerencie suas respostas, interagindo com vários serviços da web e acessando seus dados.
• Web scraping: busque documentos HTML associados a páginas da web, que podem então ser analisados usando bibliotecas como BeautifulSoup para extrair informações específicas. Saiba mais em nosso guia de web scraping em Python.
• Testar aplicativos web: simule solicitações HTTP e verifique as respostas, automatizando o processo de teste e garantindo o funcionamento adequado dos serviços web.
• Baixar: recupere arquivos de servidores web, como imagens, documentos ou outros arquivos de mídia, enviando solicitações HTTP GET para os respectivos URLs.

Métodos

Dê uma olhada nos métodos públicos expostos pela biblioteca requests na tabela a seguir:

Como você pode ver, estes abrangem os métodos de solicitação HTTP mais úteis. Saiba mais sobre como usá-los na documentação de API oficial.

É hora de vê-los em ação!

Métodos HTTP

Veja a biblioteca Python requests em ação ao lidar com os métodos GET, POST, PUT, DELETEe HEAD em HTTP.

GET

Em HTTP, o método GET é usado para solicitar um recurso específico de um servidor. É assim que você pode fazer uma solicitação HTTP GET com requests.get():

import requests

# send a GET request to the specified URL

response = requests.get('https://api.example.com/data')

Da mesma forma, você pode obter o mesmo resultado com requests.request() conforme abaixo:

import requests

response = requests.request('GET', 'https://api.example.com/data')

Nesse caso, você precisa especificar manualmente o método HTTP a ser usado com uma variável de string adicional.

POST

O método HTTP POST é usado para enviar dados a um servidor para processamento adicional. Veja como fazer uma solicitação POST com requests.post():

import requests

# data to be sent in the POST request

product = {

'name': 'Limitor 500',

'description': 'The Limitor 500 is a high-performance electronic device designed to regulate power consumption in industrial settings. It offers advanced features such as real-time monitoring, adjustable settings, and remote access for efficient energy management.',

'price': 199.99,

'manufacturer': 'TechCorp Inc.',

'category': 'Electronics',

'availability': 'In Stock'

}

# send a POST request to the specified URL

response = requests.post('https://api.example.com/product', data=product)

Em comparação com uma solicitação GET , desta vez você também precisa especificar os dados a serem enviados ao servidor por meio da opção dados. requests adicionará esses dados ao corpo da solicitação HTTP.

Para corpos JSON, passe seu objeto de dados para a opção json em vez de data:

response = requests.post('https://api.example.com/product', json=product)

De forma equivalente, você pode realizar a mesma solicitação com request.request() da seguinte forma:

import requests

product = {

'name': 'Limitor 500',

'description': 'The Limitor 500 is a high-performance electronic device designed to regulate power consumption in industrial settings. It offers advanced features such as real-time monitoring, adjustable settings, and remote access for efficient energy management.',

'price': 199.99,

'manufacturer': 'TechCorp Inc.',

'category': 'Electronics',

'availability': 'In Stock'

}

response = requests.request('POST', 'https://api.example.com/product', data=product)

PUT

O método PUT é usado para atualizar ou substituir um recurso no servidor. Enviar uma solicitação PUT com o módulo Python requests é fácil e segue um padrão semelhante ao das solicitações POST. O que muda é que o método a ser usado é requests.put(). Além disso, a string do método HTTP em requests.request() será 'PUT'.

PATCH

O método PATCH é usado para aplicar modificações parciais em um recurso on-line. Assim como para solicitações PUT , enviar solicitações PATCH na biblioteca Python requests é semelhante às solicitações POST. O que muda é que o método a ser empregado é requests.patch() e a string do método HTTP em requests.request() é 'PATCH'.

DELETE

O método DELETE é usado para excluir um recurso identificado por um determinado URI. Veja como fazer uma solicitação HTTP DELETE em requests usando o método delete():

import requests

# send a DELETE request for the product with id = 75

response = requests.delete('https://api.example.com/products/75')

Da mesma forma, você pode realizar uma solicitação DELETE com requests.request():

import requests

response = requests.request('DELETE', 'https://api.example.com/products/75')

HEAD

O método HEAD é semelhante a GET, mas solicita apenas os cabeçalhos da resposta, sem o conteúdo real do corpo. Portanto, a resposta retornada pelo servidor para uma solicitação HEAD será equivalente à de uma solicitação GET , mas sem dados do corpo.

Use requests.head() para fazer uma solicitação HTTP HEAD em Python:

import requests

# send a HEAD request to the specified URL

response = requests.head('https://api.example.com/resource')

Da mesma forma, você pode realizar uma solicitação HEAD com requests.request():

import requests

response = requests.request('HEAD', 'https://api.example.com/resource')

Analisando um objeto de resposta a partir de requests

Agora que você sabe como fazer solicitações HTTP com requests, é hora de ver como lidar com objetos de resposta.

Objeto de resposta

Depois de fazer uma solicitação HTTP, requests receberá a resposta do servidor e a mapeará em um objeto Response especial.

Dê uma olhada no exemplo de Python requests abaixo:

import requests

response = requests.get('http://lumtest.com/myip.json')

print(response)

Isso resultará:

<Response [200]>

response é um objeto Response que expõe alguns métodos e propriedades úteis. Explore os mais importantes nas próximas seções!

Aviso: requests nem sempre retornam uma resposta. Em caso de erros (por exemplo, um URL inválido), ele gera uma RequestException. Proteja-se contra essa exceção com a lógica abaixo:

try:

response = requests.get('http://lumtest.com/myip.json')

# handle the response

except requests.exceptions.RequestException as e:

print('An error occurred during the request:', e)

Códigos de status

Quando se trata de HTTP, códigos de status de resposta são valores padronizados retornados pelo servidor para indicar o sucesso, a falha ou qualquer outra condição da solicitação. Esses códigos de status são muito importantes porque fornecem feedback imediato em relação à ao êxito positivo ou negativo da solicitação e, se negativo, ao que deu errado.

Os códigos são particularmente úteis no tratamento de erros, permitindo que o cliente identifique e trate diferentes tipos de erros da forma adequada. Por exemplo, um código de status 4xx indica um erro do lado do cliente (por exemplo, uma solicitação inválida), enquanto um código de status 5xx indica um erro do lado do servidor.

Controlar o código de status geralmente é a primeira etapa para lidar com uma resposta em Python usando a biblioteca requests. Depois de fazer uma solicitação, você deve sempre verificar o código de status da resposta para determinar se a solicitação foi bem-sucedida ou não. Acesse o código de status por meio do atributo status_code do objeto de resposta:

response.status_code # 200

Dependendo do código de status recebido, você deve usar instruções condicionais para lidar com diferentes cenários de forma adequada:

import requests

response = requests.get('http://lumtest.com/myip.json')

# check if the request was successful (status code 200)

if response.status_code == 200:

print('Successful request!')

# handle the response...

elif response.status_code == 404:

print('Resource not found!')

else:

print(f'Request failed with status code: {response.status_code}')

Na maioria dos cenários, você só precisa distinguir entre uma solicitação bem-sucedida e uma resposta de erro. requests simplifica esse processo graças a uma sobrecarga personalizada __bool()__. Especificamente, você pode usar um objeto Response diretamente em uma expressão condicional. Será avaliado True se o código de status estiver entre 200 e 399, caso contrário, False.

Em outras palavras, é possível verificar o resultado bem-sucedido de uma solicitação com esta lógica:

if response:

print('Successful request!')

# handle the response...

else:

print(f'Request failed with status code: {response.status_code}')

Cabeçalhos de resposta

Acesse os cabeçalhos de uma resposta do servidor por meio do atributo headers:

import requests

response = requests.get('http://lumtest.com/myip.json')

response_headers = response.headers

print(response_headers)

Isso gerará:

{'Server': 'nginx', 'Date': 'Thu, 09 May 2024 12:51:08 GMT', 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': '279', 'Connection': 'keep-alive', 'Cache-Control': 'no-store', 'Access-Control-Allow-Origin': '*'}

Como você pode ver, response.headers retorna um objeto semelhante a um dicionário. Isso significa que você pode acessar os valores do cabeçalho por chave. Por exemplo, suponha que você queira acessar o cabeçalho Content-Type da resposta. Veja abaixo como você pode fazer isso:

response_headers['Content-Type'] # 'application/json; charset=utf-8'

Como a especificação HTTP define cabeçalhos como indiferente a maiúsculas e minúsculas, requests permitem que você os acesse sem se preocupar com a maiusculização:

response_headers['content-type'] # 'application/json; charset=utf-8'

Conteúdo de resposta

solicitações fornece atributos e métodos diferentes para acessar a carga útil de uma resposta:

• response.content: retorna o conteúdo da resposta em bytes.
• response.text: retorna o conteúdo da resposta como uma string em Unicode.
• response.json(): retorna o conteúdo codificado em JSON da resposta em um dicionário.

Veja-os em ação no exemplo a seguir:

import requests

response = requests.get('http://lumtest.com/myip.json')

# access the response as bytes

response_bytes = response.content

print(type(response_bytes))

print(response_bytes)

print()

# retrieve the response as text

response_text = response.text

print(type(response_text))

print(response_text)

print()

# retrieve the response as a JSON-encoded dictionary

response_json = response.json()

print(type(response_json))

print(response_json)

print()

http://lumtest.com/myip.json é um endpoint especial que retorna informações sobre o IP do chamador. O resultado do trecho acima será algo como:

<class 'bytes'>

b'{"ip":"45.85.135.110","country":"US","asn":{"asnum":62240,"org_name":"Clouvider Limited"},"geo":{"city":"Ashburn","region":"VA","region_name":"Virginia","postal_code":"20149","latitude":39.0469,"longitude":-77.4903,"tz":"America/New_York","lum_city":"ashburn","lum_region":"va"}}'

<class 'str'>

{"ip":"45.85.135.110","country":"US","asn":{"asnum":62240,"org_name":"Clouvider Limited"},"geo":{"city":"Ashburn","region":"VA","region_name":"Virginia","postal_code":"20149","latitude":39.0469,"longitude":-77.4903,"tz":"America/New_York","lum_city":"ashburn","lum_region":"va"}}

<class 'dict'>

{'ip': '45.85.135.110', 'country': 'US', 'asn': {'asnum': 62240, 'org_name': 'Clouvider Limited'}, 'geo': {'city': 'Ashburn', 'region': 'VA', 'region_name': 'Virginia', 'postal_code': '20149', 'latitude': 39.0469, 'longitude': -77.4903, 'tz': 'America/New_York', 'lum_city': 'ashburn', 'lum_region': 'va'}}

Observe os três formatos de resposta diferentes. Como dicionário, response.json() é particularmente útil porque simplifica o acesso aos dados:

response_json['country'] # 'US'

Para obter mais informações, confira nosso guia sobre como analisar JSON em Python.

Cookies de resposta

Enquanto cookies HTTP são definidos por meio de cabeçalhos, o objeto Response fornece um atributo cookies especial para lidar com eles. Isso retorna um objeto http.cookiejar com os cookies que o servidor enviou de volta.

Dê uma olhada no exemplo abaixo, demonstrando como acessar cookies de um objeto de resposta na biblioteca Python requests:

import requests

# define the login credentials

credentials = {

'username': 'example_user',

'password': 'example_password'

}

# send a POST request to the login endpoint

response = requests.post('https://www.example.com/login', data=credentials)

# access the cookies set by the server

cookies = response.cookies

# print the cookies received from the server

for cookie in cookies:

print(cookie.name, ':', cookie.value)

O trecho de amostra acima pode produzir algo assim:

session_id : be400765483cf840dfbbd39

user_id : 7164

expires : Sat, 01 Jan 2025 14:30:00 GMT

Personalização da solicitação com a biblioteca de solicitações do Python

As solicitações HTTP geralmente envolvem parâmetros especiais de filtragem e cabeçalhos personalizados. Vamos ver como especificá-los em requests.

Parâmetros de string de consulta

Os parâmetros de consulta, também conhecidos como parâmetros de URL, são parâmetros adicionais anexados ao final de um URL em uma solicitação HTTP. Eles fornecem informações extras ao servidor sobre a solicitação, geralmente sobre como filtrar dados e personalizar a resposta.

Considere este URL:

https://api.example.com/data?key1=value1&key2=value2

Neste exemplo, ?key1=value1&key2=value2 é a string de consulta, enquanto key1 e key2 são parâmetros de consulta.

Uma string de consulta começa com ? e consiste em um par de valores-chave separados por um sinal de igual (=) e concatenado por &. Especificar de forma programática essa string de consulta no código Python nem sempre é fácil, especialmente ao lidar com parâmetros opcionais. É por isso que requests oferece a opção params:

import requests

# define query parameters as a dictionary

params = {

'page': 1,

'limit': 10,

'category': 'electronics'

}

# send a GET request to the following URL:

# 'https://api.example.com/products?page=1&limit=10&category=electronics'

response = requests.get('https://api.example.com/products', params=params)

Equivalentemente, você pode passar os parâmetros para requests como uma lista de tuplas:

import requests

# define query parameters as a list of tuples

params = [

('page', '1'),

('limit', '10'),

('category', 'electronics')

]

response = requests.get('https://api.example.com/products', params=params)

Ou como uma string de bytes:

import requests

# define query parameters as a bytes string

params = b'page=1&limit=10&category=electronics'

response = requests.get('https://api.example.com/products', params=params)

Cabeçalhos de solicitação

Para personalizar os cabeçalhos em uma solicitação HTTP em requests, passe-os como um dicionário para a opção headers. Por exemplo, você pode definir uma string personalizada User-Agent em requests com:

import requests

# define custom headers

custom_headers = {

'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',

# other headers...

}

# send a GET request with custom headers

response = requests.get('https://api.example.com/data', headers=custom_headers)

Solicitar cookies

Enquanto os cookies HTTP são enviados ao servidor por meio de cabeçalhos, requests fornece uma opção dedicada de cookies para personalizá-los. Use-o como no exemplo a seguir:

# define custom cookies

custom_cookies = {

'session_id': 'be400765483cf840dfbbd39',

'user_id': '7164'

}

# send a GET request with custom cookies

response = requests.get('https://www.example.com', cookies=custom_cookies)

Note que cookies aceita um dicionário ou um objeto http.cookiejar.

Outras configurações

request oferece uma API rica e há muitas técnicas avançadas disponíveis. Explore alguns dos mais relevantes!

Proxy Setup

A integração de proxy em requests permite que você roteie suas solicitações HTTP por meio de um servidor proxy. Esse é um mecanismo poderoso para ocultar seu endereço IP, ignorar os limitadores de taxa ou acessar conteúdo com restrição geográfica.

Você pode integrar um servidor proxy com a biblioteca Python requests usando a opção proxies:

import requests

# define the proxy settings

proxy = {

'http': 'http://username:[email protected]:8080',

'https': 'https://username:[email protected]:8080'

}

# Make a request using the proxy

response = requests.get('https://www.example.com', proxies=proxy)

Para um tutorial completo, siga nosso guia sobre usar um proxy com Python Requests.

Autenticação básica

Autenticação HTTP, mais conhecida como “autenticação básica”, é um esquema de autenticação simples incorporado ao protocolo HTTP. Envolve o envio de um nome de usuário e senha codificados no formato Base64 no cabeçalho Authorization.

Embora você possa implementá-lo configurando manualmente o cabeçalho Authorization, requests expõe uma opção auth dedicada para ele. Isso aceita uma tupla com o nome de usuário e a senha. Use-o para lidar com a autenticação básica na biblioteca Python requests:

import requests

# define the username and password for basic authentication

username = 'sample_username'

password = 'sample_password'

# send a GET request with basic authentication

response = requests.get('https://api.example.com/private/users', auth=(username, password))

Verificação de certificado SSL

A verificação do certificado SSL é crucial para garantir a comunicação segura entre clientes e servidores pela internet. Ao mesmo tempo, há situações em que você confia no servidor de destino e não precisa impor a verificação.

Em particular, ao rotear o tráfego HTTP por meio de servidores proxy, você pode encontrar erros relacionados aos certificados SSL. Nesse caso, talvez seja necessário desativar a verificação do certificado SSL. Em requests, isso é possível por meio da opção verify :

import requests

# send a GET request to a website with SSL certificate verification disabled

response = requests.get('https://api.example.com/data', verify=False)

Tempo limite

Por padrão, as solicitações aguardam automaticamente por tempo indefinido até que o servidor responda. Se o servidor estiver passando por uma sobrecarga ou houver uma lentidão na rede, esse comportamento pode se tornar um problema.

Para evitar a lentidão de seu aplicativo enquanto espera por uma resposta que talvez nunca chegue, requests tem uma opção de timeout . É possível estabelecer um número inteiro ou flutuante representando o número de segundos para esperar por uma resposta:

import requests

# timeout after 2 second

response1 = requests.get("https://api.example.com/data", timeout=2)

Como alternativa, timeout aceita uma tupla com dois elementos: tempo limite de conexão e tempo limite de leitura. Especifique-os como no exemplo abaixo:

import requests

# timeout after 2.5 seconds for connections and 4 seconds for reading response

response = requests.get("https://api.example.com/data", timeout=(2.5, 4))

Se a solicitação estabelecer uma conexão dentro do tempo limite de conexão especificado e receber dados dentro do tempo limite de leitura, a resposta será retornada normalmente. Caso contrário, se a solicitação expirar, uma exceção Timeout será gerada:

import requests

from requests.exceptions import Timeout

try:

response = requests.get("https://api.example.com/data", timeout=(2.5, 4))

except Timeout:

print("The request timed out")

Conclusão

Neste artigo, você se aprofundou na biblioteca requests, entendendo o que ela é, quais métodos ela tem, como usá-los e muito mais. Você aprendeu que o módulo Python requests é uma biblioteca HTTP útil e popular que abrange vários casos de uso.

O problema é que qualquer solicitação HTTP expõe seu IP público. Desse modo, fornece informações sobre quem você é e onde mora, o que não é bom para sua privacidade. Existem várias maneiras de ocultar seu endereço IP, e a maneira mais eficaz de obter maior segurança e privacidade é usar um servidor proxy.

A Bright Data controla os melhores servidores de proxy do mundo, atendendo a empresas listadas na Fortune 500 e a mais de 20.000 clientes. Sua oferta inclui uma grande variedade de tipos de proxy:

• Proxies de data centers — mais de 770.000 IPs de data centers.
• Proxies residenciais — mais de 72 milhões de IPs residenciais em mais de 195 países.
• Proxies de provedores de internet (ISP) — mais de 700.000 IPs de provedores.
• Proxies móveis — mais de 7 milhões de IPs móveis.