REST Resource: photo

资源：照片

照片用于存储 360 度全景照片以及照片元数据。

JSON 表示法 
{
  "photoId": {
    object (PhotoId)
  },
  "uploadReference": {
    object (UploadRef)
  },
  "downloadUrl": string,
  "thumbnailUrl": string,
  "shareLink": string,
  "pose": {
    object (Pose)
  },
  "connections": [
    {
      object (Connection)
    }
  ],
  "captureTime": string,
  "uploadTime": string,
  "places": [
    {
      object (Place)
    }
  ],
  "viewCount": string,
  "transferStatus": enum (TransferStatus),
  "mapsPublishStatus": enum (MapsPublishStatus)
}
字段
photoId

object (PhotoId)

必需。仅限输出。更新照片时必填。仅在创建照片时输出。照片的标识符，该标识符在 Google 中的所有照片中是唯一的。
uploadReference

object (UploadRef)

仅限输入。创建照片时必填。仅限输入。上传照片字节的资源网址。
downloadUrl

string

仅限输出。照片字节的下载网址。仅当 GetPhotoRequest.view 设置为 PhotoView.INCLUDE_DOWNLOAD_URL 时，才会设置此字段。
thumbnailUrl

string

仅限输出。用于显示指定照片预览的缩略图网址。
pose

object (Pose)

可选。照片姿势。
connections[]

object (Connection)

可选。与其他照片的关联。连接表示从该照片到另一张照片的链接。
captureTime

string (Timestamp format)

可选。照片拍摄的绝对时间。如果照片没有 exif 时间戳，系统会使用此时间戳来设置照片元数据中的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
uploadTime

string (Timestamp format)

仅限输出。图片的上传时间。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
places[]

object (Place)

可选。此照片所属的地点。
viewCount

string (int64 format)

仅限输出。照片的查看次数。
transferStatus

enum (TransferStatus)

仅限输出。此照片的权利转移状态。
mapsPublishStatus

enum (MapsPublishStatus)

仅限输出。在 Google 地图中的状态，照片是已发布还是被拒绝。

PhotoId

Photo 的标识符。

JSON 表示法 
{
  "id": string
}
字段
id

string

照片的唯一标识符。

UploadRef

媒体文件的上传参考。

JSON 表示法 
{

  // Union field file_source can be only one of the following:
  "uploadUrl": string
  // End of list of possible types for union field file_source.
}
字段
联合字段 file_source。必需。file_source 只能是下列其中一项：
uploadUrl

string

每个用户的上传引用都应该是唯一的。其格式如下：“https://streetviewpublish.googleapis.com/media/user/{account_id}/photo/{uploadReference}”

姿势

实体的原始姿态测量。

JSON 表示法 
{
  "latLngPair": {
    object (LatLng)
  },
  "altitude": number,
  "heading": number,
  "pitch": number,
  "roll": number,
  "gpsRecordTimestampUnixEpoch": string,
  "level": {
    object (Level)
  },
  "accuracyMeters": number
}
字段
latLngPair

object (LatLng)

位置方向的纬度和经度对，具体说明如下：https://cloud.google.com/datastore/docs/reference/rest/Shared.Types/LatLng。创建 Photo 时，如果未提供纬度和经度对，系统会使用 exif 标头中的地理定位。如果照片或 exif 标头中未提供纬度和经度对，则会导致照片处理失败。
altitude

number

位置方向高于 WGS84 椭球体的海拔高度（以米为单位）。NaN 表示未测量的数量。
heading

number

以下姿势参数与照片的中心有关。它们与 https://developers.google.com/streetview/spherical-metadata 相匹配。罗盘航向，在照片中心测量，以与北方所呈顺时针角度表示。值必须大于等于 0 且小于 360。NaN 表示未测量的数量。
pitch

number

俯仰角，在照片中心测量，以度为单位。值必须大于等于 -90 且小于等于 90。值为 -90 表示正向下看，值为 90 表示正向上看。NaN 表示未测量的数量。
roll

number

滚转角，以度为单位。值必须大于等于 0 且小于 360。值为 0 表示与地平线齐平。NaN 表示未测量的数量。
gpsRecordTimestampUnixEpoch

string (Timestamp format)

GPS 记录的时间（从世界协调时间 (UTC) 公元纪年开始）。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
level

object (Level)

用于配置垂直导航的楼层（建筑物中的楼层）。
accuracyMeters

number

此姿势的预估水平精确度（以米为单位），置信度为 68%（一个标准差）。例如，在 Android 上，可通过以下方法获得该值：https://developer.android.com/reference/android/location/Location#getAccuracy()。其他平台采用不同的方法来获取类似的准确度估算值。

LatLng

表示纬度/经度对的对象。该对象以一对双精度数表示，分别代表纬度度数和经度度数。除非另有说明，否则该对象必须符合 WGS84 标准。值必须介于标准化范围内。

JSON 表示法 
{
  "latitude": number,
  "longitude": number
}
字段
latitude

number

纬度（以度为单位）。它必须在 [-90.0, +90.0] 范围内。
longitude

number

经度（以度为单位）。它必须在 [-180.0, +180.0] 范围内。

级别

包含级别号及其对应名称的级别信息。

JSON 表示法 
{
  "number": number,
  "name": string
}
字段
number

number

可选。楼层号，用于订购。0 表示地平面以上，1 表示地上的第一层，-1 表示地下的第一层。允许使用非整数值。
name

string

必需。为此级别分配的名称，不得超过 3 个字符。思考一下，如果有电梯，该楼层的电梯按钮会如何标示。

连接

连接是指从源照片到目标照片的链接。

JSON 表示法 
{
  "target": {
    object (PhotoId)
  }
}
字段
target

object (PhotoId)

必需。从包含的照片到另一张照片的连接的目的地。

地点

实体的地点元数据。

JSON 表示法 
{
  "placeId": string,
  "name": string,
  "languageCode": string
}
字段
placeId

string

地点标识符，如 https://developers.google.com/places/place-id 中所述。
name

string

仅限输出。地点的名称，已本地化为 languageCode。
languageCode

string

仅限输出。用于对名称进行本地化的 languageCode。它应该是请求中指定的 languageCode，但可能是后备代码。

TransferStatus

权利转让的状态。

枚举
TRANSFER_STATUS_UNKNOWN 未指定此转移作业的状态。
NEVER_TRANSFERRED 此照片从未进行过传输。
PENDING 此照片传输已开始，但接收者尚未回复。
COMPLETED 照片传输完毕，此照片已传输给收件人。
REJECTED 收件人拒绝了此照片传输。
EXPIRED 照片传输在接收者未执行任何操作之前已过期。
CANCELLED 发送者取消了此照片的传输。
RECEIVED_VIA_TRANSFER 由于权利转让，接收方拥有这张照片。

MapsPublishStatus

照片在 Google 地图中的发布状态。

枚举
UNSPECIFIED_MAPS_PUBLISH_STATUS 照片状态未知。
PUBLISHED 照片会通过 Google 地图向公众发布。
REJECTED_UNKNOWN 照片由于未知原因而被拒。

方法

create

 在客户端使用返回的 UploadRef 上传完照片后，CreatePhoto 会将上传的 Photo 发布到 Google 地图上的街景。

delete

 删除 Photo 及其元数据。

get

 获取指定 Photo 的元数据。

startUpload

 创建上传会话，以开始上传照片字节。

update

 更新 Photo 的元数据，例如姿势、地点关联、连接等。