請求 Body

在許多 API 中——特別是那些建立或更新資料的 API——請求中最重要的部分是請求 Body。與查詢或路徑參數（位於 URL 中）不同，請求 Body 是您發送結構化資料的地方，通常為 JSON 格式。

在這篇文章中，我們將解釋什麼是請求 Body、何時使用它，以及如何閱讀 API 文件中的 Body 規格。我們將使用 Pet Store API 進行演示。

1. 什麼是請求 Body？

請求 Body 是您在 HTTP 請求內部發送的資料，通常用於：

POST (建立新資源)

PUT (取代資源)

PATCH (更新部分資源)

大多數 GET 請求不包含 Body。

請求 Body 通常格式化為 JSON，但有些 API 也支援：

XML

Form data (multipart/form-data 用於檔案)

URL-encoded form fields

但 JSON 是現代標準。

與查詢參數或 Header 不同，Body 可以容納複雜的結構化資料，例如巢狀物件、陣列、檔案或二進位內容。

1. 資料結構 (Schema)：您應該發送什麼形狀的資料？

在編寫請求 Body 之前，您必須了解描述預期結構的 資料結構 (Schema)。

讓我們使用 建立寵物 端點：

POST /pets

文件顯示了 Pet 物件的資料結構：

資料結構告訴您：

存在哪些欄位 (id, name, category 等)

類型 (數字 (number), 字串 (string), 陣列 (array), 物件 (object))

巢狀結構 (category 和 tags 是物件/物件陣列)

允許值 (例如 status 可能是 "available" | "pending" | "sold")

您發送的每個請求 Body 必須遵循此形狀。

2. JSON Body — 最常見的格式

大多數現代 REST API 期望 JSON。
使用上述資料結構，這是一個用於 POST /pets 的有效 JSON 請求 Body：

{
  "name": "Lucky",
  "species": "DOG",
  "breed": "Golden Retriever",
  "ageMonths": 24,
  "size": "LARGE",
  "color": "Golden",
  "gender": "MALE",
  "goodWithKids": true,
  "goodWithPets": true,
  "adoptionFee": 150.00,
  "description": "Friendly golden retriever looking for an active family",
  "status": "AVAILABLE"
}

在 Apidog 中，當您需要根據 Body 資料結構建立請求 Body 時，您可以使用 Apidog 的 Auto-generate 功能來生成符合資料結構的 Body。

何時使用 JSON？

建立或更新物件

發送結構化資料 (物件, 陣列)

大多數 API 用戶端和伺服器自動支援它

當發送 JSON 作為 Body 時，Content-Type Header 應設定為 application/json；但是，大多數工具會自動處理此問題，因此您通常無需擔心。

3. XML Body — 較不常見但仍在某些 API 中使用

一些較舊的 API（或企業 API）支援 XML。
使用相同的資料結構，Body 也可以寫成 XML：

<Pet>
  <id>123</id>
  <name>Lucky</name>
  <category>
    <id>1</id>
    <name>Dog</name>
  </category>
  <photoUrls>
    <photoUrl>https://example.com/dog.jpg</photoUrl>
  </photoUrls>
  <tags>
    <tag>
      <id>10</id>
      <name>friendly</name>
    </tag>
  </tags>
  <status>available</status>
</Pet>

如果您發送 XML，您需要設定 Content-Type: application/xml Header。

4. multipart/form-data — 用於檔案上傳或混合欄位

某些端點接受檔案，例如圖片。
在這些情況下，JSON 是不夠的 — 您必須使用 multipart/form-data。

讓我們使用 上傳寵物圖片 端點作為範例：

POST /pets/{id}/images

文件告訴您 Body 包含：

欄位	類型	描述
file	binary (二進位)	要上傳的圖片
additionalMetadata	string (字串)	(可選) 額外資訊

您可以點擊 file 欄位中的 "Upload" 來上傳二進位檔案。

何時使用 multipart/form-data？

上傳圖片、PDF、影片

混合內容：文字 + 檔案

基於瀏覽器的表單提交

5. 重點摘要

這裡有關於請求 Body 您應該記住的事情：

資料結構 (Schema) 告訴您 Body 必須遵循什麼形狀和欄位

JSON 是最常見的請求 Body 格式

XML 在某些 API 中仍然受支援

multipart/form-data 用於檔案上傳是必需的

始終匹配正確的 Content-Type

這告訴伺服器如何解釋您的 Body。

現在您了解了什麼是請求 Body、資料結構如何定義其結構，以及如何使用 JSON、XML 和 multipart/form-data 等不同格式，您準備好邁出下一步：學習如何閱讀和解釋伺服器發送回來的回應。

1. 什麼是請求 Body？#

1. 資料結構 (Schema)：您應該發送什麼形狀的資料？#

2. JSON Body — 最常見的格式#

何時使用 JSON？#

3. XML Body — 較不常見但仍在某些 API 中使用#

4. multipart/form-data — 用於檔案上傳或混合欄位#

何時使用 multipart/form-data？#

5. 重點摘要#