用 curl 的 --request PUT 指定方法,并传入要替换资源的正文。原始文件上传可用 --upload-file,在 HTTP 下它默认选择 PUT,除非同时指定其他方法。实际字段、认证及响应取决于端点约定。
PUT 表达资源期望达到的状态,POST 由目标服务按接口约定处理,PATCH 应用指定的局部改动。使用哪种方法要以接收端接口为准。
本篇目录
使用对应媒体类型发送 JSON
按照 README 启动本地回环服务。附带的 lamp.json 包含完整的示例数据:
{"name":"Desk Lamp","stock":5,"currency":"USD"}将它发送到本地示例资源:
curl --noproxy '*' --include --request PUT \
--header 'Content-Type: application/json' \
--data-binary @lamp.json \
http://127.0.0.1:8812/api/items/lamp--data-binary 原样读取文件。需要明确传入正文,并声明 JSON 媒体类型。示例对错误的内容类型返回 415,缺少 name 或 stock 时返回 422。
成功时返回 HTTP 200 和保存后的数据。本地端点会替换旧对象,省略的字段也不会保留。生产更新前请确认实际 API 是否采用这种 PUT 约定。
防止基于旧版本更新资源
先读取当前资源及其 ETag:
curl --noproxy '*' --silent --show-error \
--dump-header get-headers.txt \
--output before.json \
http://127.0.0.1:8812/api/items/lamp将 get-headers.txt 内的 ETag 完整复制到 If-Match 标头,保留引号:
curl --noproxy '*' --include --request PUT \
--header 'Content-Type: application/json' \
--header 'If-Match: "ETAG_FROM_GET"' \
--data-binary @lamp.json \
http://127.0.0.1:8812/api/items/lamp用刚收到的值替换占位符。示例包的 put_demo.py 使用 curl 和最新 ETag 自动完成同样的步骤。
在初始状态下发送请求 | 结果 |
|---|---|
GET 读取资源 | 库存为 8,返回 ETag |
带当前 ETag 的 PUT 将库存改成 5 | HTTP 200,库存为 5,并返回新 ETag |
用原 ETag 重复 PUT | HTTP 412,未满足前置条件 |
失败后重新 GET | 库存仍为 5 |
如果别的请求已更新资源,重新读取后再决定如何合并改动。条件请求需要服务端支持并执行前置条件。规则见 RFC 9110 的 If-Match 定义。

向上传端点发送原始文件
本地服务器提供单独的原始文件上传地址:
curl --noproxy '*' --include \
--upload-file sample.txt \
http://127.0.0.1:8812/uploads/sample.txt
curl --noproxy '*' --silent --show-error \
http://127.0.0.1:8812/uploads/sample.txt首次上传会返回 201 Created,替换已有文件则返回 204 No Content。随后 GET 返回 Example upload 和换行。204 没有正文,客户端无需尝试读取 JSON。
此处直接发送文件内容,用 --form 时则发送 multipart 表单。接收端需要支持 PUT 上传。方法与上传选项见 curl HTTP 脚本指南。
根据响应决定是否重试
响应 | 处理方式 |
|---|---|
200 | 服务报告成功,核对返回的资源数据 |
201 | 已按端点约定创建资源 |
204 | 已成功,响应无正文 |
400 或 422 | 核对格式、必填字段和校验信息 |
401 或 403 | 检查目标服务的身份验证或访问权限 |
405 | 检查资源支持的 HTTP 方法 |
412 | 检查未满足的前置条件 |
415 | 检查接收端支持的媒体类型 |
默认情况下,curl 完成传输后可能以状态零退出,即使 HTTP 响应是错误。自动化流程可以使用 --fail-with-body,并记录实际 HTTP 状态与响应正文。
PUT 的预期效果是幂等的,重复提交同一份数据应得到相同的目标状态。时间戳、响应和其他服务行为可能有变化。超时后,第一个请求可能已到达服务端。决定是否重试前,先读回资源或使用接口提供的并发控制。
分别核对网络路由和写入约定
代理用于改变到达端点的网络路线。PUT 支持、应用授权和写入结果由服务端接口决定。代理连接字段见 MIYAIP 静态代理文档。
常见问题
PUT 可以只更新一个字段吗?
以 API 文档为准。只改部分字段时,检查端点是否支持 PATCH 及相应的正文格式,并确认遗漏其他字段会怎样处理。
-X PUT 会上传文件吗?
它只选定请求方法。可加 --data-binary @file.json 指定正文,或对原始文件上传端点使用 --upload-file。
HTTP 200 能确认保存的值与预期相符吗?
HTTP 200 表示服务器报告成功。请对照返回的资源数据,或再次读取确认实际保存的值。