自定义 Intent

每款应用都各不相同，并非所有应用功能都能匹配可用的 App Actions 内置 Intent (BII)。对于应用功能没有对应 BII 的情况，您可以使用自定义 Intent 来扩展您的应用并集成 App Actions。

与 BII 一样，自定义 Intent 遵循 shortcuts.xml 架构，并充当 Assistant 与您定义的实现之间的连接点。自定义 Intent 也有 Intent 参数，您可以将其映射到相应实现中的参数。

与 BII 不同的是，自定义 Intent 需要查询模式来描述用户可能说的示例查询。这种方法不同于内置 Intent，后者会建模用户表达该 Intent 的常用方式。

限制

自定义 Intent 有以下限制

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

支持的类型

自定义 Intent 支持以下 schema.org 类型用于参数提取

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

使用自定义 Intent 定义 App Actions

与其他使用 BII 的 App Actions 一样，您可以在 shortcuts.xml 的 <capability> 元素中定义自定义 Intent。

功能定义在 <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 中使用与 BII 快捷方式相同的格式定义自定义 Intent 的快捷方式。

以下代码描述了一个 App Action，它使用引用的查询模式触发 SCHEDULE_APPOINTMENT 自定义 Intent，并使用一组定义的值 DRIVERS_LICENSE 和 VEHICLE_REGISTRATION 作为 apptType 参数。

<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 参数，您可以使用它来引导实体提取到 shortcuts.xml 中指定的一组支持的实体。

查询模式

您使用的每个自定义 Intent 都需要一套用户期望针对该 Intent 发出的查询。这种方法不同于 BII，在 BII 中，查询已经建模为用户表达他们正在尝试执行的任务或寻求的信息的常用方式。

在 Android 资源文件（通常是 /res/values/strings.xml）中，将查询模式指定为字符串数组中的项。当您的 App Action 被调用时，Google Assistant 会对照您的查询模式检查用户查询，以此作为匹配用户 Intent 以进行实现的一部分。您提供的每个查询模式都代表您认为对于相应的自定义 Intent 有效的短语。

为自定义 Intent 提供查询模式时，期望每个模式都遵循明确的调用，例如“打开 Example App 并”或“启动 Example App 并”。例如，考虑以下用户查询

“Hey Google, open Example Game App and start making a cake.”（嘿 Google，打开示例游戏应用并开始制作蛋糕。）
“Hey Google, open Example Game App and start making an apple pie.”（嘿 Google，打开示例游戏应用并开始制作苹果派。）
“Hey Google, start Example Game App and craft 5 cake items.”（嘿 Google，启动示例游戏应用并制作 5 个蛋糕物品。）
“Hey Google, use Example Game App to produce cake 5 times.”（嘿 Google，使用示例游戏应用生产蛋糕 5 次。）

为了匹配用户查询，提供包含调用短语之后查询部分的查询模式。对于您想从查询中提取的信息（例如用户提供的文本或数字），您使用查询模式中的占位符将值分配给相应的 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”都是有效查询。