對話動作已於 2023 年 6 月 13 日淘汰。詳情請參閱「對話動作已淘汰」。

建構專案

Actions 專案會將所有動作封裝成單一容器。你將這項專案發布到 Actions on Google，讓 Google 助理瞭解如何探索及叫用對話體驗。

動作專案元件
圖 1. 動作專案結構

您可以使用下列低階元件建構 Actions 專案：

  • 「設定和資源」會定義專案中繼資料，以及專案圖示等資源。Google 會使用這些資訊將您的動作發布到 Google 助理目錄，方便使用者探索並叫用這些動作。

  • 意圖代表要執行的任務，例如部分使用者輸入內容或需要處理的系統事件。最常見的意圖類型是使用者意圖。這些意圖可讓您宣告 NLU (自然語言理解) 引擎自然訓練的詞組，以提供更多更多類似詞組。NLU 會使用這些詞組的匯總來訓練 Google 助理用來比對使用者輸入內容的語言模型。在對話期間，如有部分使用者輸入內容與意圖的語言模型相符，Google 助理執行階段會將意圖傳送至您的動作，以便進行處理並回應使用者。

  • 「類型」可讓您從使用者輸入內容擷取結構化資料。透過訓練型註解為類型加上註解，NLU 可以為您擷取相關的結構化資料，因此您無須剖析開放式輸入。

  • 情境程序意圖，是動作的主要邏輯執行者。他們能執行運算單元填補、評估條件邏輯、向使用者傳送提示，甚至呼叫外部網路服務來執行商業邏輯。與意圖搭配使用，場景可讓您有效地偵測特定使用者輸入或系統事件，並執行對應的邏輯。

  • 「提示」會定義您用於回應使用者的靜態或動態回應。

  • Webhook 可讓您將額外工作委派給網路服務 (執行要求)，例如驗證資料或產生提示。您的動作會透過以 JSON 為基礎的 Webhook 通訊協定與執行要求進行通訊。

  • 互動式畫布可讓您使用 HTML、CSS 和 JavaScript 的網頁應用程式建立豐富的沉浸式體驗。

建立專案

您必須先在 Actions 主控台建立專案，才能開發 Google 助理。建立專案的步驟如下：

  1. 前往動作控制台。
  2. 按一下 [新專案]。
  3. 輸入專案名稱，然後按一下「Create Project」(建立專案)。
  4. 在「您想建構什麼動作？」畫面中，選取最符合專案的類別，然後點選「下一步」。
  5. 在「How 如何想要建構」畫面中，選取建構方式，然後按一下「Start Building」(開始建構)。舉例來說，您可以先使用空白專案或範例。

建立本機 Actions SDK 專案

在 Actions 主控台建立動作專案後，您可以在本機開發環境中初始化專案。

如要從現有的動作專案初始化 Actions SDK 專案，請按照下列步驟操作：

  1. 在本機檔案系統中針對 Actions 專案建立空白目錄。
  2. 在這個空白目錄中，建立 sdk 目錄。
  3. 將工作目錄變更為終端機的 sdk 目錄。

從空白專案開始

如要從剛剛在控制台中建立的空白專案開始，請執行 gactions pull --project-id <my-project-id>。

$ mkdir myAction
$ cd myAction
$ mkdir sdk
$ cd sdk
$ gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk

從範例專案開始

如果您要從範例專案開始執行，請執行 gactions init <sample name>。

$ mkdir actions-test
$ cd actions-test
$ mkdir sdk
$ cd sdk
$ gactions init question
Writing sample files for question.
✔ Done. Please checkout the following documentation - https://developers.google.com/assistant/conversational/build on the next steps on how to get started.

定義專案資訊

專案的設定和資源會定義專案相關資訊，例如特徵和途徑支援、支援的語言代碼、顯示名稱、說明、標誌等。下表說明您提供的主要設定和資源。Actions on Google 會利用這些資訊來部署專案並發布至 Google 助理目錄。

姓名 說明
目錄資訊 提供資訊，以便 Actions on Google 將專案發布至 Google 助理目錄。包括專案的中繼資料，以及標誌和橫幅圖片的圖片資源。
指定地區 設定可使用動作的語言代碼。
介面功能 設定可用於執行動作的介面。
公司詳細資料 指定貴公司的聯絡資訊。
公司行號驗證 連結您擁有的網站或 Android 應用程式，即可享有您各種額外功能，例如預留的叫用名稱，以及動作內的網站連結。
發布版本 為「測試」和「正式版」設定不同的測試和正式版。
Google 助理連結 允許使用者從網站資源叫用你的動作。

如何定義專案資訊：

  1. 在 sdk/settings/settings.yaml 中定義動作專案的全域設定。如需支援的值，請參閱設定參考說明文件。

    以下程式碼片段是 sdk/settings/settings.yaml 檔案範例：

    accountLinking:
  enableAccountCreation: true
  linkingType: GOOGLE_SIGN_IN
category: GAMES_AND_TRIVIA
projectId: my-project-id
...

  2. 在 sdk/settings/<locale>/settings.yaml 檔案中，定義會因使用者所在地區 (例如不同語言的叫用詞組) 而有所不同，請將 locale 替換成您的目標語言代碼。

    如需支援的值，請參閱 LocalizedSettings 參考說明文件。

    下列程式碼片段是 sdk/settings/en/settings.yaml 檔案中定義的英文設定範例：

    localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action
  largeBannerImage: https://path/to/large/banner
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action
  smallLogoImage: https://path/to/small/logo
  voice: female_1
...

新增資源

您可以使用動作專案儲存圖片檔、音訊檔案和字串等資源，並透過系統定義的 $resources 變數從設定檔參照資源 (例如提示定義或條件)。

專案資源會儲存在 resources/ 底下，每個資源類型都會指派給目錄中的資料夾。

如要將資源本地化，您可以在資源類型資料夾中建立語言代碼專屬的資料夾，例如，將西班牙文版本的字串儲存在 resources/strings/es/<filename>.yaml 中。

映像檔

圖片檔儲存在 resources/images/ 中，您可以使用 $resources.images.<name of the image file without file extension> 參照這些檔案。允許的副檔名如下：

  • gif
  • png
  • jpg
  • jpeg

舉例來說，如果小型標誌的英文版儲存在 resources/images/en/square.png 中，且大型橫幅的英文版都儲存在 resources/images/en/landscape.jpg 中，則上一個範例中的 sdk/settings/en/settings.yaml 會變為：

localizedSettings:
  developerEmail: developer@developers.com
  developerName: Developer Name
  displayName: My Display Name
  fullDescription: full description of the action

  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: http://path/to/privacy/policy
  sampleInvocations:
  - Talk to My Display Name
  shortDescription: short description of the action

  smallLogoImage: $resources.images.square
  voice: female_1
...

音訊檔案

音訊檔案儲存在 resources/audio/ 中，您可以使用 $resources.audio.<name of the audio file without file extension> 參照這些檔案。

允許的副檔名如下：

  • mp3
  • mpeg

舉例來說，您可以參考提示中的音訊錄音：

candidates:
  - first_simple:
      variants:
        - speech: your speech response
    content:
      media:
        mediaType: audio
        mediaObjects:
          - name: media name
            description: media description
            url: $resources.audio.intro

字串

字串會儲存在 resources/strings/ 中.yaml。每個檔案都含有字串鍵和相關聯的值對應關係，可以是單一字串或字串清單。針對單一字串值，可使用 $resources.strings.<name of the image file without file extension>.<key> 參照值，也可以從清單中取得隨機值，而 $resources.strings.<name of the image file without file extension>.<key>.<numerical index> 則適用於清單中的特定字串值。

例如，使用字串字串進行字串本地化，上一個範例中的 sdk/settings/en/settings.yaml 可能會變成：

localizedSettings:
  developerEmail: developer@developers.com
  developerName: $resources.strings.appinfo.developerName
  displayName: $resources.strings.appinfo.displayName
  fullDescription: $resources.strings.appinfo.fullDescription
  largeBannerImage: $resources.images.landscape
  privacyPolicyUrl: $resources.strings.appinfo.privacyPolicyUrl
  sampleInvocations:
  - $resources.strings.invocations.sample
  shortDescription: $resources.strings.appinfo.shortDescription
  smallLogoImage: $resources.images.square
  voice: female_1
...

在模擬器中測試專案

Actions 主控台會提供模擬器，方便您預覽動作。模擬工具可讓您查看偵錯資訊、設定裝置功能、模擬語言代碼等等。

圖 3. 模擬工具的主要區域：(1) 使用者輸入內容、(2) 裝置檢視畫面、(3) 選項和設定，以及 (4) 對話記錄。

如要測試專案：

  1. 執行 gactions deploy preview 將動作部署至「預覽」，並在模擬器中啟用測試。
  2. 開啟指令輸出中的網址來存取模擬器。
$ gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview