頂級(jí)保留屬性名稱

頂級(jí)的JSON對(duì)象可能包含下面這些屬性

apiVersion

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

呈現(xiàn)請(qǐng)求中服務(wù)API期望的版本，以及在響應(yīng)中保存的服務(wù)API版本。應(yīng)隨時(shí)提供apiVersion。這與數(shù)據(jù)的版本無(wú)關(guān)。將數(shù)據(jù)版本化應(yīng)該通過(guò)其他的機(jī)制來(lái)處理，如etag。

示例：

{ "apiVersion": "2.1" }

context

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

客戶端設(shè)置這個(gè)值，服務(wù)器通過(guò)數(shù)據(jù)作出回應(yīng)。這在JSON-P和批處理中很有用，用戶可以使用_context_將響應(yīng)與請(qǐng)求關(guān)聯(lián)起來(lái)。該屬性是頂級(jí)屬性，因?yàn)椴还茼憫?yīng)是成功還是有錯(cuò)誤，_context_總應(yīng)當(dāng)被呈現(xiàn)出來(lái)。_context_不同于_id_在于_context_由用戶提供而_id_由服務(wù)分配。

示例：

請(qǐng)求 #1:

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

請(qǐng)求 #2:

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

響應(yīng) #1:

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

響應(yīng) #2:

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

公共的JavaScript處理器通過(guò)編碼同時(shí)處理以下兩個(gè)響應(yīng)：

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

id

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

服務(wù)提供用于識(shí)別響應(yīng)的標(biāo)識(shí)(無(wú)論請(qǐng)求是成功還是有錯(cuò)誤)。這對(duì)于將服務(wù)日志和單獨(dú)收到的響應(yīng)對(duì)應(yīng)起來(lái)很有用。

示例：

{ "id": "1" }

method

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

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

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

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

params

屬性值類型: 對(duì)象(object)
父節(jié)點(diǎn): -

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

示例：

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

data

屬性值類型: 對(duì)象(object)
父節(jié)點(diǎn): -

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

error

屬性值類型: 對(duì)象(object)
父節(jié)點(diǎn): -

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

示例：

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