自定义意图

每个应用都不同，并非所有应用功能都与可用的应用操作内置意图 (BII) 匹配。如果您的应用功能没有对应的 BII，您可以使用自定义意图来扩展您的应用并添加应用操作。

与 BII 一样，自定义意图遵循shortcuts.xml 模式，并充当助理和您定义的履行之间的连接点。自定义意图也具有意图参数，您可以将其映射到相应履行中的参数。

与 BII 不同的是，自定义意图需要查询模式来描述用户可能会说的一些示例查询。这种方法不同于内置意图，内置意图对用户表达该意图的常见方式进行建模。

限制

自定义意图具有以下限制：

自定义意图的名称不能以actions.intent开头。
自定义意图的名称在您的应用的自定义意图名称中必须唯一。
Google 助理只能提取某些数据类型（请参阅支持的类型）。
自定义意图必须包含可用查询模式的示例（请参阅查询模式）。
每个查询最多支持两个文本参数。此限制不适用于其他数据类型。
自定义意图仅支持 en-US 语言环境。此外，设备和助理语言设置必须匹配。

支持的类型

自定义意图支持以下用于参数提取的schema.org 类型：

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

使用自定义意图定义应用操作

与使用 BII 的其他应用操作一样，您可以在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>

自定义意图名称不能以actions.intent开头，因为该命名空间保留用于 BII。相反，在命名自定义意图时，请使用前缀custom.actions.intent，以区分自定义意图与 BII 和 Android 意图（功能不同）。

对于每个参数，请提供支持的 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>
...

使用与 BII 快捷方式相同的格式，在shortcuts.xml中为自定义意图定义快捷方式。

以下代码描述了一个使用引用的查询模式来触发SCHEDULE_APPOINTMENT自定义意图的应用操作，并为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>

您可以使用内联清单配置自定义意图参数，您可以使用它将实体提取引导到shortcuts.xml中指定的受支持实体集。

查询模式

您使用的每个自定义意图都需要一组来自用户的预期查询。这与 BII 不同，在 BII 中，查询已经为用户表达他们试图执行的任务或他们寻求的信息的常见方式建模。

在 Android 资源文件（通常为 /res/values/strings.xml）中，将查询模式指定为字符串数组中的项目。当您的 App Action 被调用时，Google 助理会将用户查询与您的查询模式进行检查，以此匹配用户的意图以进行执行。您提供的每个查询模式都代表您认为与相应自定义意图有效的短语。

在为自定义意图提供查询模式时，应预期每个模式都遵循明确的调用，例如“打开示例应用并”或“启动示例应用并”。例如，考虑以下用户查询：

“嘿 Google，打开示例游戏应用并开始制作蛋糕。”
“嘿 Google，打开示例游戏应用并开始制作苹果派。”
“嘿 Google，启动示例游戏应用并制作 5 个蛋糕。”
“嘿 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。在这种情况下，“设置今天的午后约会”和“设置一个今天的午后约会”都是有效的查询。