對話動作將於 2023 年 6 月 13 日淘汰。詳情請參閱對話動作停用

OAuth 型「Google 登入」的「簡化」連結概念指南

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

以 OAuth 為基礎的 Google 登入「精簡」連結類型可在 OAuth 帳戶連結之外加上 Google 登入。如果您在動作中使用此連結類型,則流程會從 Google 登入開始,讓您檢查使用者的 Google 設定檔資訊是否存在於系統中。如果沒有,系統就會啟動標準 OAuth 流程。只要提供這兩種連結類型,您的使用者就能在 Google 操作中使用自己的身分,並將這些身分連結至 Google 或非 Google 帳戶。使用者也可以選擇使用 Google 個人資料資訊建立新帳戶。

如果發生下列任一情況,建議您採用帳戶連結方式:

  • 您的操作範圍橫跨多個平台 (例如,如果您的動作支援 Android 應用程式)。
  • 您有一個現有的驗證系統,並想讓使用者將自己的身分連結到非 Google 帳戶。舉例來說,如果您提供會員方案,且想確保使用者不會失去現有帳戶累積的點數。

如要確認「簡化連結」是最合適的解決方案,請參閱選擇帳戶連結類型頁面。

重要詞彙

在瞭解簡化連結的運作方式之前,請先熟悉以下字詞:

  • Google ID 憑證:經過簽署的宣告,含有使用者的 Google 基本個人資訊 (姓名、電子郵件地址和個人資料相片)。Google ID 憑證為 JSON Web Token (JWT)。以下是已解碼的權杖範例:
{
  "sub": 1234567890,        // The unique ID of the user's Google Account
  "iss": "https://accounts.google.com",        // The token's issuer
  "aud": "123-abc.apps.googleusercontent.com", // Client ID assigned to your Actions project
  "iat": 233366400,         // Unix timestamp of the token's creation time
  "exp": 233370000,         // Unix timestamp of the token's expiration time
  "name": "Jan Jansen",
  "given_name": "Jan",
  "family_name": "Jansen",
  "email": "jan@gmail.com", // If present, the user's email address
  "locale": "en_US"
}
  • user.verificationStatus由系統設定的屬性,表示目前工作階段是否有已驗證的使用者。

  • user.accountLinkingStatus系統設定的屬性,表示目前工作階段中的使用者是否有已連結的身分。

  • 帳戶連結系統場景:這個預先定義的場景會導入帳戶連結確認流程,並且可針對特定用途加以自訂。

  • 授權碼流程:您可以使用簡化連結導入的 OAuth 2.0 流程。此流程需要兩個端點:

    • 授權端點:這個端點會向尚未登入的使用者顯示登入使用者介面。它會以短期的授權碼的形式,記錄要求存取的要求。
    • 權杖交換端點:這個端點負責處理兩種類型的廣告交易平台:
      1. 將長期更新憑證與短期存取權杖交換授權碼。使用者完成帳戶連結流程後,系統就會執行這項交換作業。
      2. 將長期更新憑證交換成短期存取權杖。當 Google 需要新的存取權杖已過期時,這個交換作業就會發生。
  • 隱式程式碼流程:可透過簡化連結導入的 OAuth 2.0 流程。此流程只需要授權端點。在這個流程中,Google 會在使用者的瀏覽器中開啟您的授權端點。如果登入成功,系統會將長效存取權杖傳回 Google。現在,從 Google 助理傳送至動作的所有要求中,都會包含這個存取權杖。

  • 存取憑證:授權讓服務存取使用者資料的某個部分。存取憑證會與個別使用者建立關聯。

  • 重新整理權杖:短期存取權杖過期後,此憑證會用於新的存取權杖。

必要條件

如要使用簡化連結類型,您必須符合以下條件:

  • OAuth 2.0 伺服器
  • 權杖交換端點

    憑證交換端點必須擴充,才能新增 Google 通訊協定,以支援透過 ID 憑證自動建立連結和建立帳戶 (例如,向這個端點發出的要求中加入 intent=getintent=create 參數)。

運作方式

本節將說明簡化連結的一般流程。 下一節「簡化連結流程」將說明 (a) 如何透過語音啟用或停用帳戶,以及 b) 是否使用隱含或授權程式碼流程,產生各種不同的資料流。

基本流程如下:

  1. 你的動作會要求使用者提供 Google 個人資料的同意。
  2. 使用者提供同意聲明後,您的動作會收到包含使用者 Google 個人資料資訊的 Google ID 憑證。
  3. 您必須驗證並解碼憑證,才能讀取設定檔內容。
  4. 您的操作會使用這個憑證來檢查系統中是否存在使用者的 Google 個人資料資訊。
    1. 如果是的話,使用者已經使用自己的 Google 帳戶登入您的系統,且 Google 助理已將使用者的身分與自己的 Google 帳戶連結。使用者可以繼續與帳戶連結 Google 助理的對話。
    2. 如未連結,請參閱步驟 5。
  5. 使用者可以 a) 使用其 Google 個人資訊來建立新帳戶,或 b) 使用其他帳戶登入您的系統。視您透過語音啟用或停用帳戶建立功能而定,系統顯示的選項會有所不同。如果使用者選擇使用其他帳戶登入系統,標準 OAuth 流程就會開始執行。
  6. 使用者建立新帳戶或使用其他服務供應商登入之後,您的服務就會將存取權杖傳回 Google。(如果您使用的是授權碼流程,您的服務也會傳回重新整理權杖。)
  7. 使用者現在可以連結自己的帳戶與 Google 助理對話。

簡化的連結流程

本節將說明簡化連結可能產生的各種流程。 這些圖表涵蓋使用授權碼流程 (而非隱含程式碼流程) 產生的流程,並假設您使用的是 Actions Builder。

每個流程皆包含使用者叫用動作後的一般步驟:

在上述流程中,您將轉換為帳戶連結系統場景,並提供自訂原因。這個情境會要求使用者授予 Google 個人資訊的存取權。使用者表示同意後,Google 助理會傳送包含 user@gmail.com 設定檔資訊的要求。

在這個時間點之後,資料流會有所不同,取決於您是否透過語音設定帳戶連結,以及使用者資訊中是否已有使用者的資訊。以下各節將說明這些流程。

已啟用語音帳戶建立流程

本節詳細說明如果您透過語音功能建立帳戶,可能會發生帳戶連結流程。

流程 1:使用者資訊存在於您的系統中

此時,user@gmail.com 代表的使用者在您的後端中,所以您的權杖交換端點就會為使用者傳回一個憑證。動作中的使用者身分現在已連結至其 Google 帳戶使用者的原始要求 (「訂購我常態」) 會與使用者意圖相符 order_drink. 然後 Webhook 會處理相符意圖的出貨情形,並向資料庫查詢 user@gmail.com 的正常順序。使用者就能繼續與 Google 助理對話。

流程 2:使用者資訊不存在,且使用者建立帳戶

由於您啟用透過語音建立帳戶的方式,而且後端沒有 user@gmail.com,因此 Google 助理會詢問使用者是否想要執行下列任一操作:

a) 使用語音的 Google 個人資料來建立新帳戶,並利用語音完成這項操作

b) 以其他帳戶登入系統

在此情況下,使用者選擇透過語音建立新帳戶。Google 會呼叫您服務的權杖交換端點,然後要求建立帳戶。此要求包含 Google ID 憑證,其中包含建立新帳戶所需的元件。然後,您可以使用這個憑證資訊 (使用者名稱和電子郵件地址) 來為使用者建立帳戶。

建立帳戶之後,您的服務會傳回存取權杖,並為新建的帳戶重新整理憑證。動作中的使用者身分現在已連結至 他們的 Google 帳戶使用者的原始要求 (「訂購我常態」) 會比對使用者意圖 order_drink. 然後,您的 Webhook 會處理相符意圖的執行要求,並查詢資料庫是否執行 user@gmail.com 的一般順序,因為使用者是新的,所以還不存在。接著,您的動作就可以向使用者詢問想要訂購的商品。

流程 3:使用者資訊不存在,且使用者以不同的帳戶登入

您已啟用語音建立功能,因此 Google 助理會詢問使用者是否要執行下列任一操作:

a) 使用語音的 Google 個人資料來建立新帳戶,並利用語音完成這項操作

b) 以其他帳戶登入系統

在這種情況下,使用者選擇以其他帳戶登入,可啟動標準 OAuth 流程。如果流程是以語音裝置啟動,Google 會將執行作業轉移到手機。接著,Google 會在使用者的瀏覽器中開啟您的授權端點,並且視您的設定而定,例如:a) 使用現有帳戶 (非使用 Google 登入) 登入服務;或者 b) 使用其他供應商的帳戶建立新帳戶。如要進一步瞭解 OAuth 流程,請參閱 OAuth 連結概念指南

驗證使用者的憑證之後,您的服務就會將存取憑證和更新權杖傳回 Google。動作中的使用者身分現在已連結至非 Google 帳戶使用者的原始要求 (「訂購我的常態」) 會與使用者意圖相符 order_drink. 然後,Webhook 會處理相符意圖的執行要求,並查詢資料庫中 user@gmail.com 的正常順序,因為使用者是新的,所以還不存在。接著,您的操作會詢問使用者想訂購的商品,或是要求使用者設定平常的訂單。

停用語音帳戶建立流程

本節說明停用透過語音建立帳戶停用功能時的帳戶連結流程。

流程 4:使用者的資訊不存在

您未透過語音啟用帳戶建立功能,但使用者不存在於您的後端,因此會啟動標準 OAuth 流程。「Google 助理」會在使用者的瀏覽器中開啟授權端點 (如果流程是在僅限語音的裝置上啟動,Google 會將執行作業轉移到有螢幕的裝置)。使用者可以選擇 (a) 使用其他供應商登入 (如果已透過其他帳戶註冊您的服務),或是 b) 使用其他供應商建立新帳戶。如要進一步瞭解 OAuth 流程,請參閱 OAuth 連結概念指南

驗證使用者的憑證之後,您的服務就會將存取憑證和更新權杖傳回 Google。動作中的使用者身分現在已連結至非 Google 帳戶使用者的原始要求 (「訂購我的常態」) 會與使用者意圖相符 order_drink. 然後,Webhook 會處理相符意圖的執行要求,並查詢資料庫中 user@gmail.com 的正常順序,因為使用者是新的,所以還不存在。這樣一來,您的動作就能要求使用者設定正常順序。