一般
問:我們應該在哪些位置執行 Actions on Google 執行基礎架構?應該使用哪種語言?
答:只要它支援新型安全資料傳輸層 (SSL) 和 OAuth 2.0,您就可以自由選擇任何平台和任何語言實作基礎架構。建議您盡可能靠近基礎架構的其他部分,以提高可靠性並縮短實際執行使用者裝置的延遲時間。
問:裝置 ID 可以重複嗎?
答:ID 不得重複。如果您的服務沒有專屬 ID,則這些 ID 必須至少與每位使用者層級重複。舉例來說,如果使用者擁有多個住家,而其中兩處住家對同一位使用者整合,要求你打開一棟房子的燈具時,不應在其他房子裡使用相同 ID 的燈具打開。
問:裝置名稱可以重複嗎?
答:名稱可以重複。不過,我們可能會在一段時間後改善名稱不當命名方式,讓使用者享有更優質的體驗。
以下是一些簡單的命名指南:
- 名稱應該要能實際唸出。
- 系統可以識別字串子集,因此如果您有「ACME 彩色燈」,系統也會回答「acme 光」。
- 建議使用產品的描述性名稱,以及一或多個使用者定義的名稱。
- 使用者不必提供燈具名稱,因為我們有不同的房間;每個房間都要有不重複的名稱,但可以一律使用複數來指令所有東西。例如,辦公室的兩個燈泡為「北燈」和「東燈」,但可以只用「燈具」執行指令。
問:裝置狀態多久更新一次?
答:當使用者執行「查詢」或「執行」指令時,系統就會擷取臨時狀態。如果使用者詢問「燈開著嗎?」,或想要調亮燈光,我們就必須查詢來瞭解目前狀態。
問:是否能依據裝置的目前狀態直接更新 Home 圖譜?
答:可以,請使用 Report State API 呼叫。
帳戶連結和 OAuth
問:我需要進行帳戶連結嗎?
答:是的,您必須連結帳戶,才能將使用者的裝置連結至供應商的雲端服務。
問:針對 OAuth,存取權杖每 15.213 小時就會到期,這樣嗎?
答:可以,但也請試著稍微的到期時間,例如 10 到 20 分鐘。OAuth 用戶端應視需要更新權杖,而使用較短的到期時間進行測試即可證明運作正常。
意圖
問:同步處理會在何時進行?
答:同步處理會在 OAuth 完成,以及發出 Request Sync 呼叫之後立即執行。
問:為什麼 SYNC
無法正常運作?
答:同步處理失敗的一些常見原因包括。
您傳送的裝置類型有誤。
- 舉例來說,我們預期的是
action.devices.types.LIGHT
,但您傳送的是action.devices.types.Light
。
- 舉例來說,我們預期的是
系統不支援你傳送的裝置類型,
- 舉例來說,您傳送
action.devices.types.FLASHLIGHT
,但我們不支援這個問題。
- 舉例來說,您傳送
您傳送的欄位無效/不支援,
- 例如版本欄位或其他欄位不在我們的規格中。
您的 SYNC 回應還有其他格式問題。
- 請檢查括號!
帳戶連結發生問題。
- 請確認您在 SYNC 要求的驗證標頭中收到有效的存取權杖。
您回應 SYNC 要求的時間過長。
- 請確認您在 5 秒內回應 SYNC 要求。
問:可以使用「待處理」回覆嗎?
答:如果您的裝置具有即時功能,強烈建議您使用成功/失敗回應,而非待處理回應。我們瞭解有些低耗電的非即時裝置可能需要有待處理回應和非同步執行模型,如果您覺得需要「待處理」回應,請與我們聯絡。
測試與提交
問:我可以建立執行環境嗎?
答:可以,請另外建立專案,並完成該專案的所有設定。您可以視需要建立不限數量的專案,以對應至開發程序和基礎架構。
問:需要多久更新專案草稿?
答:專案草稿需要每 3 天更新一次。3 天後,測試代理程式會從行動裝置-HomeControl 設定中消失。如果您遇到這種情況,請在 Actions on Google Console 中,按一下專案的「測試草稿」按鈕。
問:我可以同時測試多部裝置嗎?
答: Actions on Google 一次只能支援一個「裝置端」AP。如果您先在「ap1」上使用測試草稿並同步處理裝置,那麼在未取消連結 ap1 的情況下,請直接執行 TEST 草稿「ap2」,「ap1」就會從 mobile-HomeControl-settings 中消失。如要修正這個問題,請再次在「ap1」執行 TEST DRAFT,然後您可以在設定中取消連結「ap1」。
請注意,使用者的所有 Google Assistant 裝置都能使用這個單一動作套件,例如,您可以在聲控喇叭和 Android 上測試新的硬體整合。
問:我提交的動作專案因名稱或發音而遭拒,我需要變更哪個部分?
答:我們會檢查名稱發音,確保發音日後不會因為其他動作使用,而且發音與顯示名稱相符 (避免因不相符而影響未來的名稱註冊)。
如要繼續使用相同名稱,請聯絡支援團隊,將語音團隊新增至 Assistant。
問:Google Home 應用程式的「居家控制系統」部分沒有顯示我的動作,為什麼會這樣?
答:可能的原因如下:
- 您並未在 Actions Console 中針對專案點選「TEST DRAFT」按鈕。
- 在裝置測試中,你一次只能測試一項動作。
- 在 Actions Console 中,前往「Actions」專案的「 Simulator」分頁,然後將「啟用/未使用」切換按鈕設為「已停用」,然後再次啟用。
- 如果這是與您共用的動作,請確認已遵循所有分享操作說明。
- 裝置測試將於三天後到期。按一下 Actions Console 中的專案「TEST DRAFT」按鈕。
問:為什麼在模擬器中輸入「和<my agent name>
」交談時會出現錯誤訊息?
答:智慧住宅動作不會用到叫用名稱。如要在模擬器中測試,您必須在已安裝 Google Home app (GHA) 的 Android 或 iOS 手機上透過帳戶連結執行。在執行帳戶連結之前,您也必須擁有與您的帳戶相關聯的裝置。
問:為什麼我嘗試使用模擬器時收到錯誤訊息?
答:您無法使用模擬器來測試已部署的 smart home Actions。如要針對實際工作環境中的家用裝置自動化專案使用模擬工具,您必須建立新專案以便進行測試。
報表狀態
問:導入報表狀態時是否需要先決條件?
答:專案需要使用 Smart Home API,支援 OAuth2,而且必須具備具有待回報狀態的特徵。
問:我們需要多久回報一次裝置狀態?
答:Google 想確認轉換和終端狀態,但如果在短時間內有許多狀態變更 (例如使用者在短時間內開啟並關閉冰箱三次或調暗冰箱),我們只需要回報的最終狀態即可。
問:進行「報告狀態」呼叫時,是否需要傳送完整裝置狀態?
答:系統不支援部分狀態更新,因此 Report State 呼叫應一律包含已更新特定特徵的所有資料。如果兩項特徵會產生不一致,則應一併回報。
問:Google 可以查詢我的裝置並取得狀態 (也就是輪詢裝置) 嗎?
答:我們不建議採用這個備用機制。如果我們需要經常為這些使用者重新輪詢裝置,我們無法保證會產生多少額外負載。而這些需求源自於全新的視覺介面。除了未知的載入問題之外,也會降低使用者體驗。我們認為 Report State 對平台來說至關重要。
問:目前支援「報告狀態」功能的哪些特性?
答:系統支援所有具有相關州別的公共特徵。此外,我們也應回報裝置線上狀態的任何變更。
請注意,場景沒有狀態。但是,這些元件可能會發生裝置狀態變更。如果 Google Home Graph 中的任何裝置處於變更狀態,就必須回報這個狀態。
問:是否需要傳送時間戳記?
答:我們不需要時間戳記;上次傳送的狀態將覆寫先前的呼叫。
問:如果我已在「查詢」和/或「執行」中傳送狀態,是否必須另外回報狀態?
答: Home Graph 只會儲存透過 Report State 傳送的狀態。傳回為 EXECUTE 和 QUERY 意圖的回應狀態,只會用於向使用者顯示的語音回應,不會儲存。因此,即使已經傳回裝置的新狀態做為 EXECUTE 或 QUERY 意圖的回應,仍應呼叫 Report State。
問:如果未在指定期限內完全導入「報表狀態」功能,會有什麼後果?
答:這會導致使用者體驗不佳,例如在 GHA 和視覺介面中出現。這意味著許多 QUERY 意圖將會傳送至各狀態的輪詢,而且我們無法保證這會對應合作夥伴雲端上的額外負載。
問:如何測試報表狀態導入作業?
答:使用 Home Graph 檢視器這項自助式測試工具,會顯示儲存在 Home Graph 中的目前裝置狀態。
問:是否可以針對報表狀態使用隨機 requestId?
答:如果 Report State 是由 EXECUTE 要求所觸發,我們建議合作夥伴使用透過 EXECUTE 要求收到的相同 requestId,否則您只能使用隨機 requestId。
問:如果使用者有多部裝置,其中一部裝置的狀態改變,我們必須回報所有裝置的最新狀態嗎?
答:不行,你只要回報特定裝置的狀態即可。
最佳做法
問:合理的延遲時間範圍是?
答:200 毫秒以內最為理想,介於 2 到 5 秒之間。如果您的延遲時間超過 5 秒,請與我們聯絡。
問:要如何讓聲控揚聲器在離線狀態下正確回應?
答:將離線裝置退回離線狀態。對於這項錯誤,我們會傳回「目前無法提供」的 TTS。詳情請參閱錯誤和例外狀況。