プロアクティブイベントAPI



プロアクティブイベントAPIリファレンス

プロアクティブイベントAPIを使用すると、Alexaにイベントを送信できます。イベントとは、ユーザーが興味を持つと考えられる、事実に基づくデータのことです。イベントを受信すると、Alexaは、これらのイベントを受け取るよう選択したユーザーに、プロアクティブに情報を配信します。現在、このAPIは、Alexa通知というプロアクティブチャネルを1つサポートしています。将来的にプロアクティブチャネルが追加されると、新しいAPIを統合しなくても、追加のチャネルを利用できるようになります。

ユーザーが自分で、スキルからイベントの通知を受け取るよう選択できるため、Alexaからプロアクティブなメッセージが届いても、ユーザーが困惑することはありません。このAPIを使用すると、開発者はユーザー別のイベントを送信できるので、ユーザーに応じた通知をすることができます。反対に、スキルから通知を受け取るよう選択したすべてのユーザーに。一斉送信でイベントを通知することも可能です。たとえば、天気スキルからは天気に関するアラートを1つだけ送信し、その後Alexaが関心のあるすべてのユーザーに配信するということができます。

プロアクティブイベントのスキルデモで、プロアクティブイベントを使用してサンプルスキルを作成してみてください。

スキルにプロアクティブイベントを追加する

プロアクティブイベントをスキルに追加するための高レベルプロセスは以下のとおりです。

  1. ユーザーに送信するイベントを表すスキーマを選択します。
  2. プロアクティブイベント機能を使用して、スキルマニフェストを更新します。詳細については、SMAPIを使用したプロアクティブイベントを定義するを参照してください。
  3. スキルサービスを更新して、注文の配達が完了したときなど、特定の条件が発生した場合にユーザーにプロアクティブイベントを送信します。
  4. スキルのエンドユーザーとしてAlexaデバイスをセットアップし、ユーザーエクスペリエンスをテストします。Alexaアプリの通知設定ページで、スキルの通知を有効にします。エンドユーザーとして、プロアクティブイベントを受け取るのに必要な権限を提供したことになります。スキルが公開中の場合は、ユーザーは同様にAlexaアプリの通知を有効にして、プロアクティブイベント通知を有効にします。ユーザーがスキルを使用すると、Alexaアプリでこの変更を行うようにプロンプトが出されます。
  5. 開発者コンソールのテストセクションを開きます。開発者がエンドユーザーとなってスキルをテストします。プロアクティブイベントを送信し、Alexa搭載デバイスで通知を受信できることを確認します。詳細については、Alexaへのプロアクティブイベントの送信を準備するProactiveEvents APIを呼び出すを参照してください。
  6. スキルの認定を申請します。詳細については、スキルをテストして認定を申請するを参照してください。認定が完了すると、ユーザーがスキルにアクセスできるようになります。

通知APIから移行する

以前に通知APIプレビューをスキルに統合している場合、スキルをProactiveEvents APIに移行して、スキルの再認定を申請します。スキルが認定されると、以前にスキルの通知を有効にしていたユーザーは、スキルで宣言したプロアクティブイベントに自動的にサブスクリプションが行われます。スキルマニフェストに新しいイベントタイプを追加するたびに、関連する通知を有効にしていたユーザーに対し、新しいイベントタイプのサブスクリプションが行われます。

イベントとスキーマについて

スキルをSMAPIを使用したプロアクティブイベントを定義するで説明されているとおりにSMAPI(スキル管理API)から設定すると、スキルへのプロアクティブイベントのサポートを追加できます。

サポートするプロアクティブイベントのスキーマを事前に定義されたスキーマの一覧から選択できます。これらのスキーマは、開発者がユーザーに通知したいイベントを表します。スキルサービスで、プロアクティブイベントAPIを使用して、これらのイベントを適宜ユーザーに送信します。Alexaアプリでユーザーがスキルから通知を受信することを選択した場合、ユーザーはイベントごとに通知を受け取ることになります。詳細については、プロアクティブイベントのスキーマを参照してください。

スキーマ1つにつき、実装できるインスタンスは1つのみです。

次に、注文のステータスを表すAMAZON.OrderStatus.Updatedイベントの例を示します。

{
  "timestamp": "2019-04-18T03:27:00.00Z",
  "referenceId": "mytest-request-id",
  "expiryTime": "2019-04-19T10:00:00.00Z",
  "event": {
    "name": "AMAZON.OrderStatus.Updated",
    "payload": {
      "state": {
        "status": "ORDER_SHIPPED",
        "deliveryDetails": {
          "expectedArrival": "2019-04-19T12:03:00.000Z"
        }
      },
      "order": {
        "seller": {
          "name": "localizedattribute:sellerName"
        }
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "ja-JP",
      "sellerName": "サンプルコーポレーション"
    }
  ],
  "relevantAudience": {
    "type": "Unicast",
    "payload": {
      "user": "amzn1.ask.account.<identifier>"
    }
  }
}

スキルがユーザーにイベントを配信すると、イベントは、Alexaによってエンドユーザーに読み上げられるテキストを含む事前定義済みのテンプレートと統合されます。

以下は、このスキーマのテンプレートの例です。

「サンプルコーポレーションでのご注文は出荷済みです。12月12日月曜日までにお届け予定です」

スキルにその他のスキーマが必要な場合は、リクエストをAlexaスキルDeveloper voice - 日本語に記入してください。

ローカライズ対応を追加する

プロアクティブイベントAPIは、localizedAttributesフィールドのローカライズされたコンテンツを許可しています。このコンテンツは、イベントに含まれていません。APIはイベントの本文からローカライズされたコンテンツを参照します。列挙値はすべて自動的にローカライズされます。eventフィールドの名前は、ローカライズされません。

以下は、ローカライズされたリソースをイベントAMAZON.WeatherAlert.Activatedevent.payload.weatherAlert.sourceに伝える方法を示した例です。この場合、localizedAttributesの配列に含まれるロケールは1つのみですが、配列localizedAttributesに要素を追加して、適宜追加ロケールをサポートすることができます。

{
  "event": {
    "name": "AMAZON.WeatherAlert.Activated",
    "payload": {
      "weatherAlert": {
        "source": "localizedattribute:source",
        "alertType": "TORNADO"
      }
    }
  },
  "localizedAttributes": [
    {
      "locale": "ja-JP",
      "source": "お天気サンプルコーポレーション"
    }
  ]
}

SMAPIを使用したプロアクティブイベントを定義する

スキル管理API(SMAPI)を使用すると、スキルがユーザーに提供するイベントを定義できます。

イベントはスキルマニフェストの一部として定義します。スキル管理API(SMAPI)を使用してイベントの作成や読み込み、削除ができます。SMAPIを使用してスキルのマニフェストを変更する場合は、SMAPIスキルの操作を参照してください。

スキルマニフェストには、イベントの定義をサポートするために、events.publicationsオブジェクトがあります。events.subscriptionsオブジェクトは、ユーザーサブスクリプションが変化したことを示します。これはオプションです。

マニフェストはpermissionsオブジェクトも含む必要があり、以下の例に示すようにalexa::devices:all:notifications:writepermissions.name値として含んでいなければなりません。

マニフェストは、スキルに含めているプロアクティブイベントを指定する必要があります。この例では、AMAZON.OrderStatus.UpdatedAMAZON.MessageAlert.Activatedになります。

  "permissions": [
    {
      "name": "alexa::devices:all:notifications:write"
    }
  ],
  "events": {
    "publications": [
      {
        "eventName": "AMAZON.OrderStatus.Updated"
      },
      {
        "eventName": "AMAZON.MessageAlert.Activated"
      }
    ],
    "endpoint": {
      "uri": "arn:aws:lambda:us-east-1:0000000000000:function:sampleSkill"
    },
    "subscriptions": [
      {
        "eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"
      }
    ],
    "regions": {
      "NA": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:0000000000000:function:sampleSkill"
        }
      }
    }
  }

詳細については、スキルマニフェストのイベントを参照してください。

Alexaへのプロアクティブイベントの送信を準備する

APIを呼び出すには、次の手順でAlexaの認証を行います。

アクセストークン取得リクエストの形式

以下のセクションでは、アクセストークンを取得するPOSTリクエストの形式について説明します。

HTTPヘッダー

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

HTTPヘッダーのパラメーター

パラメーター 説明
Content-Type リソースのコンテンツタイプです。application/x-www-form-urlencodedである必要があります。 Content-Type: application/x-www-form-urlencoded

リクエスト本文の構文

grant_type=client_credentials&client_id=(clientID)&client_secret=(clientSecret)&scope=alexa::proactive_events

リクエスト本文のパラメーター

パラメーター 説明
grant_type 値はclient_credentialsである必要があります。 grant_type=client_credentials
client_id 開発者コンソールのClientId値です。 client_id=amzn1.iba-client.b2b360f8a77d457981625636121d6edf
client_secret 開発者コンソールのClientSecret値です。 client_secret=c559965801308f2bb79ca787b1dfc8deece8a2fd7d7618946cec1635d26dcbfb
scope 値はalexa::proactive_eventsである必要があります。 scope=alexa::proactive_events

ClientIdとClientSecretの値を確認する

まず、通知権限が有効になっているマニフェストでスキルをデプロイされていることを確認します。

その後、さまざまな方法でClientIdClientSecretにアクセスできます。

  • 開発者コンソールでスキルを選択します。次に、ビルドタブを選択し、アクセス権限セクションまで下にスクロールし、ページ下部のAlexaスキルメッセージングClientIdClientSecretの値を確認します。
  • スキル認証情報APIを使用して、ClientIdClientSecretの値にアクセスします。
  • ASK CLIを使用して、ask api get-skill-credentials -s {skill-id}コマンドを実行します。

cURLリクエストの例

curl -i -XPOST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=xxxx&client_secret=yyyy&scope=alexa::proactive_events' https://api.amazon.com/auth/o2/token

応答の形式

以下のセクションでは、アクセストークンをリクエストするPOSTリクエストへの応答形式について説明します。

HTTPヘッダー

X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
Content-Type: application/json

HTTPヘッダーのパラメーター

パラメーター 説明
X-Amzn-RequestId サーバーで作成された値です。リクエストを一意に識別します。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 X-Amzn-RequestId: d917ceac-2245-11e2-a270-0bc161cb589d
Content-Type リソースのコンテンツタイプ(application/json)です。 Content-Type: application/json

応答本文の構文

{
    "access_token":"Atc|MQEWYJxEnP3I1ND03ZzbY_NxQkA7Kn7Aioev_OfMRcyVQ4NxGzJMEaKJ8f0lSOiV-yW270o6fnkI",
    "expires_in":3600,
    "scope":"alexa::proactive_events",
    "token_type":"Bearer"
}

応答本文のパラメーター

パラメーター 説明
access_token アクセストークンです。すべてのリクエストに使用します。 access_token”:“Atc|MQEWYJxEnP3I1ND03Zz…
expires_in アクセストークンの有効期間(秒)です。3600の場合、アクセストークンは応答が生成されてから1時間で無効になります。 "expires_in":3600
scope アクセストークンリクエストで指定したスコープです。値はalexa::proactive_eventsです。 "scope":"alexa::proactive_events"
token_type 発行されるトークンのタイプです。ベアラートークンのみがサポートされます。 "token_type":"Bearer"

リクエストが正常に完了しなかった場合、200以外のエラーステータスコードが返されます。200以外のコードの場合、応答メッセージのJSONObject本文に以下のパラメーターが含まれることがあります。

reason: « リクエストが受け付けられなかった理由が入ります。 »

エラー処理: ステータスコード

ステータスコード 説明
400 INVALID_REQUEST

この応答には、以下の理由が考えられます。

  • 認可サーバーでコンテンツタイプがサポートされていません。つまり、これはapplication/x-www-form-urlencodedではありません。
  • リクエストに次のいずれかの必須パラメーターが不足しています。grant-typescopeclient_idclient_secret
  • リクエストの形式が正しくありません。
400 UNAUTHORIZED_CLIENT クライアントは、リクエストされた操作を行うことを認可されていません。
400 UNSUPPORTED_GRANT_TYPE grant種別が認可サーバーでサポートされていません。つまり、これはclient_credentialsではありません。
400 INVALID_SCOPE リクエストされたスコープが無効です。つまりこれはalexa::proactive_eventsではありません。
401 INVALID_CLIENT クライアントの認証に失敗しました。
500 SERVER_ERROR
503 SERVICE_UNAVAILABLE サーバーが一時的に使用できません。リクエスターは応答のRetry-Afterヘッダーを参照して再試行する必要があります。Retry-After値の取りうる形式については、HTTP/1.1仕様を参照してください。

ProactiveEvents APIを呼び出す

スキルを開発中の場合は、次の開発エンドポイントを使用してプロアクティブイベントを送信して、スキルをテストします。このエンドポイントはいつでも利用可能であり、ライブユーザーにリクエストを送信しないので、気軽に使用できます。テスト通知を受け取るようサブスクリプションを行う場合は、Alexaアプリの通知設定を使用します。

自分の地域に該当するエンドポイントを選択します。

https://api.amazonalexa.com/v1/proactiveEvents/stages/development(北米)
https://api.eu.amazonalexa.com/v1/proactiveEvents/stages/development(ヨーロッパ)
https://api.fe.amazonalexa.com/v1/proactiveEvents/stages/development(極東)

ライブユーザーにイベントを送信するには、プロアクティブイベントを適切なライブエンドポイントに送信します。これらのエンドポイントを利用するには、スキルの認定が必要です。また、スキルからAlexaへの送信が認定されたイベントのみが受け入れられます。

https://api.amazonalexa.com/v1/proactiveEvents/   (北米)
https://api.eu.amazonalexa.com/v1/proactiveEvents/ (ヨーロッパ)
https://api.fe.amazonalexa.com/v1/proactiveEvents/ (極東)

アクセストークン取得リクエストの形式で受信したアクセストークンを使用して、スキルでプロアクティブイベントAPIを次のように呼び出すことができます。

メソッド POST
URI /v1/proactiveEvents/stages/development
リクエストヘッダー Content-type: application/json Authorization: Bearer << accessToken >>

個別のイベントを作成する

スキルで特定のユーザーを対象とする個別のイベントや、すべてのユーザーを対象とする一斉配信のイベントを作成することができます。

個別のイベントの場合は、type値がUnicastとなり、リクエストのrelevantAudienceオブジェクトには特定のuserIdパラメーターが入ります。次の例を参照してください。

{
    "timestamp": "2018-06-18T22:10:01.00Z",
    "referenceId": "unique-id-of-this-instance",
    "expiryTime": "2018-06-19T22:10:01.00Z",
    "event": "<event_payload>",
    "localizedAttributes": "[ローカライズされたアトリビュートの配列]",
    "relevantAudience": {
        "type": "Unicast",
        "payload": {
            "user": "userId"
        }
    }
}

一斉配信のイベントを作成する

すべてのユーザーを対象とする一斉配信イベントの場合は、リクエストのrelevantAudienceオブジェクトのtype値が「Multicast」になります。次の例を参照してください。

{
  "timestamp": "2018-06-18T22:10:01.00Z",
  "referenceId": "unique-id-of-this-instance",
  "expiryTime": "2018-06-19T22:10:01.00Z",
  "event": "<event_payload>",
  "localizedAttributes": "[ローカライズされたアトリビュートの配列]",
  "relevantAudience": {
    "type": "Multicast",
    "payload": {}
  }
}

プロアクティブイベントAPIのパラメーター

プロアクティブイベントAPIのパラメーターは以下のとおりです。

パラメーター 必須 説明
timestamp 文字列 必須 このイベントに関連付けられたイベントの日付と時刻です(ISO 8601形式)。イベントの作成時刻を表します。
referenceId 文字列 必須 クライアント提供のIDです。イベントを外部エンティティと相関付けるために使用します。このフィールドは、イベント作成の際のべき等キーとしても使用されます。詳細については、イベントのべき等性を参照してください。referenceIdフィールドに使用できる文字は英数字と~であり、referenceIdフィールドの長さは1文字以上、100文字以内にする必要があります。
expiryTime 文字列 必須 サービスが、保留状態になっている通知を自動的に削除する日付と時刻です(ISO 8601形式)。expiryTime値に設定できる最大値は24時間であり、最小値は5分です。
event オブジェクト 必須 ユーザーに送信されるイベントデータです。このイベントに関連付けられているスキーマに準拠します。
localizedAttributes 配列 必須 ローカライゼーションのサポートが必要な一連のイベントアトリビュートを含む項目のリストです。詳しくは、ローカライズに対応した表示を参照してください。
relevantAudience オブジェクト 必須 このイベントの対象ユーザーです。
relevantAudience.type enum 必須 このイベントの対象ユーザーです。イベントをサブスクリプションしているすべてのユーザーを対象にする場合はMulticastを使用し、イベントごとに実際のuserIdで対象を指定する場合はUnicastを使用します。
relevantAudience.payload オブジェクト 必須 relevantAudience.typeMulticastに設定されている場合は、payloadオブジェクトは空ですが、その場合でも必須です。
relevantAudience.payload.user 文字列 relevantAudience.typeUnicastに設定されている場合は必須です。 イベントの対象のuserId値です。

イベントを更新する

イベントを更新するには、同じreferenceIdを使用し、timestampを変更します。最新のtimestampが、イベントの前のインスタンスに置き換わります。

入力を検証する

入力は有効である必要があります。以下のいずれかの入力検証テストに失敗したものがあった場合、ステータスコード400(Bad Request)が返されます。

  • すべての必須フィールドが存在するかどうかを検証します。すべてのフィールドには値が必要です。null値は使用できません。
  • ロケールがIETF BCP 47形式になっているかどうかを検証します。
  • 日付と時刻がISO 8601形式になっているかどうかを検証します。

イベントのべき等性

プロアクティブイベントAPIは、クライアント提供のreferenceIdと、skillIdおよびcustomerIdとの組み合わせに基づいたべき等性を持ちます。つまり、これらの同じパラメーターで繰り返し呼び出しを行うと、同一の結果が得られるということです。

referenceIdはスキルとユーザーの特定の組み合わせに対して一意の値になりますが、スキルは別のユーザーにイベントを作成する際に同じreferenceId値を使用することができます。同様に、ユーザーが同じreferenceId値を持つ別のスキルによって公開されたイベントを持つことができます。

エラー処理: ステータスコード

以下の表は、リクエストがAlexaに送信されたときに発生する可能性のあるエラーステータスコードの一覧です。

ステータス コード 説明
400 Bad request リクエストされたパラメーターが存在しないか、形式が間違っている、またはリクエストされたリソースの作成が前回のリクエストですでに完了している場合に返されます。
403 Unauthorized 認証が失敗したときに返されます。
409 Conflict たとえば、スキルが同じユーザーに対して同じreferenceIdを使用して重複するイベントを作成しようとすると、このコードが返されます。
429 Too many requests クライアントが許可された制限回数より多くの呼び出しを行ったときに戻されます。上限は、スキルごとに25 TPSです。
500 Internal server error 有効な要求に対して、ProactiveEvents APIが内部サーバーエラーを検出したときに戻されます。

サブスクリプションイベント

スキルからイベントを受け取るようにユーザーがサブスクリプションを行うと、Alexaはそのユーザーの情報を含むメッセージをスキルに送信します。この情報は、個々のユーザーにイベントを送信するためのuserIdを確認する際に必要です。イベントのサブスクリプションを行うには、ユーザーはまず最初にスキルのAlexaアプリで通知を有効にする必要があります。

これらのイベントを受け取るようにスキルを設定する場合は、スキルイベントを参照してください。

イベントの形式

イベントが公開されてスキルに戻ってくると、次のような形式になっています。サブスクリプションのリストには、ユーザーが現在サブスクリプションを行っているイベントのリストが含まれます。ユーザーがイベントのサブスクリプションを解除した場合、このリストには、このユーザーが引き続きスキルからの受け取りのサブスクリプションを行っている、残りのイベントタイプが含まれます。サブスクリプションのリストが空の場合、このユーザーはスキルのすべてのイベントタイプのサブスクリプションを解除しています。

{
  "version": "string",
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string"
      },
      "apiEndpoint": "https: //api.amazonalexa.com"
    }
  },
  "request": {
    "type": "AlexaSkillEvent.ProactiveSubscriptionChanged",
    "requestId": "string",
    "timestamp": "string",
    "body": {
      "subscriptions": [
        {
          "eventName": "string"
        }
      ]
    }
  }
}