跳到主要内容

Request():put()

执行 PUT 请求并返回一个 Response 对象。此方法用于完全替换服务器上的资源。

签名​

put(): Response

返回值

Response - 包含服务器响应的响应对象

描述​

put() 方法向创建 Request 对象时指定的 URL 发送 HTTP PUT 请求。PUT 请求通常用于用新数据完全替换现有资源，或者在特定 URL 上创建资源。

在调用 put() 之前，请使用 setParameter() 向请求体添加数据。

示例​

基本 PUT 请求​

-- 替换用户的完整数据
local response = Request("https://api.example.com/users/123")
    :setParameter("name", "John Smith")
    :setParameter("email", "john.smith@example.com")
    :setParameter("age", "35")
    :setParameter("status", "active")
    :put()

带 JSON 请求头的 PUT 请求​

-- 用新内容替换整篇文章
local response = Request("https://api.example.com/posts/456")
    :setHeader("Content-Type", "application/json")
    :setHeader("Authorization", "Bearer your-token-here")
    :setParameter("title", "Completely New Title")
    :setParameter("body", "Completely new post content")
    :setParameter("userId", "1")
    :setParameter("status", "published")
    :put()

处理 PUT 响应​

-- 更新用户资料并处理响应
local response = Request("https://api.example.com/users/789")
    :setHeader("Content-Type", "application/json")
    :setHeader("Authorization", "Bearer token123")
    :setParameter("name", "Jane Doe")
    :setParameter("email", "jane.doe@example.com")
    :setParameter("bio", "Software Developer")
    :setParameter("website", "https://jane.example.com")
    :setParameter("location", "San Francisco")
    :put()

local data = response:getData()
local statusCode = response:getResponseCode()

if statusCode == 200 then
    print("User updated successfully!")
    print("Updated user data: " .. data)
elseif statusCode == 201 then
    print("User created successfully!")
    print("New user data: " .. data)
else
    print("Failed to update user. Status: " .. statusCode)
end

使用 PUT 创建资源​

-- 在特定 URL 创建新资源
local response = Request("https://api.example.com/files/document-v2")
    :setHeader("Content-Type", "application/json")
    :setParameter("content", "This is the new document content")
    :setParameter("version", "2.0")
    :setParameter("author", "John Doe")
    :put()

local status = response:getResponseCode()
if status == 201 then
    print("Document created successfully!")
elseif status == 200 then
    print("Document replaced successfully!")
else
    print("Operation failed with status: " .. status)
end

条件性 PUT 更新​

-- 仅当资源未被修改时才更新
local response = Request("https://api.example.com/articles/123")
    :setHeader("Content-Type", "application/json")
    :setHeader("If-Match", "etag-value-here")
    :setHeader("Authorization", "Bearer token")
    :setParameter("title", "Updated Article Title")
    :setParameter("content", "Updated article content")
    :setParameter("author", "John Doe")
    :put()

local status = response:getResponseCode()
if status == 412 then
    print("Update failed: Resource has been modified by another user")
elseif status == 200 or status == 201 then
    print("Article updated/replaced successfully")
end

完整替换资源​

-- 用新数据替换整个产品
local response = Request("https://api.example.com/products/456")
    :setHeader("Content-Type", "application/json")
    :setParameter("name", "Premium Widget")
    :setParameter("description", "A high-quality widget with advanced features")
    :setParameter("price", "99.99")
    :setParameter("stock", "50")
    :setParameter("category", "electronics")
    :setParameter("specs", '{"color": "black", "weight": "200g", "warranty": "2 years"}')
    :put()

local updatedProduct = response:getData()
print("Product replaced: " .. updatedProduct)

说明​

  • 在调用 put() 之前，请使用 setParameter() 向请求体添加数据
  • PUT 请求应包含资源的完整表示，而不仅仅是更改的部分
  • PUT 与 PATCH 的区别在于：PUT 会替换整个资源，而 PATCH 进行部分更新
  • 成功的 PUT 操作通常返回：
    • 200 OK，响应体中包含更新后的资源（用于更新）
    • 201 Created，响应体中包含新资源（用于创建）
    • 204 No Content，如果操作成功但不需要响应体
  • 该方法返回一个 Response 对象，您可以通过它访问响应数据和状态码
  • 请始终检查响应状态码，以确保请求成功
  • PUT 请求是幂等的——多次发起相同的请求应产生相同的效果
  • 使用 PUT 请求时请谨慎，因为它们会完全替换现有数据