自定义意图

每个应用都不同，并非所有应用功能都与可用的应用操作内置意图 (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）中，将查询模式指定为字符串数组中的项目。当您的应用操作被调用时，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。在这种情况下，“set appointment today at noon”和“set an appointment today at noon”都是有效的查询。