リストスキルの作成手順

リストスキルの作成手順

リストスキルは、カスタム音声対話モデルを選択して作成することも、対話モデルなしで作成することもできます。スキルマニフェストを更新し、リストとスキルのイベントを有効にする適切な設定を追加します。

リストとスキルのイベントを有効にした場合は、Alexa Skills Kit（ASK）コマンドラインインターフェース（CLI）を使ってスキルを管理する必要があります。Alexa開発者コンソールでそのスキルを編集することはできなくなります。

手順に従って、リストイベントを同期するリストスキルを作成します。イベントを使用しないカスタムスキルの場合は、Alexa開発者コンソールで管理できます。カスタムスキルにリストを追加する場合は、Alexaの買い物リストとやることリストにアクセスするを参照してください。

前提条件

リストスキルを作成する際に必要なものは以下のとおりです。

  • Amazon開発者アカウント。日本語のスキルを開発してテストするには、Amazon.co.jpのアカウントを使用します。作成済みでない場合は、Amazon.co.jpにアクセスして新しいアカウントを作成してください。アカウントは無料です。
  • Alexa搭載デバイス（Amazon Echoなど）。Echoへのサインインには、Alexa開発者アカウントと同じ認証情報を使用してください。
  • モバイルデバイスにインストールしたAmazon Alexaアプリ。Alexaアプリのダウンロード手順については、AmazonウェブサイトのAlexaアプリをダウンロードするを参照してください。モバイルデバイス上のAlexaアプリへのサインインには、Alexa開発者アカウントと同じ認証情報を使用してください。
  • ASK CLIクイックスタートに従ってASK CLIをインストールします。
  • CLIを使用してスキルを作成します。CLIを使用してスキルを作成する方法の詳細については、新しいスキルプロジェクトを作成するを参照してください。

リスト管理機能を追加する手順

リストスキルにリスト管理機能を追加するには、次の手順に従います。

  1. ユーザーリストにアクセスする権限を設定します。
  2. 不足している権限を処理します。
  3. ユーザーのAlexaリストにアクセスします。
  4. リストスキルでリストやスキルのイベントを使用します。

ステップ1：ユーザーリストにアクセスする権限を設定する

スキルマニフェストを編集して、ユーザーのAlexaリストにアクセスするための適切な権限を設定します。スキルの機能をサポートするには、読み込みまたは書き込みの権限、あるいはその両方の権限を設定します。

開発者コンソールでリストへのアクセスの権限を設定するには

  1. エディターでskill.jsonファイルを開きます。
  2. リストイベントのサブスクリプションを実行するには、apisオブジェクトにhouseholdListを追加します。
    スキルマニフェストは、apisオブジェクトにあるhouseholdListを持つスキルマニフェストか、apisオブジェクトに追加のhouseholdListフィールドを持つカスタムスキルマニフェストのいずれかです。詳細については、リストスキルのマニフェストの例を参照してください。
  3. ユーザーに対してリストの適切な権限を付与することを促すプロンプトを出すよう、スキルをセットアップします。permissionsオブジェクトを追加します。permissionsオブジェクトを使用して、Alexaリストに対する読み込みまたは書き込み権限の許可をユーザーに求めることができます。
    読み込みと書き込みに必要なリスト権限はそれぞれalexa::household:lists:readとalexa::household:lists:writeです。この手順を実行すると、開発者コンソールで権限を設定する場合と同じ結果になります。以下は、スキルがリストに対する読み込みや書き込みの権限をリクエストするpermissionsオブジェクトの例です。 
    "permissions": [{
    "name": "alexa::household:lists:read"
},
{
    "name": "alexa::household:lists:write"
}
]
  4. イベントを使用する場合は、イベントのサブスクリプションを説明するeventsオブジェクトを追加します。追加するイベントは、スキルが必要とするものだけにしてください。
    カスタムコンポーネントのないリストスキルのマニフェストの例については、リストスキルマニフェストを参照してください。
    スキルマニフェストにeventsオブジェクトがあってもapisオブジェクトにcustomオブジェクトが含まれない場合、カスタム対話モデルはオプションになります。
  5. update-skill-manifest CLIコマンドを使って、スキルのマニフェストを更新します。

スキルを有効にしたユーザーは、Alexaアプリで権限を付与または拒否するためのカードを受け取ります。

ステップ2：不足している権限を処理する

ユーザーのAlexaリストにアクセスするには、ユーザーがAlexaアプリのスキルセクションでスキルに対する権限を付与する必要があります。ユーザーが権限を取り消すまで、スキルにアクセスできます。ユーザーはいつでも、Alexaアプリのスキルのページにある設定で、スキルに許可した権限を変更することができます。

ユーザーがスキルに自分のAlexaリストへのアクセス権を付与していない場合は、適切な対応をとる必要があります。ベストプラクティスとしては、Alexaアプリの音声プロンプトと権限カードを使用して、Alexaアプリで必要なアクセスを許可するようユーザーに求めることができます。

次のコード例は、ユーザーのAlexaリストへの書き込み権限を求めるカードの形式を示しています。

{
  "version": "1.0",
  "response": {
    "card": {
      "type": "AskForPermissionsConsent",
      "permissions": [
        "alexa::household:lists:read",
        "alexa::household:lists:write"
      ]
    }
  }
}

ステップ3：ユーザーのAlexaリストにアクセスする

アカウントリンクを実装し、スキルを有効にしたユーザーをシステムのIDに関連付けます。スキルマニフェストにはアカウントリンクオブジェクトを含める必要があります。このオブジェクトは、update-account-linking subcommandでマニフェストに追加できます。アカウントリンクの詳細については、アカウントリンクとはを参照してください。アカウントリンクを実行するには、スキルID、クライアントID、クライアントシークレットがスキルで必要となります。

Alexa開発者コンソールでスキルの認証情報を取得するには

  1. Alexa開発者コンソールにサインインします。
  2. スキルリストから、カスタムスキルを探し、スキル名の下にあるスキルIDをコピーをクリックします。
  3. アクションを選択ドロップダウンから、編集を選択します。
  4. ビルド、ツール、アクセス権限の順にクリックします。
  5. AlexaクライアントIDとAlexaクライアントシークレットを確認するには、画面の下までスクロールして表示をクリックします。
  6. AlexaクライアントIDとAlexaクライアントシークレットをコピーします。

または、ASK CLIのget-skill-credentials SMAPIサブコマンド、ask smapi get-skill-credentials -s {skill-id}を使って、認証情報を取得することもできます。

ステップ4：リストスキルでリストやスキルのイベントを使用する

リストイベントとスキルイベントを使用すると、ユーザーがスキルとセッション中でないときでも「アレクサ、買い物リストにバナナを追加して」といった上位レベルの発話にすぐに応答できるスキルを作成できます。たとえば、ユーザーがニュースを聞いたり、ゲームをしたりしているときにAlexaリストに項目の追加をリクエストするような場合です。

スキルサービスで、リストイベントに応答するハンドラーを実装します。

スキルメッセージAPIを使用して、アプリやウェブサイトなど、ユーザーがスキルセッション中でないときにリストにアクセスします。詳細については、スキルメッセージAPIリファレンスを参照してください。スキルにリストの同期以外の機能を追加する場合、スキルにインテントモデルを追加します。スキルにカスタムコンポーネントを含める場合、カスタム対話モデルが必要になります。また、apisオブジェクトにcustomオブジェクトを入れ子にする必要があります。詳細については、カスタムスキルマニフェストの例を参照してください。

サンプルコード