共用方式為

JSON 序列化規則 (ADO.NET 資料服務架構)

  • 發行項

ADO.NET 資料服務所使用的 JSON 格式包括序列化 (Serialization) 套用至可透過服務存取之所有資源的資料的通訊協定 (Protocol)。

所有資源通用的序列化規則

本主題將列出 ADO.NET 資料服務中所有資源通用的序列化規則。

Note附註

您可以使用在 JSON 格式之間來回轉換的程式庫來降低許多序列化的複雜度。如需詳細資訊，請參閱 CodePlex (英文)。

Null 值

您必須使用 JSON 常值 'null' 來表示所有 Null 值。

實體集

  • 實體集必須表示成 JSON 物件的陣列，而且該集合中的每個實體類型執行個體 (Instance) 都有一個物件。

  • 空白實體集必須表示成空白 JSON 陣列，亦即沒有任何項目的陣列。

實體類型

  • 實體類型必須序列化成為 JSON 物件。

  • 此類型的每個屬性都必須表示成物件內的名稱/值組。此名稱/值組中的名稱是屬性名稱，而此組的值是屬性的值。屬性出現在物件內部的順序並不重要。

  • 實體類型執行個體的 JSON 序列化必須包含名為 __metadata 的屬性。雖然此屬性不是資料，不過卻是這個通訊協定中定義的慣例，可針對類型的特定執行個體指定中繼資料。__metadata 屬性的值包含兩個屬性：uri 和 type。uri 屬性必須是可識別目前實體類型執行個體的 URI。更精確的說，移除最後一個非空白路徑區段之後，此 URI 必須相對於要求的 URI。'Type' 屬性的值必須是代表伺服器之實體類型執行個體類型的命名空間限定名稱 (Namespace Qualified Name)，例如 namespaceName.typeName。__metadata 屬性可能會包含 etag 屬性。如果實體已經定義了 etag 屬性，etag 屬性就必須存在。

    • 如果 JSON 物件所代表的實體類型屬於繼承階層架構 (Inheritance Hierarchy) 的一部分，就必須包含 Type 屬性。如果不是，'Type' 屬性就是選擇性的。

    • 如需有關 URI 和 type 參數何時必須、可能和不得存在的詳細資料，請參閱一般 HTTP 需求。

複雜類型

  • 複雜類型必須序列化成為 JSON 物件。

  • 複雜類型的每個屬性都必須表示成 JSON 物件內的名稱/值組。此名稱/值組中的名稱是屬性名稱，而此組的值是屬性的值。屬性出現在物件內部的順序並不重要。

導覽屬性和連結屬性

  • 根據預設，系統會延後導覽和連結屬性的序列化。延後此內容時，__deferred 項目底下的 uri 屬性就不會包含標準 URI。如需如何擴充此屬性的詳細資訊，請參閱延後的內容 (JASON)。

  • 由於導覽和連結屬性代表相關實體集的關聯，所以序列化導覽屬性所遵循的規則與實體集相同，但有下列例外：

    • 最上層 XML 項目必須與導覽或連結屬性的名稱 (而非實體集名稱) 相符。

屬性

屬性可以用兩種方式序列化：透過包裝標記，或採用不含任何包裝標記的未裝飾格式。

若要使用包裝標記，將屬性序列化成 JSON：

  • 此序列化會表示成 JSON 物件內的名稱/值組，例如 {<propertyname>:<propertyvalue>}。

  • 本文件的表格將示範如何使用 JSON 來格式化 Entity Data Model (EDM) 所定義的每個基本型別 (Primitive Type)。JSON 序列化資料行會定義屬性值的序列化方式。

若要在不使用包裝標記的情況下，將屬性序列化成 JSON (以 /$value 結束的 URI)：

  • 在這種格式中，只會序列化屬性的值。下表的 JSON 序列化資料行會指定在此格式中，每個基本型別的序列化方式。

  • 如果型別的值為 Null 或空白，就表示沒有採用此格式的屬性值序列化。在這種情況下，通訊協定的互動模型必須發出這類值是否存在的訊號。

EDM 基本型別 JSON 序列化 Null 表示 (僅包含包裝標記) 空白值表示 (僅包含包裝標記)

Edm.Binary

Convert.ToBase64String(<bytes>, Base64FormattingOptions.None)

無法使用

大小為 0 的陣列

Edm.Boolean

true | false

無法使用

無法使用

Edm.Byte

<short>.ToString(CultureInfo.InvariantCulture)

無法使用

無法使用

Edm.DateTime

\/Date(<ticks>)\/ <ticks>: 從 1970 年 1 月 1 日開始計算的毫秒數。請注意：這個格式與 ASP.NET AJAX 架構所使用的格式相同。如需詳細資料，請參閱 DateTime (英文)。如需使用 ADO.NET 資料服務的範例，請參閱 HttpWebRequest POST (ADO.NET 資料服務架構)。

無法使用

無法使用

Edm.Decimal

<Decimal>.ToString(CultureInfo.InvariantCulture). 請注意：JSON 沒有 Decimal 資料型別。此值會轉換成字串，防止資料遺失。

無法使用

無法使用

Edm.Double

XmlConvert.ToString(<double>)

無法使用

無法使用

Edm.Guid

<Guid>. ToString() xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

無法使用

無法使用

Edm.Int16

<int16>.ToString(CultureInfo.InvariantCulture)

無法使用

無法使用

Edm.Int32

<int32>.ToString(CultureInfo.InvariantCulture)

無法使用

無法使用

Edm.Int64

<int64>.ToString(CultureInfo.InvariantCulture). 請注意：傳回成為字串，防止由於 JSON 數目限制而導致資料遺失。

無法使用

無法使用

Edm.SByte

<short>.ToString(CultureInfo.InvariantCulture)

無法使用

無法使用

Edm.Single

XmlConvert.ToString(<float>). 如果此值為無限大，就會使用 'infinity'。

無法使用

無法使用

Edm.String

<string>

null

""

Edm.UInt16

<uint16>.ToString(CultureInfo.InvariantCulture)

無法使用

無法使用

Edm.UInt32

<uint32>.ToString(CultureInfo.InvariantCulture)

無法使用

無法使用

Edm.UInt64

<uint64>.ToString(CultureInfo.InvariantCulture). 請注意：傳回成為字串，防止由於 JSON 數目限制而導致資料遺失。

無法使用

無法使用

System.Data.Linq.Binary

Convert.ToBase64String(<binary>.ToArray(),Base64FormattingOptions.None)

無法使用

大小為 0 的陣列

System.Data.Linq.XElement

<element>.ToString(System.Data.Linq.SaveOptions.None)

null

""

另請參閱

概念

JSON 格式 (ADO.NET 資料服務架構)
延後的內容 (JSON ADO.NET 資料服務架構)
ADO.NET 資料服務架構