CameraEventImage 架構

Nest Cam (舊版) Nest Hub Max Nest Doorbell (舊版) 

sdm.devices.traits.CameraEventImage

只要裝置支援從事件生成圖片，就屬於這項特徵。

欄位

這個特徵沒有可用的欄位。

指令

GenerateImage

提供下載攝影機圖片的網址。

這個指令支援下列事件：

類型 元素 說明
活動 CameraMotion 特徵的動作事件 攝影機偵測到動作。
活動 攝影機人員特徵的人員事件 攝影機偵測到有人。
活動 CameraSound 特徵的聲音事件 攝影機偵測到聲響。
活動 DoorbellChime 特徵的 Chime 事件 有人按了門鈴。
在指令要求中使用支援事件的 eventId，即可接收與該事件相關的攝影機圖片下載網址。

GenerateImage 請求和回應

要求

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraEventImage.GenerateImage",
  "params" : {
    "eventId" : "iYTZwoT3K-OgtqzhF_KTC5dhEb..."
  }
}

回應

{
  "results" : {
    "url" : "https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "token" : "g.0.eventToken"
  }
}

GenerateImage 要求欄位

欄位 說明 資料類型
eventId 要要求相關攝影機圖片的事件 ID。 string
範例：「iYTZwoT3K-OgtqzhF_KTC5dhEb...」

GenerateImage 回應欄位

欄位 說明 資料類型
url 可從中下載攝影機圖片的網址。 string
範例：「https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...」
token 下載圖片時，要在 HTTP 授權標頭中使用的權杖。 string
範例：「g.0.eventToken」

下載攝影機影像

使用 HTTP 授權標頭中的 token (採用基本授權)，對 GenerateImage 指令回應中的 url 進行 GET 呼叫，即可下載攝影機圖片：

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...

使用 width 或 height 查詢參數，自訂下載圖片的解析度。您只需要指定其中一個參數。另一個參數會根據攝影機的長寬比自動縮放。

舉例來說，如果攝影機的長寬比為 4:3，如要下載解析度為 480 x 360 的攝影機影像，請指定寬度或高度：

寬度

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?width=480

高度

curl -H "Authorization: Basic g.0.eventToken" \
      https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?height=360

下載網址的其他限制如下：

  • 如果網址中同時提供這兩個參數，系統會使用 width 並忽略 height。
  • 如果網址中未提供任一參數，系統會為 width 選擇預設值 480。

如要瞭解圖片屬性，請參閱 CameraImage 特徵。

錯誤

系統可能會傳回下列與這項特徵相關的錯誤代碼：

錯誤訊息 單次點擊收益 疑難排解
攝影機影像已無法下載。 DEADLINE_EXCEEDED 活動圖片會在活動發布後 30 秒過期。請務必在期限前下載圖片。
事件 ID 不屬於攝影機。 FAILED_PRECONDITION 使用相機事件傳回的正確 eventID。

如需完整的 API 錯誤代碼清單，請參閱 API 錯誤代碼參考資料。