門鈴 (舊版)

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只要裝置支援人物偵測事件，就會具備這項特徵。Person
CameraSound這項特徵屬於支援聲響偵測事件的任何裝置。音效
DoorbellChime凡是支援門鈴鈴聲和相關按鈕事件的裝置，都屬於這項特徵。鈴聲
資訊這個特徵屬於任何裝置，可提供裝置相關資訊。

JSON

如果 GET 回應中沒有某項特徵，表示該特徵或功能目前不適用於裝置。詳情請參閱裝置類型。

{
  "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 特徵的動作事件 攝影機偵測到動作。
活動 攝影機人員特徵的人員事件 攝影機偵測到有人。
活動 CameraSound 特徵的聲音事件 攝影機偵測到聲響。
活動 DoorbellChime 特徵的 Chime 事件 有人按了門鈴。
舉例來說，以下是按下門鈴按鈕的畫面：

酬載

{
  "eventId" : "98b859b4-6e53-41d9-bb07-13ae3c41f322",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.DoorbellChime.Chime" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "mVddCT2dHIL0atQLRlmvei3ota..."
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}
這項事件的酬載包含 eventId，可用於 GenerateImage 指令。這項指令會傳回與事件相關的攝影機圖片下載網址：

要求

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

回應

{
  "results" : {
    "url" : "https://domain/sdm_event_snapshot/dGNUlTU2CjY5Y3VKaTZwR3o4Y1...",
    "token" : "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 特徵。

存取直播

可以存取攝影機的即時串流影像。這部裝置支援下列串流格式：

  • RTSP

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

如要存取即時串流，請使用CameraLiveStream特徵的適當 GenerateFormatStream 指令。

RTSP

如果是 RTSP 串流，CameraLiveStream 特徵指令的 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 分鐘。如要延長直播的生命週期，請針對產生的串流格式，使用 CameraLiveStream 特徵的適當 ExtendFormatStream 指令。

RTSP

如要延長 RTSP 串流，請使用 CameraLiveStream 特徵指令的 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特徵的適當 StopFormatStream 指令。

RTSP

如要停止 RTSP 串流，請使用權杖，透過 CameraLiveStream 特徵指令的 StopRtspStream 指令將權杖設為無效：

要求

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

回應

{}

錯誤

與這部裝置相關的錯誤代碼可能如下：

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

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