ドキュメント

Intentのパラメータをリゾルブする

Intentのパラメータを検証し、続行に必要な情報があることを確認します。

概要

ユーザーのリクエストに対応するのに必要な情報があるかを検証するには、Intentのパラメータをリゾルブする必要があります。ユーザーがSiriに話しかけると、ユーザーが発話したコマンドはSiriによってアクションとして実行が可能なデータに変換され、そのデータはIntentオブジェクトに配置されます。リゾルブでは、SiriKitから、handlerオブジェクトのリゾルブメソッドを呼び出して各パラメータを個別に検証するよう求められます。各メソッドにおいて、提供されたデータを検証し、パラメータのリゾルブが成功したか否かを示すリゾルブリザルトオブジェクトを作成します。SiriKitは、このリゾルブリザルトオブジェクトを使って続行方法を判断します。たとえば、リゾルブリザルトに2つ以上の候補があり、ユーザーが曖昧さを解消する必要がある場合、SiriKitはユーザーに対しそれらの候補からいずれかを選択するよう求めます。

リスト1は、配車予約Appがユーザーの降車場所をリゾルブする方法を示しています。この例では、ユーザーが有効な降車場所を提供しないと、Appは配車リクエストに対応できません。ユーザーがAppのサービスエリア内にある降車場所を提供すれば、メソッドによって成功のリゾルブリザルトが返されます。降車場所が有効なサービス区域外の場合は、その場所がサポートされていないことを示すリゾルブリザルトになります。ユーザーが降車場所を一切指定しなかった場合は、メソッドにより、値が必要であることを示すリゾルブリザルトが作成されます。

リスト1

配車サービスの降車場所をリゾルブする

func resolveDropOffLocation(
            forRequestRide intent: INRequestRideIntent,
            with completion: @escaping (INPlacemarkResolutionResult) -> Void) {     
   var result: INPlacemarkResolutionResult
        
   if let location = intent.dropOffLocation {
      // If the location is valid, use it; otherwise,
      // let the user know it is not supported
      if self.locationIsInsideServiceArea(location) {
         result = INPlacemarkResolutionResult.success(with: location)
      } else {
         result = INPlacemarkResolutionResult.unsupported()
      }
   } else {
      // Ask for the drop-off location.
      result = INPlacemarkResolutionResult.needsValue()
   }

   // Return the result back to SiriKit.
   completion(result)
}

リゾルブ可能なパラメータそれぞれに対応するリゾルブリザルトクラスがあり、これを使ってSiriKitに結果を返します。たとえば、先ほどの例のCLPlacemark(英語)オブジェクトをリゾルブするには、INPlacemarkResolutionResult(英語)オブジェクトの作成が必要です。すべてのリゾルブリザルトクラスは、あらゆるタイプのパラメータに共通のリゾルブ方法を定義するINIntentResolutionResult(英語)基底クラスから継承されます。

SiriKitにリゾルブリザルトを返すときは必ず、実際の結果についてできるだけ多くの情報を含めてください。SiriKitは、リゾルブ試行のたびに、提供された情報を使ってIntentオブジェクトをアップデートします。リゾルブが失敗し、SiriKitが再びリゾルブメソッドを呼び出す必要がある場合は、追加情報を使ってより速くリゾルブが完了するようにできます。たとえば、リゾルブ中に同じ名前の連絡先が2件見つかった場合、各INPerson(英語)オブジェクトのcustomIdentifier(英語)プロパティに一意の文字列を追加しておくと、この後選択された連絡先の検索に使用できます。リゾルブメソッドは、その他の連絡先一致ロジックをバイパスして、最初にこのIDを検索できます。

適切なリゾルブリザルトを選択する

SiriKitに返すリゾルブリザルトオブジェクトによって、さらにユーザーとのやり取りを行うかどうかが決まります。すべてのパラメータのリゾルブが成功するか、パラメータが不要であることをSiriKitに知らせる必要があります。リゾルブリザルトがそれ以外の場合は、Siriがユーザーからさらに情報を収集する必要が生じます。

リゾルブリザルトオブジェクトを作成するには、適切なクラスメソッドを選択します。特定のリゾルブリザルトクラスごとに、対応するタイプで取りうるリゾルブリザルトを定義するメソッドがあります。INIntentResolutionResult(英語)基底クラスで、一連の共通リゾルブリザルトも定義されます。表1は、リゾルブリザルトのタイプとその意味の一覧です。

表1

リゾルブリザルトのタイプ

リゾルブリザルト

意味

成功

リゾルブ成功は、その値を使ってユーザーのリクエストを処理できることを意味します。ユーザーが何を意味しているのか、経験に基づいて推測することを意味する場合も、このリゾルブリザルトを使います。リゾルブリザルトがこのタイプの場合、それ以上ユーザーとのやり取りは必要ありません。

例:ユーザーが「ジョン」という名前の人を指定した場合、この名前の連絡先が1件しかななければ、パラメータはその人を指しているものとリゾルブできます。

不要

サービスで使用しないパラメータについて、このリゾルブリザルトを指定します。リゾルブリザルトがこのタイプの場合、それ以上ユーザーとのやり取りは必要ありません。

例:「ワークアウトの目標」がフィットネスAppでサポートされていない場合、「ワークアウトの目標」についてこのリゾルブリザルトを指定できます。

曖昧さの解消が必要

複数のリゾルブリザルトが考えられ、1つに限定できない場合にこのリゾルブリザルトを指定します。リゾルブリザルトがこのタイプの場合、SiriKitはユーザーに対し、提供されたオプションからいずれかを選択するよう求めます。

例:ユーザーが「ジョン」という名前の人を指定した場合、同程度に可能性のある同名の連絡先が2件あると、どちらかを選ぶようユーザーに求めることができます。

確認が必要

選択した値について、ユーザーに確認してほしい場合にこのリゾルブリザルトを指定します。1つの値を選択できるが、正しい値かどうか完全に自信を持てないという場合に指定します。リゾルブリザルトがこのタイプの場合、SiriKitはユーザーに対し、値を確認するよう求めます。

「ジョン」という名前の連絡先が2件あり、1件はよく使う項目に指定されていて頻繁に使用されている場合、よく使う項目の方を選択してユーザーに確認を求めます。

値が必要

パラメータに値が指定されておらず、値が必要な場合に、このリゾルブリザルトを指定します。リゾルブリザルトがこのタイプの場合、SiriKitはユーザーに対し、値を提供するよう求めます。

例:ユーザーが金額を指定せずに別の人からの支払いを求めている場合、このリゾルブリザルトを返します。

サポートなし

ユーザーが提供した値が無効な場合や、ほかのパラメータの値と競合する場合に、このリゾルブリザルトを指定します。リゾルブリザルトがこのタイプの場合、SiriKitはユーザーに対し、値がサポートされていないことを知らせます。

例:Appがユーロと米国ドルしかサポートしていないのにユーザーがカナダドルで支払おうとした場合、このリゾルブリザルトを返します。

できるだけ速やかに「成功」または「不要」のリゾルブリザルトに到達するようにします。その他のリゾルブリザルトの場合、さらにユーザーとのやり取りが発生したり、さらにハンドラを呼び出したりすることになります。また、同じパラメータについて曖昧さの解消を繰り返しユーザーに求めるとユーザに不満を感じさせることがあるので、避けるようにします。できるだけユーザーの思考様式や習慣に基づいて妥当な値を選び、どうしても必要な場合にのみ、曖昧さの解消や確認を求めるようにしてください。

関連項目

Intentのリゾルブとハンドル

Intentの詳細をコンファームする

Intentパラメータの最終的な検証を行い、サービスがIntentを実行できる状態にあることを確認します。

Intentのハンドル

Intentを実行し、処理内容に関するフィードバックをSiriKitに提供します。