Alexaの買い物リストとやることリストにアクセスする

Alexaの買い物リストとやることリストにアクセスする

Alexaユーザーは2つのデフォルトリストにアクセスできます。 Alexa買い物リストとAlexaやることリストです。カスタムリストを作成して管理することもできます。ユーザーは、音声またはAlexaアプリを使用してAlexaリストの確認や変更を行うことができます。たとえば、家でAlexa買い物リストにアイテムを追加するようAlexaに頼んだ後、店でAlexaアプリを使用してアイテムを確認し、更新できます。同様に、Alexaリストにアクセスするアプリをカスタムスキルとともに実装することもできます。アプリからスキルへのセッション外メッセージを使用して、これらのリストの同期を保つことができます。

カスタムスキルでAlexaの買い物リストとやることリストにアクセスできます。また、カスタムリストを作成して管理することもできます。リスト管理の詳細については、リストスキルの概要を参照してください。

Alexa買い物リストとやることリスト、およびカスタムリストへのアクセスを構築するには、次の手順に従います。

前提条件

Alexaにアクセスするには、カスタムスキルが必要です。カスタムスキルの作成方法の詳細については、カスタムスキルのビルド手順を参照してください。Alexaリストを使用するカスタム音声対話インテントモデルをデザインします。

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

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

  1. Alexaリストにアクセスする権限を設定します。
  2. 不足している権限を処理します。
  3. Alexaリストにアクセスします。
  4. リスト管理機能を実装します。

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

Alexa開発者コンソールを使用して、ユーザーのAlexaリストにアクセスするための適切な権限を設定します。スキルの機能をサポートするには、リストの読み込みまたはリストへの書き込みの権限、あるいはその両方をリクエストします。

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

  1. Alexa開発者コンソールにログインします。
  2. スキルの一覧からカスタムスキルを見つけ、アクションのドロップダウンから編集を選択します。
  3. 左側のペインでツールをクリックし、アクセス権限をクリックします。
  4. 読み取り権限を有効にするには、リストの読み込みを切り替えます。
  5. 書き込み権限を有効にするには、リストへの書き込みを切り替えます。

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

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

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

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

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

読み込みと書き込みに必要なリスト権限はそれぞれalexa::household:lists:readとalexa::household:lists:writeです。

ステップ3：Alexaリストにアクセスする

Alexaリストにアクセスするには、ユーザーのAlexaリストにアクセスする権限をユーザーがスキルに与えたことを示すアクセストークンが必要です。このトークンは、ユーザーの音声リクエストなど、セッション内リクエストで取得します。スキルセッション外でAlexaリストにアクセスするには、アプリまたはウェブサイトにユーザー固有のアクセストークンが必要です。相互認証を使用してこのトークンを取得します。

セッション中のアクセストークン

スキルに送信される各リクエストには、ユーザーがスキルに与えた権限をカプセル化するAPIアクセストークンが含まれています。アクセストークンは、context.System.apiAccessTokenパラメータにあります。パラメータの詳細については、リクエスト本文の構文を参照してください。このトークン値は、リスト管理 REST APIで使用します。

セッション外のアクセストークン

アプリは、スキルセッション外でユーザーリストを更新する必要がある場合、セッション外アクセストークンをリクエストできます。たとえば、ユーザーは音声でショッピングリストに牛乳を追加し、店でアプリ内のリストを更新できます。

スキルセッション外でList Management APIを呼び出すには、スキルがユーザー固有のAlexaアクセストークンを非同期で保存および更新する必要があります。ユーザーがスキルにAlexaリストへのアクセスを許可すると、Alexaがスキルに認可コードを提供します。OAuth 2.0コード付与フローを使用して、認可コードとクライアント認証情報をアクセストークンに交換します。詳しい手順については、セッション外からAlexaを呼び出すためのユーザー固有のアクセストークンを取得するを参照してください。トークンの有効期限が切れた後に別のアクセストークンを取得できるように、認可コードを保存しておいてください。

ステップ4：リスト管理機能を実装する

List Management REST APIを使用して、カスタムおよびデフォルトのAlexaリストの作成、読み取り、更新、削除、およびトラバースを行います。アーカイブリストは読み取り専用リストです。アーカイブリストの項目を読み取ることはできますが、更新または削除はできません。ステップ3で取得したアクセストークンをREST Authorizationヘッダーで使用します。

List Management REST APIに加えて、スキルはリストイベントとスキルイベントにアクセスできます。これらのイベントはスキルの機能を拡張するために使用します。

制限

List APIリクエストはスキルあたり25 TPSを超えることはできません。この制限を超えたリクエストはHTTP 429 Too Many Requestsエラーコードを受け取ります。リクエストの再試行には指数バックオフを使用します。

サンプルコード

スキルにリストを組み込む方法のサンプルコードについては、Alexaリストへのアクセスデモを参照してください。