カスタムタスクをAlexa定型アクションに統合する



カスタムタスクをAlexa定型アクションに統合する

カスタムタスクをAlexa定型アクションに統合すると、より豊かなエクスペリエンスをユーザーに提供し、スキルへのトラフィックを増やすことができます。また、Alexa定型アクションとの統合用に作成したカスタムタスクをSkill ConnectionsQuick Linkに再利用することもできます。

このページでは、スキルのタスクをAlexa定型アクションとしてユーザーに提供する方法について説明します。

Alexa定型アクションとは

Alexa定型アクションは、トリガーとアクションで構成されます。トリガーとは、時刻(午前7時)などのイベントや、「アレクサ、朝のセッションを始めて」などのユーザー発話です。 アクションは、たとえば、ニュースのブリーフィングをしてから天気予報を読み上げるといった、トリガーが発生したときにAlexaに実行させるタスクです。ユーザーは、ビルトインのAlexa定型アクションを有効にすることも、Alexaアプリでトリガーと定型アクションを選択して独自のカスタム定型アクションを作成することもできます。

次のセクションでは、アクションに組み込むためのカスタムタスクを公開する方法を説明します。ユーザーは、スキルのカスタムタスクを定型アクションに追加できます。

Alexaアプリでのスキルとタスクの表示画面

カスタムタスクを定義し、公開してAlexa定型アクションに統合すると、タスクはスキルのアクションとして表示されます。ユーザーは、Alexaアプリに表示されるアクションを選んで定型アクションを作成できます。

ユーザーがAlexaアプリでスキルを有効にすると、スキルのカスタムタスクは定型アクションで選択できるようになります。ユーザーはアクションを追加 > スキル > {スキル名}をタップしてこの画面を表示します。次のスクリーンショットは「マイニュース」というスキルの例です。3つのカスタムタスクが定型アクションとして表示されています。

Alexaアプリに表示されたマイニューススキルのタスクリスト。「マイニュースを開く」、「最新ニュース」、「株価」の3つのタスクが表示されている
Alexaアプリに表示されたマイニューススキルのタスク一覧

カスタムタスクをAlexa定型アクションに統合する

スキルにカスタムタスクを追加する手順に従って、スキルにカスタムタスクを構築します(作成していない場合)。

カスタムタスクをAlexa定型アクションで使えるようにするには、ユーザーが理解しやすいタイトル、説明、入力パラメーター名と説明をタスクに付ける必要があります。これらの文字列は、Alexaアプリでユーザーに表示されます。

これらの文字列は、次のようにタスク定義ファイルに指定します。

  1. まず、どこのロケールでカスタムタスクをAlexa定型アクションとして利用できるようにするかを決めます。有効なロケールは、en-AUen-CAen-INen-GBen-USfr-CAfr-FRde-DEhi-INit-ITja-JPpt-BRes-ESes-MXes-USです。スキルが対象ロケールで公開されていることを確認してください。

  2. ロケールごとに、適切な言語で次の情報を指定します。タスクのtitledescriptionの各フィールドは、常に必須です。タスクの入力パラメーターのnamedescriptionは、タスクに入力パラメーターがある場合のみ必須です。

    • タスクのタイトルと説明infoオブジェクトのx-amzn-display-detailsフィールドは、カスタム拡張フィールドです。わかりやすい文字列を追加し、ローカライズしたタイトルを割り当てることがきます。このフィールドに入力したタスクのtitledescriptionがAlexaアプリに表示されます。
    • 入力パラメーターの名前と説明pathsオブジェクトのx-amzn-display-detailsフィールドは、カスタム拡張フィールドです。入力パラメーターにわかりやすい文字列を追加し、ローカライズしたパラメーターを割り当てることができます。このフィールドに入力したタスク入力パラメーターのnamedescriptionがAlexaアプリに表示されます。

タスクをAlexa定型アクションに統合する際の制限事項

  • 開発者プレビューの段階では、入力パラメーターなしか、1つの文字列入力パラメーターを取るカスタムタスクのみがサポートされます。
  • タスク定義ファイルには次の制限があります。
    • x-amzn-alexa-access-scopeフィールドは、vendor-privateではなく、publicに設定する必要があります。
    • オプションのminLengthフィールドとmaxLengthフィールドを使用して、エンドユーザーが入力パラメーター値として入力できる最小、最大の長さを指定できます。minLengthは正の整数で指定する必要があります。maxLengthminLength以上の値を指定する必要があります。デフォルトのmaxLength値は100です。
  • タスクは、Amazon定義済みタスクではなく、カスタムタスクである必要があります。
  • タスクは公開中(認定済みおよび公開中)で、希望する各マーケットプレイスで有効である必要があります。詳細については、多言語に対応するスキルを開発するおよびスキルストアの詳細と公開範囲を定義するを参照してください。
  • 開発者プレビューの段階では、バージョン管理がサポートされません。
  • ユーザーはAlexaアプリで任意の文字列を入力パラメーターとして入力できるため、想定外のテキストが入力された場合にもタスクで適切に処理する必要があります。たとえば、ユーザーがタスクでサポートしていないテキストを入力した場合、Amazonではデフォルト値を使用することを推奨します。

例:入力パラメーターなしのカスタムタスクのタスク定義

以下の例は、最新ニュースを提供する「最新ニュース」カスタムタスクのタスク定義です。このタスクにはタスク入力パラメーターがありません。タスクをAlexa定型アクションに統合できるように、x-amzn-display-detailsフィールドにはわかりやすいタスクタイトルと説明の文字列が入っています。

{
  "openapi": "3.0.0",
  "info": {
    "title": "最新ニュース",
    "version": "1",
    "x-amzn-alexa-access-scope": "public",
    "x-amzn-display-details": {
      "ja-JP": {
        "title": "最新ニュース",
        "description": "最新ニュースを読み上げます"
      },
      "es-US": {
        "title": "Actualización de las noticias",
        "description": "Reproducir actualización de noticias"
      }
    }
  },
  "paths": {
    "/NewsUpdate": {
      "post": {
        "requestBody": {
          "content": {}
        },
        "response": {
            ...
        }
      }
    }
  }
}

infoオブジェクトに入力したわかりやすい文字列が、Alexaアプリの定型アクションリストに表示されます。この場合、入力パラメーターがないため、ユーザーが定型アクションリストから「最新ニュース」を選択すると確認画面にリダイレクトされます。Alexaアプリは、テンプレートを使って次の文字列を表示します。 Alexaは${task title}を開きます。タスクタイトルには、infoオブジェクトのx-amzn-display-details.titleフィールドから取得したわかりやすい文字列が入ります。

次のスクリーンショットは、入力パラメーターなしの「最新ニュース」タスクの確認画面の例です。

最新ニュースタスクの確認画面
最新ニュースタスクの確認画面

例:1つの文字列入力パラメーターを取るカスタムタスクのタスク定義

以下は、株価を提供する「株価」カスタムタスクの例です。「最新ニュース」カスタムタスクと同様、このタスクにもAlexa定型アクションに統合するためのx-amzn-display-detailsフィールドがあります。このフィールドにタスクタイトルと説明のわかりやすい文字列が指定されています。また、このタスクには会社名という1つの文字列入力パラメーターが必要です。pathsオブジェクトの別のx-amzn-display-detailsフィールドに、パラメーター名と説明のわかりやすい文字列を指定します。

{
  "openapi": "3.0.0",
  "info": {
    "title": "株価",
    "version": "1",
    "x-amzn-alexa-access-scope": "public",
    "x-amzn-display-details": {
      "ja-JP": {
        "title": "株価",
        "discription": "株価の情報を提供します"
      },
      "es-US": {
        "title": "Actualización de stock",
        "description": "Proporcionar actualizaciones de precios de acciones"
      }
    }
  },
  "paths": {
    "/StockQuote": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company": {
                    "type": "string",
                    "x-amzn-display-details": {
                      "ja-JP": {
                        "name": "会社名",
                        "description": "銘柄コードを入力してください"
                      },
                      "es-US": {
                        "name": "Nombre de empresa",
                        "description": "Ingrese el símbolo de stock"
                      }
                    }
                  }
                }
              }
            }
          }
        }
        "responses": {
          ...
        }
      }
    }
  }
}

この場合、アクションには文字列入力パラメーターが含まれます。このため、ユーザーが「株価」アクションを選択すると、テキスト入力フィールドのある画面にリダイレクトされます。入力フィールドのヒントテキストとして、pathsオブジェクトのx-amzn-display-details.descriptionに指定したわかりやすい文字列が表示されます。

次のスクリーンショットは、1つのパラメーターを取る「株価」タスクの入力画面です。「銘柄コードを入力してください」というプロンプトが表示されています。

株価タスクの入力画面。ユーザー入力前には「銘柄コードを入力してください」のプロンプトが表示されます。
ユーザー入力前の株価タスク入力画面

ユーザーがプロンプトをタップして銘柄記号を入力すると、プロンプトは消え、銘柄コードのみが表示されます。

株価タスクの入力画面。ユーザーが銘柄コード「AMZN」を入力するとプロンプトは消えます。
ユーザー入力後の株価タスク入力画面

スキルを公開してカスタムタスクを利用可能にする

カスタムタスクをAlexa定型アクションで利用できるようにするプロセスは、Skill Connectionsでカスタムタスクを利用できるようにする方法と同じです。カスタムタスクを利用できるようにするには、スキルが認定され、公開されている必要があります。統合されたスキルがliveステージに公開されると、カスタムタスクはAlexa定型アクションとして利用できるようになります。

カスタムタスクが特定のロケールで表示されるようにするには、infoオブジェクトのx-amzn-display-detailsフィールドに該当ロケールのタスクタイトルと説明のわかりやすい文字列を指定します。タスク定義に特定ロケールのタスクタイトルと説明がない場合、そのロケールではこのタスクをAlexa定型アクションとして利用できません。

ベストプラクティス: カスタムタスクパラメーター

スキルのタスクを使用するユーザーのプライバシーとセキュリティを保護し、最高のユーザーエクスペリエンスを提供するには、以下の推奨事項に従ってください。

  • カスタムタスクのパラメーターに、ユーザー個人を特定できる情報(PII)を示す可能性のある名前または値を含めないでください。PIIデータには、ユーザーの名前、住所、メールアドレス、社会保障番号などが含まれます。
  • カスタムタスク入力パラメーターの説明には、Alexa定型アクションを使用するユーザーが有効なテキストを入力できるよう、わかりやすい手順や説明を提供してください。