頂級保留屬性名稱

頂級的JSON對象可能包含下面這些屬性

apiVersion

屬性值類型: 字符串(string)
父節(jié)點: -

呈現(xiàn)請求中服務API期望的版本，以及在響應中保存的服務API版本。應隨時提供apiVersion。這與數(shù)據(jù)的版本無關。將數(shù)據(jù)版本化應該通過其他的機制來處理，如etag。

示例：

{ "apiVersion": "2.1" }

context

屬性值類型: 字符串(string)
父節(jié)點: -

客戶端設置這個值，服務器通過數(shù)據(jù)作出回應。這在JSON-P和批處理中很有用，用戶可以使用_context_將響應與請求關聯(lián)起來。該屬性是頂級屬性，因為不管響應是成功還是有錯誤，_context_總應當被呈現(xiàn)出來。_context_不同于_id_在于_context_由用戶提供而_id_由服務分配。

示例：

請求 #1:

http://www.google.com/myapi?context=bart

請求 #2:

http://www.google.com/myapi?context=lisa

響應 #1:

{
  "context": "bart",
  "data": {
    "items": []
  }
}

響應 #2:

{
  "context": "lisa",
  "data": {
    "items": []
  }
}

公共的JavaScript處理器通過編碼同時處理以下兩個響應：

function handleResponse(response) {
  if (response.result.context == "bart") {
    // 更新頁面中的 "Bart" 部分。
  } else if (response.result.context == "lisa") {
    // 更新頁面中的 "Lisa" 部分。
  }
}

id

屬性值類型: 字符串(string)
父節(jié)點: -

服務提供用于識別響應的標識(無論請求是成功還是有錯誤)。這對于將服務日志和單獨收到的響應對應起來很有用。

示例：

{ "id": "1" }

method

屬性值類型: 字符串(string)
父節(jié)點: -

表示對數(shù)據(jù)即將執(zhí)行，或已被執(zhí)行的操作。在JSON請求的情況下，_method_屬性可以用來指明對數(shù)據(jù)進行何種操作。在JSON響應的情況下，_method_屬性表明對數(shù)據(jù)進行了何種操作。

一個JSON-RPC請求的例子，其中_method_屬性表示要在_params_上執(zhí)行的操作：

{
  "method": "people.get",
  "params": {
    "userId": "@me",
    "groupId": "@self"
  }
}

params

屬性值類型: 對象(object)
父節(jié)點: -

這個對象作為輸入?yún)?shù)的映射發(fā)送給RPC請求。它可以和_method_屬性一起用來執(zhí)行RPC功能。若RPC方法不需要參數(shù)，則可以省略該屬性。

示例：

{
  "method": "people.get",
  "params": {
    "userId": "@me",
    "groupId": "@self"
  }
}

data

屬性值類型: 對象(object)
父節(jié)點: -

包含響應的所有數(shù)據(jù)。該屬性本身擁有許多保留屬性名，下面會有相應的說明。服務可以自由地將自己的數(shù)據(jù)添加到這個對象。一個JSON響應要么應當包含一個_data_對象，要么應當包含_error_對象，但不能兩者都包含。如果_data_和_error_同時出現(xiàn)，則_error_對象優(yōu)先。

error

屬性值類型: 對象(object)
父節(jié)點: -

表明錯誤發(fā)生，提供錯誤的詳細信息。錯誤的格式支持從服務返回一個或多個錯誤。一個JSON響應可以有一個_data_對象或者一個_error_對象，但不能兩者都包含。如果_data_和_error_都出現(xiàn)，_error_對象優(yōu)先。

示例：

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found
    }]
  }
}