开发者指南

cURL PUT 请求与结果验证

使用 cURL PUT 发送 JSON 或上传文件,区分 POST 与 PATCH,通过 If-Match 进行条件更新,并核对响应与资源状态。

下载可运行的示例

用 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 定义。

条件 PUT 成功、旧 ETag 请求被拒绝及再次 GET 的过程。
第一次条件 PUT 更新 ETag。使用旧 ETag 再发请求返回 412,库存维持为 5。

向上传端点发送原始文件

本地服务器提供单独的原始文件上传地址:

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 表示服务器报告成功。请对照返回的资源数据,或再次读取确认实际保存的值。

继续使用 MIYAIP