此页面由 Cloud Translation API 翻译。

自定义 intent

每个应用都是不同的，且并非所有应用功能都与可用的与应用有关的 Action 内置 intent (BII) 匹配。如果没有适合您的应用功能的 BII，您可以改用自定义 intent 来通过与应用有关的 Action 扩展应用。

与 BII 一样，自定义 intent 遵循 shortcuts.xml 架构，并充当 Google 助理和您定义的执行方式之间的连接点。自定义 intent 也有 intent 参数，您可以将这些参数映射到相应执行方式中的参数。

与 BII 不同，自定义 intent 需要查询句式，以便描述用户可能会说出的示例查询。此方法与内置 intent 不同，内置 intent 会对用户表达相应 intent 的常用方式进行建模。

限制

自定义 intent 具有以下限制：

自定义 intent 的名称不能以 actions.intent 开头。
一个应用的各个自定义 intent 的名称不得相同。
Google 助理只能提取特定数据类型的参数（请参阅支持的类型）。
自定义 intent 必须包含可用查询句式的示例（请参阅查询句式）。
每个查询最多支持两个文本参数。此限制不适用于其他数据类型。
自定义 intent 仅支持 en-US 语言区域。此外，设备语言设置和 Google 助理语言设置必须匹配。

支持的类型

自定义 intent 支持提取以下 schema.org 类型的参数：

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

使用自定义 intent 定义与应用有关的 Action

与其他使用 BII 的与应用有关的 Action 一样，您可以在 shortcuts.xml 内的 <capability> 元素中定义自定义 intent。

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 属性中提供自定义 intent 的名称，并在 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>

自定义 intent 的名称不能以 actions.intent 开头，因为该命名空间是为 BII 预留的。相反，在为自定义 intent 命名时，请使用前缀 custom.actions.intent 来区分自定义 intent 与 BII 和 Android 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 中，为自定义 intent 定义快捷方式的格式与为 BII 定义快捷方式的格式相同。

以下代码描述了一个与应用有关的 Action，该 Action 使用引用的查询句式来触发 SCHEDULE_APPOINTMENT 自定义 intent，并为 apptType 参数使用了一组已定义值，即 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>
  </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>

您可以使用内嵌目录配置自定义 intent 参数，用于将 entity 提取引导到 shortcuts.xml 中指定的一组受支持 entity。

查询格式

您使用的每个自定义 intent 都需要具有用户预期会对该 intent 执行的一组查询。这种方法与 BII 不同，内置 intent 已经根据用户表达他们想要执行的任务或查找的信息的常用方式对查询进行建模。

在 Android 资源文件（通常是 /res/values/strings.xml）中，将查询格式指定为字符串数组中的项。调用与应用有关的 Action 时，Google 助理在为执行方式匹配用户 intent 的过程中，会针对您的查询格式检查用户查询。您提供的每个查询格式都代表一个您认为对相应自定义 intent 有效的短语。

在为自定义 intent 提供查询格式时，应要求每种格式遵循显式调用，例如“open Example App and”或“start Example App and”。例如，请考虑以下用户查询：

“Hey Google, open Example Game App and start making a cake.”
“Hey Google, open Example Game App and start making an apple pie.”
“Hey Google, start Example Game App and craft 5 cake items.”
“Hey Google, use Example Game App to produce cake 5 times.”

如需匹配用户查询，请提供包含调用短语之后的查询部分的查询格式。对于要从查询中提取的信息（如用户提供的文本或数字），可以通过查询格式中的占位符为相应的 intent 参数分配值。

如需在查询句式中引用参数，请在句式的参数名称中添加 $。例如，若要为参数创建占位值（例如 <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”都是有效的查询。