自訂意圖

每個應用程式都有不同之處，也並非所有應用程式功能都有相符的應用程式動作內建意圖可供使用。如果沒有所有內建意圖 (BII) 都不適合應用程式功能使用，您可以改為使用自訂意圖，以便用應用程式動作擴充應用程式。

自訂意圖和 BII 相同，也會遵守 shortcuts.xml 結構定義，扮演著 Google 助理和定義執行要求之間的連接點。自訂意圖裡也有意圖參數，您可以把這些參數對應到對應執行要求裡的參數。

自訂意圖和 BII 不同，必須使用查詢模式說明使用者可能會提出的查訊範例。這個方法和內建意圖不同，每個內建意圖都會為使用者經常表達意圖的方式建立模型。

限制

自訂意圖具有以下幾種限制：

自訂意圖的名稱不得以 actions.intent 開頭。
在應用程式內，每個自訂意圖的名稱都必須是專用的，不可重複。
Google 助理只能擷取特定資料類型的參數。支援類型清單請見「支援的類型」。
每項查詢最多僅能支援兩個文字參數。其他資料類型無這項限制。
自訂意圖僅支援 en-US 語言代碼 (裝置和 Google 助理必須使用相同的語言設定)。

支援的類型

擷取參數時，自訂意圖支援以下 schema.org 類型：

https://schema.org/Text
https://schema.org/Date
https://schema.org/Time
https://schema.org/Number

使用自訂意圖定義應用程式動作

和其他使用內建意圖的應用程式動作相同，您需在 shortcuts.xml 的 <capability> 元素中定義自訂意圖。

功能定義於 <shortcuts> 根元素內。定義 <shortcuts> 元素時，您必須提供欲存取的屬性的命名空間。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  ...
</shortcuts>

在 android:name 屬性內提供自訂意圖名稱，並在 queryPatterns 屬性內參照查詢模式資源檔案。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.EXAMPLE_INTENT"
      app:queryPatterns="@array/ExampleQueries">
    <intent ...>
      <url-template
          android:value="http://custom.com{?number_of_items,item_name}" />
      <parameter
          android:name="number_of_items"
          android:key="number_of_items"
          android:mimeType="https://schema.org/Number" />
      <parameter
          android:name="item_name"
          android:key="item_name"
          android:mimeType="https://schema.org/Text" />
    </intent>
  </capability>
  ...
</shortcuts>

命名自訂意圖時，建議使用 custom.actions.intent 的字首，以便區分自訂意圖和內建意圖及 Android 意圖 (這些意圖有不同的功能)。自訂意圖名稱不得以 actions.intent 開頭，因為系統保留這個命名空間給內建意圖使用。

按照最符合每個參數意義的敘述，提供支援的 schema.org 類型。舉例來說，您可以用 https://schema.org/Date 說明您預期收到的日期：

...
<intent>
  <url-template android:value="https://example.com/appt{?apptType,date,time}" />
  <parameter
      android:name="date"
      android:key="date"
      android:mimeType="https://schema.org/Date" />
  ...
</intent>
...

shortcuts.xml 內的捷徑定義無論自訂意圖或內建意圖都使用相同的格式。以下程式碼描述的應用程式動作會為 apptType 參數參照查詢模式觸發 SCHEDULE_APPOINTMENT 自訂意圖與一組定義過的值、DRIVERS_LICENSE 及 VEHICLE_REGISTRATION。

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
      <url-template android:value="https://example.com/appt{?apptType,date,time}" />
      <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
      <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
      <!-- The following parameter has no type because the shortcuts are bound to it -->
      <parameter android:name="apptType" android:key="apptType" />
    </intent>
    ...

<shortcuts
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
  <capability
      android:name="custom.actions.intent.SCHEDULE_APPOINTMENT"
      app:queryPatterns="@array/scheduleApptQueries">
    <intent ...>
     <url-template android:value="https://example.com/appt{?apptType,date,time}" />
       <parameter
          android:name="date"
          android:key="date"
          android:mimeType="https://schema.org/Date" />
       <parameter
          android:name="time"
          android:key="time"
          android:mimeType="https://schema.org/Time" />
       <!-- The following parameter has no type because the shortcuts are bound to it -->
       <parameter android:name="apptType" android:key="apptType" />
    </intent>
  </capability>

  <shortcut
      android:shortcutShortLabel="Driver's License"
      android:shortcutId="DRIVERS_LICENSE">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/driversLicense" />
    </capability-binding>
  </shortcut>

  <shortcut
      android:shortcutsShortLabel="Vehicle Registration"
      android:shortcutId="VEHICLE_REGISTRATION">
    <capability-binding android:key="custom.actions.intent.SCHEDULE_APPOINTMENT">
      <parameter-binding
          android:key="apptType"
          android:value="@string/vehicleRegistration" />
    </capability-binding>
  </shortcut>
</shortcuts>

您可以使用內嵌清查設定自訂意圖的參數，使用清查將擷取的實體導入 shortcuts.xml 指定的多個支援實體。

查詢模式

您使用的每個自訂意圖，都需要提供多個您預期使用者會為該意圖所查詢的內容。這和內建意圖使用的方式不同，內建意圖已經按照使用者經常表達的作業進行方式或需要的資訊建立模型。

在 Android 資源檔案 (通常是 /res/values/strings.xml) 中，使用字串陣列項目的方式指定查詢模式。當系統叫用應用程式動作時，Google 助理會在比對使用者的執行要求意圖時，按照您的查詢模式檢查使用者的查詢內容。您提供的每項查詢模式都代表了您認為適用於對應自訂意圖的句子。

為自訂意圖提供查詢模式時，請預期每項模式都會遵守明確叫用方式，例如「開啟範例應用程式」或「啟動範例應用程式然後」。舉例來說，請考慮使用以下使用者查詢內容：

「Ok Google，開啟範例遊戲應用程式，然後開始做蛋糕。」
「Ok Google，開啟範例遊戲應用程式然後開始做蘋果派。」
「Ok Google，啟動範例遊戲應用程式然後製作 5 個蛋糕項目。」
「Ok Google，使用範例遊戲應用程式產生蛋糕 5 次。」

請在叫用詞組後方提供含有查詢部分內容的查詢模式，以便符合使用者的查詢內容。針對您想從查詢中擷取的資訊 (如使用者提供的文字或數字)，您需要在查詢模式中將值指派給對應的意圖參數及預留位置。

若要在查詢模式內參照參數，請在模式內的參數名稱中加入 $。舉例來說，如果想為參數建立預留位置值，如 <parameter name="date1" ... (actions.xml) 或 <parameter android:name="date1" ... (shortcuts.xml)，您需要使用 $date1。

以下程式碼描述的查詢模式會比對上述的使用者查詢，並擷取項目名稱值，及需要製作的項目數量：

<resources>
  <string-array name="ExampleQueries">
    <item>start making a $text1</item>
    <item>start making an $text1</item>
    <item>craft $number1 $text1 items</item>
    <item>produce $text1 $number1 times</item>
  </string-array>
</resources>

查詢模式支援條件式。如：「set (an)? appointment $date $time」。此時，「set appointment today at noon」和「set an appointment today at noon」都是有效的查詢內容。