PUT 方法(ADO.NET 数据服务框架)
下面的列表和示例中描述了针对 ADO.NET 数据服务对 PUT 方法的使用的协议。通用 HTTP 要求(ADO.NET 数据服务框架)和 PUT、POST 和 DELETE(ADO.NET 数据服务框架)中描述了超文本传输协议 (RFC 2616) 所需的其他行为。
下列协议适用于使用 PUT 方法的 HTTP 请求。
所有成功的 PUT 请求在返回时带有响应代码“204 无内容”。
针对 ADO.NET 数据服务资源的 PUT 请求会将请求中的内容与资源的当前状态合并。通过将请求正文的每个组件与服务器上存在的资源进行比较来完成此合并。
如果请求正文中的某个组件在资源中不存在,则该请求表示一个架构冲突,并将返回响应代码“422 无法处理的实体”。
当请求正文中的某个组件与资源上的某个组件匹配时,将对请求正文中的元素的子级继续进行匹配。
如果一个资源的类型不可为 null,而 PUT 请求将该资源的值设置为 null,则会导致返回响应代码“422 无法处理的实体”。
如果一个资源的类型未定义空状态,而 PUT 请求将该资源的值设置为空,则会导致返回响应代码“422 无法处理的实体”。
由于 PUT 是 idempotent 所必需的,因此不能使用 PUT 将资源插入资源集中。换句话说,PUT 无法实现与 POST 类似的追加或创建语义。
请求负载中任何延迟的内容批注都将被忽略。
如果 HTTP 标头中的请求 URI 与请求负载中的关联 URI 不匹配,则请求 URI 优先。将负载视为其包含请求 URI 的值来处理。
如果 PUT 请求的正文包含作为资源序列化的一部分进行操作的资源的键,则将忽略这些键值。无法更新资源键值。
支持 PUT 方法的类型
本文档后面的示例汇总了支持 PUT 方法的资源类型。如果请求主体没有针对指定资源的足够权限,则对支持 PUT 方法的资源类型的 PUT 请求可能会失败。在此情况下,如超文本传输协议 (RFC 2616) 中所述,请求将返回响应代码“401 未授权”或响应代码“403 已禁止”,具体取决于为数据服务提供替代主体是否可让请求成功执行。
下面的示例显示了支持或不支持 PUT 方法的 HTTP URL 路径语法的结束元素。每个示例都包含对 PUT 请求和可预知的结果的描述。
/<EntitySet>
示例 URI 最终元素
下面的 URI 示例将一个实体集显示为结束元素。
/Customers
说明:
PUT 方法不支持将实体集作为结束元素。将返回响应代码“405 不支持的方法”。
/<EntitySet>(keyPredicate)
下面的 URI 示例将一个 keyPredicate 显示为结束元素。
/Customers('ALFKI')
说明:
支持的 PUT 方法。
更新由请求正文提供并由 keyPredicate 标识的单个资源类型实例
不支持对关联类型进行深度更新。
支持绑定基数为一的关系方。
支持将 keyPredicate 标识的资源 R1 绑定到现有资源:
如果 R1 仅包含现有资源 R2 的 URI 作为导航或链接的值(标识基数为一的关系方),则将 R1 绑定到 R2。
如果 R1 包含 URI 和资源正文,则假定 URI 表示已绑定到 R1 的现有资源 R2。然后,使用正文中指定的值更新 R2。
如果 R1 仅包含正文,而不包含相关资源 R2 的 URI 作为导航或链接属性的值,则将返回“400 错误的请求”。
向此资源发送相当于文字值 null 的负载会导致产生响应代码“400 错误的请求”。
无法更新构成资源键的一个或多个属性的值。如果 PUT 请求的负载中出现新值,则将忽略这些新值。
下面的 URI 示例将一个数字键谓词显示为结束元素。代码将更新 Product #123 以及与之关联的类别;它将重新绑定关联的类别。
/Products(123)
JSON 格式
{
__metadata:{ uri="/Products(123)",
type="NorthwindModel.Product" },
Name:"New product name"
Category : { __metadata: {uri:"/Category(2)" } }
}
/<NavigationProperty> 或 /<LinkProperty>
下面的 URI 示例将导航属性和链接属性显示为结束元素。
/Customers('ALFKI')/Orders
/Customers('ALKFI')/Orders(1)
/Products(1)/Category
(仅对以基数 1 结束的关系起作用)
说明:
支持的 PUT 方法。
如果导航或链接属性标识单个资源或基数为一的关系方,则:
- 使用与
/<ResourceSet>(keyPredicate)
相同的语义,不过,仅包含 null 值的请求正文将会取消该资源与由第二个到最后一个 URI 段标识的资源之间的绑定。
- 使用与
如果导航或链接属性标识多个资源或“多个”关系方,则:
- 不受支持,并将返回响应代码“405 不支持的方法”。
/<ComplexType>
下面的 URI 示例将一个复杂类型显示为结束元素。
/Customers('ALFKI')/Address
说明:
支持的 PUT 方法。
用请求正文的内容更新由请求 URI 的叶级标识的复杂类型。
支持深度更新。
请求负载可以包含嵌套的复杂类型的可更新内容。只要深度位于包含资源类型实例之内,则不会为此类更新定义最大深度。
/<Property>
下面的 URI 示例将一个属性显示为结束元素:
/Customers('ALFKI')/FirstName
说明:
支持的 PUT 方法。
支持更新属性的值。
该属性可以设置为 null。
- JSON 使用 null 基元。
/<Property>/$value
下面的 URI 示例将一个属性值显示为结束元素:
/Customers('ALFKI')/FirstName/$value
说明:
支持的 PUT 方法。
支持更新属性的原始值。
不提供将值设置为 null 的方法。
请求正文的 MIME 类型必须与服务器上的资源类型的 MIME 类型匹配。
如果该属性的类型定义一个空状态,则零字节的请求正文会将该属性的值设置为空;否则,将返回响应代码“422 无法处理的实体”。
/<ServiceOperationName>
下面的 URI 示例将一个服务操作名称显示为结束元素:
/CustomersByCity?city='London'
说明:
不支持 PUT 方法。
不为 ADO.NET 数据服务操作定义 PUT 谓词。
返回响应代码“405 不支持的方法”。
有关 PUT 请求的往返限制
ADO.NET 数据服务框架支持一种往返方案,其中使用对特定 Uri 的 GET 请求来返回负载。一个典型的情况是,修改某些数据并将相同的负载传入到对此 Uri 的 PUT 请求中。当实体中的属性不是键而是标识列时,此方案不起作用。唯一的解决方法是,在存储架构定义语言 (SSDL) 文件中将该标识列更改为计算得到的属性。
另请参见
概念
HttpWebRequest GET(ADO.NET 数据服务框架)
HttpWebRequest PUT(ADO.NET 数据服务框架)
HttpWebRequest POST(ADO.NET 数据服务框架)
HttpWebRequest DELETE(ADO.NET 数据服务框架)
PUT、POST 和 DELETE(ADO.NET 数据服务框架)