このページは Cloud Translation API によって翻訳されました。

カスタムインテント

すべてのアプリはそれぞれ異なるため、すべてのアプリの機能が利用可能な App Actions 組み込みインテント（BII）と一致するわけではありません。アプリの機能に対応する BII がない場合は、代わりにカスタムインテントを使用することにより、App Actions でアプリを拡張できます。

BII と同様に、カスタムインテントは shortcuts.xml のスキーマに従い、アシスタントと定義済みのフルフィルメントとの間の接続ポイントとして機能します。カスタムインテントには、対応するフルフィルメントのパラメータにマッピングできるインテントパラメータもあります。

BII とは異なり、カスタムインテントには、ユーザーが発話する可能性のあるクエリの例を記述するクエリパターンが必要です。このアプローチは、ユーザーがインテントを表現する一般的な方法をモデル化する組み込みインテントとは異なります。

制限事項

カスタムインテントには次の制限があります。

カスタムインテントの名前を actions.intent で始めることはできません。
カスタムインテントの名前は、アプリのカスタムインテント名の中で一意にする必要があります。
Google アシスタントによるパラメータ抽出に使用できるのは、特定のデータタイプのみです（サポートされているタイプをご覧ください）。
カスタムインテントには、使用可能なクエリパターンの例を含める必要があります（クエリパターンをご覧ください）。
各クエリでは、最大 2 つのテキストパラメータがサポートされます。この上限は他のデータタイプには適用されません。
カスタムインテントは en-US ロケールのみをサポートしています。また、デバイスとアシスタントの言語設定が一致している必要があります。

サポートされているタイプ

カスタムインテントは、パラメータ抽出に対して以下の schema.org タイプをサポートしています。

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

カスタムインテントを使用して App Actions を定義する

BII を使用する他の App Actions と同様に、shortcuts.xml の <capability> 要素でカスタムインテントを定義します。

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 用に予約されています。代わりに、カスタムインテントに名前を付けるときは、BII と Android インテント（両者は異なります）の両方と区別するために、プレフィックス custom.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>
...

BII のショートカットと同じ形式を使用して、shortcuts.xml でカスタムインテントのショートカットを定義します。

次のコードは、参照されるクエリパターンを使用して SCHEDULE_APPOINTMENT カスタムインテントをトリガーし、apptType パラメータの定義済みの値 DRIVERS_LICENSE と VEHICLE_REGISTRATION を使用する App Action を記述しています。

<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 とは異なります。

Android リソースファイル（通常は /res/values/strings.xml）で、クエリパターンを文字列配列のアイテムとして指定します。App Action が呼び出されると、Google アシスタントは、ユーザーの意図をフルフィルメントと照合する一環として、ユーザークエリをクエリパターンと照合します。指定した各クエリパターンは、対応するカスタムインテントに対して有効と見なされるフレーズを表します。

カスタムインテントのクエリパターンを指定する際は、各パターンでは「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.」

ユーザークエリと一致させるには、呼び出しフレーズの後のクエリ部分を含むクエリパターンを指定します。クエリから抽出する情報（ユーザーが指定したテキストや数値など）については、クエリパターン内のプレースホルダで対応しているインテントパラメータに値を割り当てます。

クエリパターンでパラメータを参照するには、パターンのパラメータの名前に $ を追加します。たとえば、<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」が有効なクエリとなります。