門鈴 (舊版)

Nest Hello

Smart Device Management (SDM) API 支援所有舊版 Nest Doorbell。 此裝置會傳回 DOORBELL 的裝置類型：

sdm.devices.types.DOORBELL

Google Nest Doorbell (舊版) 配備攝影機，功能與 CAMERA 裝置類型相同。

性狀

參考資料

下列與這部裝置相關的特徵、指令或事件：

特徵說明指令活動
CameraEventImage該特徵隸屬於支援透過事件產生圖片的任何裝置。GenerateImage
CameraImage此特徵屬於任何支援拍照的裝置。
CameraLiveStream這項特性屬於任何支援直播功能的裝置。GenerateRtspStream
ExtendRtspStream
StopRtspStream
CameraMotion該特徵屬於支援動作偵測事件的任何裝置。動態
CameraPerson該特徵屬於支援人員偵測事件的任何裝置。使用者
CameraSound這項特徵屬於支援聲響偵測事件的任何裝置。音效
DoorbellChime這項特徵屬於任何支援門鈴鈴聲及相關媒體事件的裝置。管鐘
資訊這項特徵隸屬於任何裝置，

JSON

如果 GET 回應中沒有特徵，表示裝置目前不支援該 trait。詳情請參閱「裝置類型」一節。

{
  "type" : "sdm.devices.types.DOORBELL",
  "traits" : {
    "sdm.devices.traits.CameraEventImage" : {},
    "sdm.devices.traits.CameraImage" : {
      "maxImageResolution" : {
        "width" : 1280,
        "height" : 960
      }
    },
    "sdm.devices.traits.CameraLiveStream" : {
      "maxVideoResolution" : {
        "width" : 640,
        "height" : 480
      },
      "videoCodecs" : ["H264"],
      "audioCodecs" : ["AAC"],
      "supportedProtocols" : ["WEB_RTC"]
    },
    "sdm.devices.traits.CameraMotion" : {},
    "sdm.devices.traits.CameraPerson" : {},
    "sdm.devices.traits.CameraSound" : {},
    "sdm.devices.traits.DoorbellChime" : {},
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    }
  }
}

處理門鈴和攝影機事件

DOORBELL 裝置類型可能會觸發下列事件：

類型 元素 說明
活動 CameraMotion trait 的動作事件 相機偵測到動作。
活動 CameraPerson trait 的 Person 事件 攝影機偵測到人影。
活動 CameraSound trait 的音效事件 攝影機偵測到聲響。
活動 Chime 事件的 DoorbellChime 特徵 你已按下門鈴。
舉例來說，以下是按下門鈴按鈕的情況：

酬載

{
  "eventId" : "119bfb86-3c27-4e12-ba3c-b35177badda0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.DoorbellChime.Chime" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "i_MVBkcoLJkn7d6J1GIhbq5M5m..."
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}
此事件的酬載包含可與 GenerateImage 指令搭配使用的 eventId。這個指令會傳回與事件相關的相機圖片下載網址：

要求

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

回應

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

下載相機圖片

使用基本授權的 HTTP Authorization 標頭中的 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 特徵。

觀看直播

你可以透過攝影機存取即時影像串流。此裝置支援下列串流格式：

  • RTSP

如需攝影機和支援的串流格式的完整清單，請參閱「支援的裝置」。

如要存取直播，請使用CameraLiveStream特徵適當的「產生」Format串流指令。

RTSP

針對 RTSP 串流，CameraLiveStream trait 指令的 GenerateRtspStream 指令會傳回串流網址和相關 streamToken：

要求

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.GenerateRtspStream",
  "params" : {}
}

回應

{
  "results" : {
    "streamUrls" : {
      "rtspUrl" : "rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken"
    },
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
    "streamToken" : "g.0.streamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

然後使用串流網址存取攝影機即時影像串流：

rtsps://someurl.com/CjY5Y3VKaTZwR3o4Y19YbTVfMF...?auth=g.0.streamingToken

不同的用戶端無法共用 RTSP 直播網址。串流網址一次只能由一位客戶使用。如果多個用戶端要同時從同一部攝影機直播，則必須為每個用戶端傳送 RTSP 指令，且每個用戶端都必須使用各自的串流網址。

延長直播時間

攝影機即時串流工作階段的有效期限為 5 分鐘。如需延長直播生命週期，請針對你產生的串流格式，使用適當的「延長Format串流」指令。 CameraLiveStream 特徵。

RTSP

如要擴充 RTSP 串流，請使用 CameraLiveStream trait 指令的 ExtendRtspStream 指令，取得新的 streamExtensionToken 和 streamToken 值：

要求

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.ExtendRtspStream",
  "params" : {
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."
  }
}

回應

{
  "results" : {
    "streamExtensionToken" : "dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "streamToken" : "g.0.newStreamingToken",
    "expiresAt" : "2018-01-04T18:30:00.000Z"
  }
}

使用這些新的值更新串流網址，即可繼續查看直播：

rtsps://someurl.com/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...?auth=g.0.newStreamingToken

停止直播

在停止使用攝影機即時影像時，請務必停止錄影，並使串流失效。方法是針對產生的串流格式，使用CameraLiveStream特徵的適當 StopFormat串流指令。

RTSP

如要停止 RTSP 串流，請使用這個權杖搭配 CameraLiveStream trait 指令的 StopRtspStream 指令來失效：

要求

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.CameraLiveStream.StopRtspStream",
  "params" : {
    "streamExtensionToken" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF..."
  }
}

回應

{}

錯誤

下列與這部裝置相關的錯誤代碼可能會傳回：

錯誤訊息 RPC 疑難排解
相機圖片已無法再下載。 DEADLINE_EXCEEDED 活動圖片會在活動發布的 30 秒後失效。請務必在到期前下載映像檔。
事件 ID 不屬於攝影機。 FAILED_PRECONDITION 使用攝影機事件傳回的正確 eventID。

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