POST 方法 (ADO.NET 資料服務架構)

發行項
08/21/2008

下列清單和範例將描述 ADO.NET 資料服務之 POST 方法所使用的通訊協定 (Protocol)。＜超文字傳輸協定，RFC 2616＞(英文) 所需的其他行為描述於一般 HTTP 需求 (ADO.NET 資料服務架構) 和 PUT、POST 和 DELETE (ADO.NET 資料服務架構) 中。

下列通訊協定適用於使用 POST 方法的 HTTP 要求。

針對 ADO.NET 資料服務資源執行的 POST 方法必須包含要求 URI 之分葉節點所識別之實體集或實體類型的序列化 (Serialization)，而且包含在要求主體中。要求的語意 (Semantics) 會指出此資料要成為新的 ADO.NET 資料服務資源。
POST 要求可能會在要求主體中包含要建立之實體的實體索引鍵屬性值。如果與資料服務相關聯的儲存區提供者會自動指派索引鍵值，這類要求可能會失敗，並傳回「422 無法處理的實體」回應碼。
POST 要求不得指定要加入之實體的 URI。如果指定了此項目，系統就會傳回「400 錯誤要求」回應碼，而且不會加入此實體。
所有成功的 POST 要求都會將新的實體插入實體集中。要求會傳回「201 已建立」回應碼，而且在含有新建立實體之 URI 的回應中包含位置標頭。
系統會忽略要求裝載中任何延後的內容附註。
如果 HTTP 標頭中的要求 URI 與要求裝載中的相關聯 URI 不符，就會優先使用要求 URI，而且此裝載會被視為它包含要求 URI 的值。
如果執行作業時發生了錯誤，服務作業的 POST 要求可能會傳回「500 內部伺服器錯誤」回應碼。例如，DataServiceException 以外的執行階段例外狀況 (Exception)。

支援 POST 方法的類型

下列範例將顯示 HTTP URI 語法中的結束項目，以及這些項目支援 POST 方法的條件。每個案例都包含 POST 要求的描述以及可預測的結果。

/<EntitySet>

下列 URI 範例會將實體集顯示成結束項目：

/Customers

描述：

支援 POST 方法。
將要求主體所指定的單一實體類型執行個體 (Instance) 插入集合中。
要插入之實體的 URI 不得顯示在要求主體中。如果存在的話，系統就會傳回「400 錯誤要求」回應碼。
要求裝載可能會包含透過導覽或連結屬性與這個實體集相關之實體集的新內容。這類更新沒有定義任何最大深度。
可將新建立的最上層實體繫結至現有或其他新建立的實體：
- 如果資源 1 僅包含現有資源 2 的 URI 當做資源導覽或連結屬性的值，資源 1 就會繫結至資源 2。
- 如果資源 1 包含全新和相關資源的 URI 與主體，系統就會傳回「400 錯誤要求」回應碼，因為不得在插入期間指定 URI 屬性。
- 如果資源 1 僅包含主體，但不包含全新和相關資源 2 的 URI，就會插入並繫結資源 1 和資源 2。

範例：

下列範例會插入新的 Customer 並將它繫結至現有的訂單 1 和 3。

要求 URI 會以/Customers.結束。它採用了 JSON 格式。

{
Company Name:"Contoso"
City: "Seattle"
Orders : [   
{ __metadata: {uri:"/Orders(1)" }},
{ __metadata: {uri:"/Orders(3)" }}
]
}

下列範例會插入新的 Customer 以及新的相關訂單。

要求 URI 會以/Customers.結束。它採用了 JSON 格式。

{
Company Name:"Contoso Widgets"
City: "Seattle"
Orders : [   
{ 
    OrderName: "NewOrder",
    // additional property values go here
}
]
}

附註
如果實體類型不屬於繼承階層架構 (Inheritance Hierarchy) 的一部分，JSON 序列化規則 (ADO.NET 資料服務架構)中所描述之 __metadata 物件的 type 參數就是選擇性的。如果沒有指定類型，就會採用實體集的基底類型。如果此類型屬於繼承階層架構的一部分，就必須指定 type 參數。

/EntitySet(keyPredicate)

下列 URI 範例會將索引鍵述詞 (Predicate) 顯示成結束項目：

/Customers('ALFKI')

描述：

不支援 POST 方法。

/<NavigationProperty> 或 /<LinkProperty>

下列 URI 範例會將導覽屬性顯示成結束項目：

/Customers('ALFKI')/Orders
/Products(1)/Category

描述：

如果關聯性端具有大於一的基數，導覽屬性和連結屬性就會支援 POST 方法。
導覽和連結屬性必須指向基數大於一的關聯性端，否則系統就會傳回「405 不支援的方法」回應碼。
這些屬性與先前所述的 /<EntitySet> 會使用相同的語意，不過新插入的資源會繫結至 second-to-last URI 區段所識別的資源。

/<ComplexType>

下列 URI 範例會將複雜類型顯示成結束項目：

/Customers('ALFKI’)/Address

描述：

不支援 POST 方法。

/<Property>

下列 URI 範例會將屬性顯示成結束項目：

/Customers('ALFKI’)/FirstName

描述：

不支援 POST 方法。

<Property>/$value

下列 URI 範例會將屬性值顯示成結束項目：

/Customers('ALFKI’)/FirstName/$value

描述：

不支援 POST 方法。

/<ServiceOperationName>

下列 URI 範例會將服務作業名稱顯示成結束項目：

/CustomersByCity?city=London

描述：

支援 POST 方法。
在伺服器上叫用 (Invoke) 服務作業。
參數會使用要求主體傳遞至服務作業。
參數會使用 application/x-www-form-urlencoding 加以編碼。
您可以使用 GET 或 POST 動詞來呼叫服務作業，而且服務的中繼資料文件會指定每個服務作業所支援的動詞。POST 是針對每個服務作業啟用的。

另請參閱

概念

PUT 方法 (ADO.NET 資料服務架構)
DELETE 方法 (ADO.NET 資料服務架構)

共用方式為