顶层保留属性名

JSON 对象的顶层可以包含以下属性。

apiVersion

属性值类型：string | 父级：-

在请求中表示所需的服务 API 版本，在响应中表示提供服务的 API 版本。apiVersion 应始终存在。这与数据的版本无关。数据版本控制应通过其他机制（如 etag）来处理。 示例：

{ "apiVersion": "2.1" }

context

属性值类型：string | 父级：-

客户端设置此值，服务器在响应中回传数据。这在 JSON-P 和批处理场景中很有用，用户可以使用 context 将响应与请求关联起来。此属性是顶层属性，因为无论响应是成功还是错误，context 都应存在。context 与 id 的区别在于，context 由用户指定，而 id 由服务分配。 示例： 请求 #1：

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

请求 #2：

https://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 | 父级：-

由服务器提供的响应标识符（无论响应是成功还是错误）。这对于将服务器日志与客户端接收到的单个响应进行关联非常有用。 示例：

{ "id": "1" }

method

属性值类型：string | 父级：-

表示要对数据执行的操作，或已对数据执行的操作。在 JSON 请求中，method 属性可用于指示要对数据执行的操作。在 JSON 响应中，method 属性可以指示对数据执行的操作。 一个示例是在 JSON-RPC 请求中，method 指示要对 params 属性执行的操作：

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

params

属性值类型：object | 父级：-

此对象用作发送到 RPC 请求的输入参数映射。它可以与 method 属性结合使用来执行 RPC 函数。如果 RPC 函数不需要参数，则可以省略此属性。 示例：

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

data

属性值类型：object | 父级：-

响应中所有数据的容器。此属性本身具有许多保留属性名，将在下面描述。服务可以自由地向此对象添加自己的数据。JSON 响应应包含 data 对象或 error 对象，但不能同时包含两者。如果 data 和 error 同时存在，则 error 对象优先。

error

属性值类型：object | 父级：-

表示发生了错误，并包含错误的详细信息。错误格式支持从服务返回一个或多个错误。JSON 响应应包含 data 对象或 error 对象，但不能同时包含两者。如果 data 和 error 同时存在，则 error 对象优先。 示例：

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