Cách gửi JSON với cURL: Hướng dẫn đầy đủ về -d, --json và những sai lầm phổ biến

Những điểm chính:

• Gửi JSON bằng cURL là hai điều, không phải một. Bạn đính kèm một thân JSON vào yêu cầu và bạn thông báo cho máy chủ rằng đó là JSON thông qua tiêu đề Content-Type: application/json. Bỏ qua tiêu đề và nhiều API sẽ từ chối hoặc phân tích sai nội dung.
• -d/--data chứa tải; tiêu đề do bạn quyết định. Cách tiêu biểu là curl -X POST -H "Content-Type: application/json" -d '{...}' URL. -d không tự động thiết lập bất kỳ tiêu đề JSON nào.
• --json là lối tắt hiện đại. Được thêm vào curl 7.82.0, --json '{...}' gửi nội dung và thiết lập cả Content-Type: application/json và Accept: application/json chỉ với một cờ.
• Trích dẫn trong shell là nơi mà hầu hết mọi người gặp rắc rối. Bọc JSON trong dấu nháy đơn để shell không xử lý nhầm các dấu nháy kép bên trong; trên Windows cmd thì có những quy tắc khác và một tệp tải là an toàn hơn.
• @file đọc nội dung từ đĩa — nhưng hãy chọn đúng cờ cho dữ liệu. -d @body.json loại bỏ các dòng mới; --data-binary @body.json và --json @body.json gửi tệp byte-for-byte.
• Hình dạng cùng một yêu cầu thúc đẩy các API thực. Một cuộc gọi JSON-RPC tới điểm cuối Scrapeless MCP được lưu trữ chỉ là một POST với nội dung JSON và một tiêu đề xác thực — chính xác là mẫu hướng dẫn này dạy.
• Miễn phí để bắt đầu. Tài khoản Scrapeless mới bao gồm thời gian chạy Scraping Browser miễn phí và quyền truy cập proxy dân cư — đăng ký tại Scrapeless.

Giới thiệu: yêu cầu mà mọi tích hợp API bắt đầu với

Hầu hết mọi API web hiện đại đều sử dụng JSON. Bạn xác thực với một thân JSON, bạn gửi một công việc với một thân JSON, bạn gọi một công cụ trên một máy chủ MCP với một thân JSON. Trước bất kỳ điều gì đó chạy bên trong một script hoặc một SDK, nó thường bắt đầu cuộc sống như một lệnh curl đơn giản trong một terminal — cách nhanh nhất để xác nhận rằng một điểm cuối hoạt động theo những gì tài liệu tuyên bố.

Vấn đề là "gửi JSON bằng curl" ẩn chứa hai yêu cầu riêng biệt mà dễ bị nhầm lẫn. Một là đính kèm văn bản JSON như một thân yêu cầu. Cái kia là tuyên bố, thông qua tiêu đề Content-Type, rằng nội dung là JSON để máy chủ phân tích nó một cách chính xác thay vì coi đó là dữ liệu biểu mẫu. Làm đúng nội dung nhưng quên tiêu đề và một API nghiêm ngặt sẽ trả về mã 400 hoặc âm thầm không đọc gì cả. Trích dẫn JSON sai trong shell của bạn và curl gửi một chuỗi bị biến dạng mà chưa bao giờ là JSON hợp lệ ngay từ đầu.

Hướng dẫn này định nghĩa chính xác ý nghĩa của "gửi JSON bằng curl", hướng dẫn qua hai nhóm cờ thực hiện việc đó (-d cộng với một tiêu đề, và --json mới hơn), cho ví dụ hoạt động mà bạn có thể chạy chống lại một điểm cuối hồi âm công khai, và liệt kê các lỗi dẫn đến những thông báo lỗi gây nhầm lẫn. Nó kết thúc bằng cách ánh xạ cùng một hình dạng yêu cầu lên một cuộc gọi thực tới một API JSON — điểm cuối Scrapeless MCP được lưu trữ — vì vậy mẫu này mang thẳng từ terminal vào sản xuất. Để có nền tảng phụ trợ, hãy xem hướng dẫn của chúng tôi về cào HTTP bất đồng bộ với aiohttp và giải thích về proxy SSL là gì.

Ý nghĩa của "Gửi JSON Bằng cURL"

cURL (công cụ dòng lệnh xung quanh libcurl) chuyển dữ liệu qua HTTP và nhiều giao thức khác. "Gửi JSON bằng cURL" có nghĩa là phát hành một yêu cầu HTTP — hầu như luôn là một POST, PUT hoặc PATCH — có nội dung là một tài liệu JSON và tiêu đề Content-Type được thiết lập thành application/json.

Hai phần này là độc lập và cả hai đều quan trọng:

• Nội dung là văn bản JSON thô — chẳng hạn như {"product":"laptop","max_price":1200}. curl gửi những byte này một cách nguyên vẹn như là thực thể yêu cầu.
• Tiêu đề Content-Type thông báo cho máy chủ cách giải thích những byte đó. Nếu không có nó, mặc định của curl cho -d là application/x-www-form-urlencoded, định dạng được sử dụng cho các yêu cầu từ biểu mẫu HTML. Một API JSON thấy tiêu đề đó có thể từ chối yêu cầu hoặc cố gắng (và thất bại) để phân tích nội dung như các trường biểu mẫu.

Yêu cầu JSON đúng do đó luôn kết hợp một nội dung JSON với loại nội dung JSON. Câu hỏi duy nhất là các cờ curl nào bạn sử dụng để tạo ra sự kết hợp đó — và đó là sự khác biệt giữa cách tiếp cận cổ điển -d-cộng-tiêu đề và lối tắt cờ đơn --json được đề cập dưới đây.

Một lưu ý nhanh về thuật ngữ: -d là dạng ngắn của --data, và -H là dạng ngắn của --header. Chúng có thể hoán đổi cho nhau; hướng dẫn này sử dụng các dạng ngắn trong các ví dụ và nêu các dạng dài ở nơi có ích.

Phương pháp 1: -d / --data Với Tiêu Đề Content-Type

Đây là phương pháp di động, hoạt động ở mọi nơi và là phương pháp mà bạn sẽ thấy nhiều nhất trong tài liệu API. Bạn cung cấp nội dung với -d và tiêu đề với -H:

curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"product":"laptop","max_price":1200}'

Có ba điều đang xảy ra:

• -X POST thiết lập phương thức HTTP. Một cách nghiêm ngặt, -d đã ngụ ý POST, vì vậy -X POST là tùy chọn ở đây - nhưng việc nêu rõ điều này làm cho ý định trở nên rõ ràng và là điều cần thiết nếu bạn bao giờ thay đổi cờ body theo cách mà nếu không thì nó sẽ mặc định là GET.
• -H "Content-Type: application/json" khai báo định dạng body.
• -d '{...}' đính kèm JSON. Dấu nháy đơn giữ cho shell không giải thích dấu nháy kép bên trong JSON.

Chạy lệnh này trên httpbin.org/post - một điểm cuối công khai mà sẽ phản hồi lại bất cứ điều gì nó nhận được - trả về:

{
  "data": "{\"product\":\"laptop\",\"max_price\":1200}",
  "headers": {
    "Accept": "*/*",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.18.0"
  },
  "json": {
    "max_price": 1200,
    "product": "laptop"
  },
  "origin": "203.0.113.10",
  "url": "https://httpbin.org/post"
}
// Các giá trị trường là mẫu minh họa; cấu trúc là những gì httpbin trả về.

Dấu hiệu chính cho sự thành công là đối tượng json: httpbin chỉ populate nó khi body được phân tích như là JSON hợp lệ và Content-Type là application/json. Header Accept là */* - giá trị mặc định của curl - vì -d không chạm vào Accept. Lưu ý rằng, riêng biệt, -d không thiết lập header JSON nào: Content-Type ở trên chỉ có mặt vì bạn đã thêm dòng -H. Nếu bỏ dòng đó, httpbin sẽ báo cáo Content-Type: application/x-www-form-urlencoded và một trường json rỗng.

Phương thức 2: Cờ --json (curl 7.82.0+)

Cờ --json được giới thiệu trong curl 7.82.0 (ra mắt đầu năm 2022) để làm đơn giản hóa trường hợp phổ biến thành một tùy chọn. Kiểm tra phiên bản của bạn bằng curl --version; nếu nó báo cáo 7.82.0 hoặc mới hơn, --json có sẵn.

curl -X POST https://httpbin.org/post \
  --json '{"product":"laptop","max_price":1200}'

Một --json đơn lẻ thực hiện ba công việc cùng một lúc. Nó gửi văn bản được cung cấp như là body yêu cầu, và nó thiết lập cả hai header này cho bạn:

• Content-Type: application/json
• Accept: application/json

Header thứ hai là sự khác biệt thực tế với Phương thức 1: --json cũng thông báo cho máy chủ rằng bạn muốn nhận JSON, mà một số API sử dụng để chọn định dạng phản hồi của họ. Việc phản hồi yêu cầu qua httpbin xác nhận điều này:

{
  "data": "{\"product\":\"laptop\",\"max_price\":1200}",
  "headers": {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.18.0"
  },
  "json": {
    "max_price": 1200,
    "product": "laptop"
  },
  "origin": "203.0.113.10",
  "url": "https://httpbin.org/post"
}
// Lưu ý cả Accept và Content-Type giờ đều là application/json.

Bạn có thể sử dụng --json nhiều lần và curl sẽ nối các đoạn lại thành một body - tiện lợi cho việc lắp ráp payload từ nhiều phần. Nếu bạn cần ghi đè một trong các header mà --json thiết lập (ví dụ, một Accept khác), hãy thêm một -H rõ ràng sau đó; header sau sẽ thắng.

Khi nào bạn nên sử dụng mỗi phương thức? Sử dụng --json cho công việc mới trên một curl hiện tại. Sử dụng -d cộng với -H khi bạn phải hỗ trợ các phiên bản curl cũ hơn, khi bạn muốn kiểm soát hoàn toàn các header hiện có, hoặc khi tài liệu bạn đang theo dõi được viết theo cách đó.

Nhận khóa API của bạn trên gói miễn phí: Scrapeless

Gửi một tệp JSON Với @

JSON trực tuyến trở nên cồng kềnh sau một vài trường, và các payload lớn thuộc về một tệp. Cả -d và --json đều chấp nhận tiền tố @ để đọc body từ một đường dẫn. Giả sử một body.json như sau:

{
  "product": "laptop",
  "max_price": 1200
}

Bạn có thể gửi nó bằng một trong hai cờ:

# Cổ điển: cờ dữ liệu + header rõ ràng
curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d @body.json

# Hiện đại: một cờ
curl -X POST https://httpbin.org/post \
  --json @body.json

Có một điểm khác biệt tinh tế nhưng quan trọng trong cách tệp được đọc. -d @body.json xóa bỏ các dòng mới và ký tự xuống dòng từ tệp trước khi gửi - một đặc điểm từ việc -d được thiết kế cho dữ liệu biểu mẫu. Body mà đến máy chủ trở thành { "product": "laptop", "max_price": 1200}: vẫn là JSON hợp lệ (trắng giữa các ký hiệu là hợp lệ), nhưng không còn byte-for-byte giống như trên đĩa.

Hai cờ bảo tồn tệp chính xác:

# --data-binary giữ mọi byte, bao gồm cả dòng mới
curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  --data-binary @body.json

# --json @file cũng gửi tệp một cách nguyên vẹn

curl -X POST https://httpbin.org/post \
  --json @body.json

Đối với JSON thông thường, phiên bản xóa ký tự xuống dòng vẫn có thể phân tích, vì vậy -d @file thường hoạt động. Nhưng nếu payload phải khớp từng byte với file — một chữ ký được tính toán trên các byte chính xác, hoặc file chứa một giá trị chuỗi với các ký tự xuống dòng nhúng có ý nghĩa — hãy sử dụng --data-binary @file hoặc --json @file.

Bạn cũng có thể ống dẫn một body từ stdin bằng cách sử dụng @-, điều này tiện lợi khi một chương trình khác tạo ra JSON:

generate_payload | curl -X POST https://httpbin.org/post --json @-

Các Sai Lầm Thường Gặp (và Cách Tránh Chúng)

Những sai lầm này biến một cú curl năm giây thành một phiên gỡ lỗi.

1. Quên tiêu đề Content-Type

Đây là sai lầm phổ biến nhất. Với -d thông thường và không có tiêu đề, curl gửi Content-Type: application/x-www-form-urlencoded. Một API JSON sẽ từ chối yêu cầu với mã 4xx hoặc đọc một body trống. Sửa: thêm -H "Content-Type: application/json", hoặc chuyển sang --json, cái sẽ thiết lập cho bạn.

2. Trích dẫn shell phá vỡ JSON

JSON sử dụng dấu ngoặc kép; hầu hết các shell cũng sử dụng dấu ngoặc kép cho việc nội suy. Bọc một payload trong dấu ngoặc kép cho phép shell loại bỏ hoặc mở rộng các phần của nó trước khi curl nhìn thấy:

# SAI trên bash/zsh: shell tiêu thụ các dấu ngoặc kép bên trong
curl -X POST https://httpbin.org/post --json "{"product":"laptop"}"

# ĐÚNG: dùng dấu ngoặc đơn cho toàn bộ payload
curl -X POST https://httpbin.org/post --json '{"product":"laptop"}'

Sửa: bọc toàn bộ tài liệu JSON trong dấu ngoặc đơn trên bash/zsh. Nếu một giá trị tự nó phải chứa một dấu ngoặc đơn, hãy thoát nó hoặc chuyển payload vào một file và sử dụng @file — điều này sẽ tránh hoàn toàn việc trích dẫn shell.

3. Việc trích dẫn cmd của Windows khác

Windows cmd.exe không coi dấu ngoặc đơn là ký tự trích dẫn, vì vậy mẹo với dấu ngoặc đơn không hoạt động ở đó. Bạn phải thoát từng dấu ngoặc kép bên trong bằng dấu gạch chéo ngược, hoặc — đáng tin cậy hơn rất nhiều — đưa JSON vào một file và gửi @body.json. PowerShell có quy tắc trích dẫn riêng và alias curl của nó từ trước đã chỉ đến Invoke-WebRequest; hãy gọi rõ ràng curl.exe và ưa thích hình thức @file để tránh bất ngờ. Sửa: trên Windows, hãy sử dụng một file payload với @body.json.

4. Để -G biến body của bạn thành một chuỗi truy vấn

-G/--get cho curl biết để thêm dữ liệu -d vào URL dưới dạng các tham số truy vấn thay vì gửi một body. Đây là công cụ đúng cho các yêu cầu GET, nhưng nếu bạn giữ nó trong khi cố gắng POST JSON, payload của bạn sẽ âm thầm chuyển vào URL và body sẽ trống. Sửa: không kết hợp -G với một body JSON; sử dụng -X POST (hoặc để -d/--json mặc định là POST).

5. Gửi JSON không hợp lệ

curl không xác thực body — nó gửi bất kỳ văn bản nào bạn cung cấp. Một dấu phẩy đuôi, một khóa không có dấu ngoặc kép, hoặc một chuỗi có dấu ngoặc đơn là điều mà máy chủ sẽ từ chối, thường với một lỗi phân tích mờ. Sửa: xác thực payload trước khi gửi. Một bài kiểm tra nhanh tại chỗ với một trình phân tích JSON sẽ bắt hầu hết chúng:

# Gặp lỗi nhanh trên JSON lỗi trước khi curl chạy
echo '{"product":"laptop","max_price":1200}' | python -c "import sys, json; json.load(sys.stdin); print('valid')"

6. Quên Accept khi API áp dụng thương lượng nội dung

Một số API trả về XML hoặc HTML trừ khi bạn yêu cầu JSON. Với -d, bạn chỉ thiết lập Content-Type, không phải Accept, vì vậy phản hồi có thể không phải là JSON ngay cả khi yêu cầu của bạn là. Sửa: thêm -H "Accept: application/json", hoặc sử dụng --json, cái sẽ thiết lập Accept cho bạn.

Ví Dụ Thực Tế: Gọi một API JSON

Tổng hợp lại, đây là hình dạng của một cuộc gọi API JSON thực tế. Điểm cuối Scrapeless MCP được lưu trữ nói chuyện JSON-RPC qua HTTP — có nghĩa là nó chính xác là yêu cầu bạn đã xây dựng: một POST với một body JSON và một tiêu đề xác thực. Đọc khóa API từ một biến môi trường để nó không bao giờ xuất hiện trong lịch sử shell của bạn:

# Body sống trong init.json; khóa đến từ môi trường, không phải dòng lệnh
curl -X POST "https://api.scrapeless.com/mcp" \
  -H "x-api-token: ${SCRAPELESS_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data-binary @init.json

với init.json giữ tay bắt tay JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "curl-demo", "version": "1.0" }
  }
}

Mỗi khái niệm từ hướng dẫn này đều có mặt: một body JSON (ở đây từ một file, gửi nguyên văn với --data-binary), header Content-Type: application/json đánh dấu nó là JSON, một header Accept liệt kê các định dạng bạn sẽ chấp nhận trả lại, và một header xác thực mang theo thông tin xác thực. Điểm cuối được lưu trữ cung cấp khoảng hai chục công cụ - google_search, scrape_html, scrape_markdown, bộ tự động hóa browser_*, và nhiều hơn nữa - mỗi công cụ được gọi với cùng một mẫu POST-a-JSON-body, chỉ có method và params là thay đổi. Các chi tiết thiết lập sống trong tài liệu Scrapeless.

Bạn không cần phải tiếp tục nói chuyện với điểm cuối bằng curl thô, tất nhiên - nhưng việc chứng minh một điểm cuối bằng curl trước, sau đó chuyển đổi yêu cầu đã được xác minh vào ngôn ngữ bạn chọn, là quy trình tiết kiệm nhiều thời gian nhất. Để xem toàn bộ danh mục công cụ của máy chủ MCP và các prompt tác nhân đã hoạt động, hãy xem 5 Trường hợp sử dụng Scrapeless MCP.

Cách Scrapeless Hoạt Động

Khi một lệnh curl hoạt động, bước tiếp theo thường là thực hiện ở quy mô lớn - nhiều yêu cầu, chống lại các trang web render nội dung bằng JavaScript hoặc lưu lượng tự động hóa màn hình. Đó là nơi hình dạng yêu cầu mà bạn vừa học gặp cơ sở hạ tầng được quản lý.

Scrapeless cung cấp một trình duyệt đám mây chống phát hiện - Scrapeless Scraping Browser - và proxy dân cư tại hơn 195 quốc gia, có thể truy cập thông qua điểm cuối MCP được lưu trữ, một SDK, và một CLI. Trình duyệt render các trang tải nặng JavaScript trên phía đám mây và quản lý dấu vân tay, vì vậy yêu cầu JSON sạch mà bạn đã tạo mẫu trong curl sẽ trả về dữ liệu có cấu trúc thay vì một trang thử thách. Chi tiết vận chuyển - ghim một đầu ra dân cư, giữ một phiên - được xử lý cho bạn; phía của bạn vẫn là vòng lặp "POST một body JSON, đọc JSON trở lại" đơn giản.

Khám phá sản phẩm Trình duyệt Scraping, xem xét các gói trên trang báo giá, và tìm tài liệu API và MCP trong tài liệu.

Kết Luận

Gửi JSON với curl phụ thuộc vào hai yêu cầu được thực hiện cùng nhau: đính kèm JSON như body yêu cầu, và tuyên bố nó là JSON bằng header Content-Type. Cách cổ điển là -d '{...}' cộng với -H "Content-Type: application/json"; cách hiện đại một cờ là --json '{...}', điều này thiết lập cả Content-Type và Accept cho bạn trên curl 7.82.0 và mới hơn. Di chuyển các payload lớn hoặc đã ký vào một file và gửi chúng với --data-binary @file hoặc --json @file để bảo tồn mọi byte, dùng dấu nháy đơn cho JSON nội tuyến trên bash để chống lại việc trích dẫn shell, và tìm một file payload trên Windows. Cùng một yêu cầu - body cộng với loại nội dung cộng với một header xác thực - chính là những gì việc gọi một API JSON thực sự như điểm cuối Scrapeless MCP trông như thế nào, đó là lý do tại sao một curl hoạt động trong terminal của bạn chuyển đổi một cách sạch sẽ vào sản xuất. Để đọc thêm liên quan, xem scraping HTTP bất đồng bộ với aiohttp và proxy SSL là gì.

Câu Hỏi Thường Gặp

Q: Cách đơn giản nhất để gửi JSON với curl là gì?

Trên một curl hiện tại (7.82.0 hoặc mới hơn), curl --json '{"key":"value"}' URL là dạng ngắn gọn nhất đúng - nó gửi body và thiết lập cả header Content-Type và Accept thành application/json. Trên curl cũ hơn, sử dụng curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL.

Q: Tại sao API JSON của tôi nói rằng body bị thiếu hoặc không hợp lệ mặc dù tôi đã gửi nó?

Hai nguyên nhân thường gặp. Hoặc bạn đã gửi -d mà không có header Content-Type: application/json, vì vậy máy chủ đã đọc nó như dữ liệu biểu mẫu - thêm header hoặc sử dụng --json. Hoặc shell của bạn đã làm hỏng JSON vì nó được bọc trong dấu ngoặc kép; dùng dấu nháy đơn cho payload, hoặc di chuyển nó vào một file và gửi @file.

Q: Sự khác biệt giữa -d, --data-binary, và --json là gì?

-d (--data) gửi body và, đối với @file, xóa các ký tự xuống dòng; nó không thiết lập bất kỳ header JSON nào một mình. --data-binary gửi body chính xác như đã cho, bao gồm cả các ký tự xuống dòng. --json gửi body nguyên văn và thiết lập Content-Type và Accept thành application/json; nó yêu cầu curl 7.82.0+.

Q: Làm thế nào để gửi một file JSON thay vì văn bản nội tuyến?

Tiền tố đường dẫn bằng @: curl --json @body.json URL, hoặc curl -H "Content-Type: application/json" --data-binary @body.json URL. Ưu tiên --json @file hoặc --data-binary @file hơn -d @file khi các byte phải khớp với file chính xác, vì -d @file xóa bỏ các ký tự xuống dòng.

Q: Làm thế nào để gửi JSON với curl trên Windows?

cmd.exe không tôn trọng dấu nháy đơn, vì vậy con đường đáng tin cậy nhất là đưa JSON vào một file và gửi với @body.json. Nếu bạn cần phải inline, hãy thoát mỗi dấu ngoặc kép bên trong bằng một dấu gạch chéo ngược. Trong PowerShell, gọi curl.exe một cách rõ ràng để bạn không chạm phải bí danh Invoke-WebRequest, và vẫn ưu tiên hình thức @file.
H: Tôi có cần đặt tiêu đề Content-Type nếu tôi sử dụng --json không?

Không. --json tự động đặt Content-Type: application/json, cùng với Accept: application/json. Bạn chỉ cần thêm một tiêu đề rõ ràng để ghi đè một trong hai tiêu đề đó — ví dụ như một Accept khác — trong trường hợp đó, hãy đặt -H sau --json để nó có hiệu lực ưu tiên.

Sẵn Sàng Xây Dựng Quy Trình Dữ Liệu Được Hỗ Trợ Bởi AI?

Tham gia cộng đồng của chúng tôi để nhận một gói miễn phí và kết nối với các nhà phát triển đang xây dựng các quy trình thu thập dữ liệu dựa trên JSON: Discord · Telegram.

Đăng ký tại Scrapeless để có quyền truy cập miễn phí vào môi trường trình duyệt Scraping và proxy dân cư, và biến yêu cầu curl mà bạn đã phát triển thành một quy trình dữ liệu sản xuất.