門鈴 (舊版)

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 回應中缺少特徵,表示該特徵或 功能目前不支援此裝置。詳情請見 更多裝置類型 可能不準確或不適當

{
  "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 特徵的 Motion 事件 攝影機偵測到動作。
活動 CameraPerson 特性的 Person 事件 攝影機偵測到一個人。
活動 CameraSound 特性的 Sound 事件 攝影機偵測到聲響。
活動 Doorbell Doorbell 特徵的管控事件 已按下門鈴。
舉例來說,以下是已按下門鈴按鈕的情況:

酬載

{
  "eventId" : "8cfbc540-68c8-42dd-9bb1-5b71c6ac7fa3",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.DoorbellChime.Chime" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "j1L8rc2B4PesaHP2zcdW6A-AwG..." } } } "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" : "HMy5lGCGEPspcfxKvpmxoiqf2i..."
  }
}

回應

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

下載相機圖片

透過url GenerateImage 指令回應 搭配「基本授權」使用 HTTP 授權標頭中的 token,即可 下載相機影像:

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

使用 widthheight 查詢參數自訂 下載後的圖片。你只需要指定其中一項參數。另一個 參數會根據相機的顯示比例自動調整。

舉例來說,如果相機的顯示比例為 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

下載網址還有其他限制:

  • 如果網址同時提供這兩個參數,系統會使用 widthheight 系統就會忽略。
  • 如未在網址中加入任何參數,系統會為 width

請參閱 CameraImage 特徵 圖片屬性的相關資訊

存取直播

可存取攝影機的即時影像。目前採用的串流格式如下所示 支援的裝置:

  • RTSP

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

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

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 分鐘。如要延長直播的生命週期,請對產生的串流格式使用適當的「延長Format串流指令」 CameraLiveStream 特徵。

RTSP

如要擴充 RTSP 串流,請使用 CameraLiveStream 特徵指令的 ExtendRtspStream 指令則授予以下權限: 取得新的 streamExtensionTokenstreamToken 值:

要求

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

停止直播

每次不再使用攝影機即時監控畫面時,請務必停止直播, 導致串流失效方法是使用適當的停止Format串流 指令 CameraLiveStream 為您產生的串流格式特徵。

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 錯誤代碼的完整清單