⭐ Python Developer · Chặng 7Bài 2/6Bài học~60 phút

Gọi Web API bằng requests: GET, POST, JSON, timeout, thử lại

Lấy dữ liệu từ Web API bằng requests: GET, POST, params, header, JSON, timeout, raise_for_status, Session, thử lại và giữ API key.

Gọi Web API bằng requests: GET, POST, JSON, timeout, thử lại

Học xong bài này, bạn sẽ

  • Hiểu request, response, mã trạng thái, JSON
  • Gửi GET, POST có tham số, header, timeout
  • Xử lý lỗi mạng, thử lại và giữ bí mật API key

Nên học trước: Công cụ dòng lệnh với argparse và Typer

Nội dung bài viết
  1. 1. Request và response
  2. 2. GET đầu tiên
  3. 3. Kiểm tra lỗi
  4. 4. POST, header và JSON body
  5. 5. API key và bí mật
  6. 6. Session, thử lại và giới hạn tần suất
  7. Tóm tắt
  8. Bài tập

Tỷ giá, thời tiết, đơn hàng trên sàn thương mại điện tử, tin nhắn Telegram, dữ liệu từ hệ thống nội bộ của công ty: gần như mọi dữ liệu ngày nay đều lấy được qua Web API. Gọi API là kỹ năng hằng ngày của Python Developer, dù bạn làm tự động hóa hay backend. Bài này dùng thư viện requests, cách gọi HTTP phổ biến nhất trong Python, với các API công khai miễn phí không cần đăng ký.

1. Request và response

Chương trình của bạn gửi một request (yêu cầu) tới máy chủ gồm: phương thức (GET để lấy dữ liệu, POST để gửi dữ liệu...), URL, header và có thể có body. Máy chủ trả về response: mã trạng thái, header và body, thường là JSON. Chặng 9 sẽ đi sâu vào HTTP khi bạn tự viết API; ở đây chỉ cần biết các mã trạng thái chính:

MãÝ nghĩa
200, 201Thành công, đã tạo mới
400, 422Request sai (thiếu tham số, dữ liệu không hợp lệ)
401, 403Chưa đăng nhập, không có quyền
404Không tìm thấy
429Gọi quá nhiều, bị giới hạn tần suất
500, 502, 503Lỗi phía máy chủ

2. GET đầu tiên

Cài: uv add requests. Lấy dự báo nhiệt độ Hà Nội từ Open-Meteo (miễn phí cho mục đích phi thương mại, không cần key):

import requests

URL = "https://api.open-meteo.com/v1/forecast"
tham_so = {
    "latitude": 21.03,
    "longitude": 105.85,
    "daily": "temperature_2m_max,temperature_2m_min",
    "timezone": "Asia/Ho_Chi_Minh",
    "forecast_days": 3,
}
r = requests.get(URL, params=tham_so, timeout=10)    # kết quả thay đổi theo ngày
print(r.status_code, r.headers["Content-Type"])
du_lieu = r.json()                                   # JSON → dict
ngay = du_lieu["daily"]
for d, cao, thap in zip(ngay["time"], ngay["temperature_2m_max"], ngay["temperature_2m_min"]):
    print(f"{d}: {thap:.0f}–{cao:.0f}°C")
200 application/json; charset=utf-8
2026-10-29: 24–31°C
2026-10-30: 24–30°C
2026-10-31: 25–30°C
  • params= nhận dict và tự ghép thành chuỗi truy vấn ?latitude=21.03&..., tự mã hóa ký tự đặc biệt. Đừng tự nối chuỗi URL.
  • r.json() chuyển body JSON thành dict, list. r.text là body dạng chuỗi.
  • timeout=10 là bắt buộc. Mặc định requests chờ vô hạn; máy chủ treo là chương trình của bạn treo theo.

Mẹo khi làm việc với API lạ: in du_lieu ra (hoặc mở URL trong trình duyệt) để xem cấu trúc JSON trước, rồi mới viết code lấy trường cần dùng.

3. Kiểm tra lỗi

import requests

r = requests.get("https://api.open-meteo.com/v1/forecast", params={"latitude": 999, "longitude": 105.85}, timeout=10)
print(r.status_code, r.json())
try:
    r.raise_for_status()                 # ném HTTPError nếu mã 4xx, 5xx
except requests.HTTPError as loi:
    print("Lỗi:", loi)
400 {'error': True, 'reason': 'Latitude must be in range of -90 to 90°. Given: 999.0.'}
Lỗi: 400 Client Error: Bad Request for url: https://api.open-meteo.com/v1/forecast?latitude=999&longitude=105.85

requests không tự ném lỗi khi máy chủ trả 4xx, 5xx: r.json() vẫn chạy và bạn có thể vô tình xử lý một thông báo lỗi như dữ liệu thật. Luôn gọi r.raise_for_status() (hoặc kiểm tra r.ok) trước khi dùng dữ liệu. Nhiều API giải thích lỗi trong body như ví dụ trên: hãy ghi nó vào log.

Ngoài lỗi HTTP còn có lỗi mạng: mất kết nối (requests.ConnectionError), hết thời gian chờ (requests.Timeout). Mọi lỗi của requests đều kế thừa requests.RequestException.

4. POST, header và JSON body

httpbin.org là dịch vụ trả lại đúng những gì bạn gửi, tiện để thử:

import requests

don_hang = {"khach": "An", "mat_hang": [{"ma": "SP1", "so_luong": 2}]}
r = requests.post(
    "https://httpbin.org/post",
    json=don_hang,                                   # tự chuyển dict → JSON, đặt Content-Type
    headers={"User-Agent": "hoc-python/1.0", "X-Ma-Yeu-Cau": "abc123"},
    timeout=10,
)
r.raise_for_status()
nhan = r.json()
print(nhan["json"] == don_hang, nhan["headers"]["Content-Type"], nhan["headers"]["X-Ma-Yeu-Cau"])
True application/json abc123

json= dùng khi API nhận JSON (đa số API hiện đại); data= dùng cho form truyền thống. Header là cặp khóa – giá trị đi kèm request: loại nội dung, ngôn ngữ, và quan trọng nhất là thông tin xác thực.

5. API key và bí mật

Đa số API thật yêu cầu key, thường gửi qua header:

# (minh họa) đọc key từ biến môi trường, không viết thẳng vào code
import os

import requests

api_key = os.environ["TEN_DICH_VU_API_KEY"]            # thiếu thì KeyError ngay: dễ phát hiện
r = requests.get("https://api.vi-du.vn/v1/don-hang",
                 headers={"Authorization": f"Bearer {api_key}"}, timeout=10)

Đặt key trong file .env (đã có trong .gitignore) và nạp vào biến môi trường, hoặc dùng thư viện python-dotenv. Không bao giờ viết key trong code, không in key ra log.

6. Session, thử lại và giới hạn tần suất

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry


def tao_session() -> requests.Session:
    s = requests.Session()
    thu_lai = Retry(
        total=3,                                # tối đa 3 lần thử lại
        backoff_factor=0.5,                     # chờ tăng dần giữa các lần
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["GET"],                # chỉ tự thử lại request an toàn
    )
    s.mount("https://", HTTPAdapter(max_retries=thu_lai))
    s.headers["User-Agent"] = "hoc-python/1.0"
    return s


with tao_session() as s:                        # kết quả thay đổi theo ngày
    for tp, (lat, lon) in {"Hà Nội": (21.03, 105.85), "TP.HCM": (10.82, 106.63)}.items():
        r = s.get("https://api.open-meteo.com/v1/forecast",
                  params={"latitude": lat, "longitude": lon, "current": "temperature_2m"}, timeout=10)
        r.raise_for_status()
        print(tp, r.json()["current"]["temperature_2m"], "°C")
Hà Nội 27.4 °C
TP.HCM 29.8 °C
  • Session giữ kết nối TCP để dùng lại giữa các request (nhanh hơn nhiều khi gọi liên tục tới cùng máy chủ), và giữ header, cookie chung.
  • Retry tự thử lại khi gặp lỗi tạm thời, chờ tăng dần (0,5 s, 1 s, 2 s...) để không dội thêm tải vào máy chủ đang quá tải. Chỉ tự thử lại GET; POST tạo đơn hàng mà thử lại có thể tạo đơn trùng.
  • Tôn trọng giới hạn tần suất của API (thường ghi trong tài liệu): thêm time.sleep() giữa các lần gọi khi duyệt nhiều trang.
httpx: lựa chọn hiện đạiThư viện httpx có giao diện gần như giống hệt requests (httpx.get(url, params=..., timeout=...)) và hỗ trợ thêm gọi bất đồng bộ với async/await, HTTP/2. Bạn sẽ dùng httpx ở bài asyncio (chặng 10) và trong test FastAPI (chặng 9).

Tóm tắt

  • requests.get(url, params=..., timeout=...), requests.post(url, json=..., headers=...).
  • Luôn có timeout; luôn raise_for_status() trước khi dùng r.json().
  • Bắt requests.RequestException cho lỗi mạng; key đọc từ biến môi trường.
  • Session + Retry cho gọi nhiều lần, thử lại lỗi tạm thời (chỉ với GET).

Bài tập

Bài 1. Dự báo 7 ngày

Gọi Open-Meteo lấy nhiệt độ cao nhất, thấp nhất và tổng lượng mưa (precipitation_sum) 7 ngày tới ở Hà Nội, in bảng ngày (dd/mm) – thấp – cao – mưa.

Xem đáp án
from datetime import date

import requests

r = requests.get(
    "https://api.open-meteo.com/v1/forecast",
    params={"latitude": 21.03, "longitude": 105.85, "timezone": "Asia/Ho_Chi_Minh",
            "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum", "forecast_days": 7},
    timeout=10,
)
r.raise_for_status()
d = r.json()["daily"]
print(f"{'Ngày':<7}{'Thấp':>6}{'Cao':>6}{'Mưa':>8}")
for ngay, thap, cao, mua in zip(d["time"], d["temperature_2m_min"], d["temperature_2m_max"],
                                d["precipitation_sum"]):
    print(f"{date.fromisoformat(ngay):%d/%m}{thap:>7.0f}{cao:>6.0f}{mua:>6.1f}mm")   # kết quả thay đổi theo ngày
Ngày     Thấp   Cao     Mưa
29/10     24    31   0.0mm
30/10     24    30   1.2mm
...

Bài 2. Hàm lấy JSON chịu lỗi

Viết lay_json(url, params=None, so_lan_thu=3): có timeout, thử lại khi lỗi mạng hoặc mã 5xx (chờ 1 s, 2 s...), không thử lại với 4xx, hết lượt thì ném lỗi cuối.

Xem đáp án
import time

import requests


def lay_json(url: str, params: dict | None = None, so_lan_thu: int = 3, cho: float = 1.0):
    for lan in range(1, so_lan_thu + 1):
        try:
            r = requests.get(url, params=params, timeout=10)
            if r.status_code < 500:
                r.raise_for_status()           # 4xx: lỗi của mình, ném ngay
                return r.json()
            loi = requests.HTTPError(f"{r.status_code} từ máy chủ")
        except (requests.ConnectionError, requests.Timeout) as e:
            loi = e
        if lan == so_lan_thu:
            raise loi
        time.sleep(cho * 2 ** (lan - 1))       # 1 s, 2 s, 4 s...


print(lay_json("https://httpbin.org/json")["slideshow"]["title"])
try:
    lay_json("https://httpbin.org/status/503", so_lan_thu=2, cho=0.1)
except requests.HTTPError as e:
    print("Bỏ cuộc:", e)
Sample Slide Show
Bỏ cuộc: 503 từ máy chủ

Đây chính là decorator thu_lai ở chặng 5 được viết thẳng vào hàm. Trong dự án thật, dùng Session + Retry như mục 6 hoặc thư viện chuyên dụng như tenacity thay vì tự viết.

Nguồn tham khảo: Requests: Quickstart; Requests: Advanced Usage; Open-Meteo API docs; urllib3 Retry.

Bài tập thực hành

  1. Gọi API thời tiết Open-Meteo lấy nhiệt độ 7 ngày tới ở Hà Nội, in bảng ngày – cao nhất – thấp nhất.
  2. Viết hàm lay_json(url, so_lan_thu=3) có timeout, thử lại khi lỗi 5xx hoặc mất kết nối.

Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.