REST Resource: photo

資源：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)

必填。僅供輸出。更新相片時必須提供，僅在建立相片時輸出。相片的 ID，在 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 時間戳記，系統會使用這個時間戳記在相片中繼資料中設定時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
uploadTime

string (Timestamp format)

僅供輸出。圖片上傳時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
places[]

object (Place)

(選用步驟) 這張相片所屬的地點。
viewCount

string (int64 format)

僅供輸出。相片的觀看次數。
transferStatus

enum (TransferStatus)

僅供輸出。這張相片的著作權轉移狀態。
mapsPublishStatus

enum (MapsPublishStatus)

僅供輸出。在 Google 地圖中的狀態，包括相片是否已發布或遭拒。

PhotoId

Photo 的 ID。

JSON 表示法 
{
  "id": string
}
欄位
id

string

相片的專屬 ID。

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 之間 (包含 0，但不包含 360)。NaN 表示未測量的數量。
pitch

number

俯仰角度，以相片中心為測量點，單位為度。值必須介於 -90 到 90 之間 (含頭尾)。值為 -90 代表直接向下看，值為 90 代表直接向上看。NaN 表示未測量的數量。
roll

number

側傾角度 (以度為單位)。值必須介於 0 至 360 之間 (包含 0，但不包含 360)。值為 0 表示與地平線齊平。NaN 表示未測量的數量。
gpsRecordTimestampUnixEpoch

string (Timestamp format)

自世界標準時間 Epoch 紀元時間起算的 GPS 記錄時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
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

地點 ID，如 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 的中繼資料，例如姿勢、地點關聯、連線等。