プロアクティブイベントAPIリファレンス
プロアクティブイベントAPIを使用すると、Alexaにイベントを送信できます。イベントとは、ユーザーが興味を持つと考えられる、事実に基づくデータのことです。イベントを受信すると、Alexaは、これらのイベントを受け取るよう選択したユーザーに、プロアクティブに情報を配信します。現在、このAPIは、Alexa通知というプロアクティブチャネルを1つサポートしています。将来的にプロアクティブチャネルが追加されると、新しいAPIを統合しなくても、追加のチャネルを利用できるようになります。
ユーザーが自分で、スキルからイベントの通知を受け取るよう選択できるため、Alexaからプロアクティブなメッセージが届いても、ユーザーが困惑することはありません。このAPIを使用すると、開発者はユーザー別のイベントを送信できるので、ユーザーに応じた通知をすることができます。反対に、スキルから通知を受け取るよう選択したすべてのユーザーに。一斉送信でイベントを通知することも可能です。たとえば、天気スキルからは天気に関するアラートを1つだけ送信し、その後Alexaが関心のあるすべてのユーザーに配信するということができます。
プロアクティブイベントのスキルデモで、プロアクティブイベントを使用してサンプルスキルを作成してみてください。
- スキルにプロアクティブイベントを追加する
- 通知APIから移行する
- イベントとスキーマについて
- ローカライズ対応を追加する
- SMAPIを使用したプロアクティブイベントを定義する
- Alexaへのプロアクティブイベントの送信を準備する
- ProactiveEvents APIを呼び出す
スキルにプロアクティブイベントを追加する
プロアクティブイベントをスキルに追加するための高レベルプロセスは以下のとおりです。
- ユーザーに送信するイベントを表すスキーマを選択します。
- プロアクティブイベント機能を使用して、スキルマニフェストを更新します。詳細については、SMAPIを使用したプロアクティブイベントを定義するを参照してください。
- スキルサービスを更新して、注文の配達が完了したときなど、特定の条件が発生した場合にユーザーにプロアクティブイベントを送信します。
- スキルのエンドユーザーとしてAlexaデバイスをセットアップし、ユーザーエクスペリエンスをテストします。Alexaアプリの通知設定ページで、スキルの通知を有効にします。エンドユーザーとして、プロアクティブイベントを受け取るのに必要な権限を提供したことになります。スキルが公開中の場合は、ユーザーは同様にAlexaアプリの通知を有効にして、プロアクティブイベント通知を有効にします。ユーザーがスキルを使用すると、Alexaアプリでこの変更を行うようにプロンプトが出されます。
- 開発者コンソールのテストセクションを開きます。開発者がエンドユーザーとなってスキルをテストします。プロアクティブイベントを送信し、Alexa搭載デバイスで通知を受信できることを確認します。詳細については、Alexaへのプロアクティブイベントの送信を準備するとProactiveEvents APIを呼び出すを参照してください。
- スキルの認定を申請します。詳細については、スキルをテストして認定を申請するを参照してください。認定が完了すると、ユーザーがスキルにアクセスできるようになります。
通知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日月曜日までにお届け予定です」
ローカライズ対応を追加する
プロアクティブイベントAPIは、localizedAttributes
フィールドのローカライズされたコンテンツを許可しています。このコンテンツは、イベントに含まれていません。APIはイベントの本文からローカライズされたコンテンツを参照します。列挙値はすべて自動的にローカライズされます。event
フィールドの名前は、一切ローカライズされません。
以下は、ローカライズされたリソースをイベントAMAZON.WeatherAlert.Activated
のevent.payload.weatherAlert.source
に伝える方法を示した例です。この場合、localizedAttributes
の配列に含まれるロケールは1つのみですが、配列localizedAttributes
に要素を追加して、適宜追加ロケールをサポートすることができます。
{
"event": {
"name": "AMAZON.WeatherAlert.Activated",
"payload": {
"weatherAlert": {
"source": "localizedattribute:source",
"alertType": "TORNADO"
}
}
},
"localizedAttributes": [
{
"locale": "en-US",
"source": "Example Weather Corp"
}
]
}
SMAPIを使用したプロアクティブイベントを定義する
スキル管理API(SMAPI)を使用すると、スキルがユーザーに提供するイベントを定義できます。
イベントはスキルマニフェストの一部として定義します。スキル管理API(SMAPI)を使用してイベントの作成や読み込み、削除ができます。SMAPIを使ってスキルマニフェストを変更する方法については、スキルの管理を参照してください。
スキルマニフェストには、イベントの定義をサポートするために、events.publications
オブジェクトがあります。events.subscriptions
オブジェクトは、ユーザーサブスクリプションが変化したことを示します。これはオプションです。
マニフェストはpermissions
オブジェクトも含む必要があり、以下の例に示すようにalexa::devices:all:notifications:write
をpermissions.name
値として含んでいなければなりません。
マニフェストは、スキルに含めているプロアクティブイベントを指定する必要があります。この例では、AMAZON.OrderStatus.Updated
とAMAZON.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=xxxx |
client_secret
|
開発者コンソールのClientSecret 値です。 |
client_secret=xxxx |
scope |
値はalexa::proactive_events である必要があります。 |
scope=alexa::proactive_events |
ClientIdとClientSecretの値を確認する
まず、通知権限が有効になっているマニフェストでスキルをデプロイされていることを確認します。
その後、さまざまな方法でClientId
とClientSecret
にアクセスできます。
- 開発者コンソールでスキルを選択します。次に、ビルドタブを選択し、アクセス権限セクションまで下にスクロールし、ページ下部のAlexaスキルメッセージングで
ClientId
とClientSecret
の値を確認します。 - スキル認証情報APIを使用して、
ClientId
とClientSecret
の値にアクセスします。 - ASK CLIのget-skill-credentials smapiサブコマンドを使用します。
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
|
この応答には、以下の理由が考えられます。
|
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/ |
リクエストヘッダー |
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 |
文字列 | 必須 | サービスが通知をRecent からPrevious へ自動的に変更する日付と時刻です(ISO 8601形式)。expiryTime 値に設定できる最大値は24時間であり、最小値は5分です。 |
event |
オブジェクト | 必須 | ユーザーに送信されるイベントデータです。このイベントに関連付けられているスキーマに準拠します。 |
localizedAttributes |
配列 | 必須 | ローカライゼーションのサポートが必要な一連のイベントアトリビュートを含む項目のリストです。詳細については、ローカライズ対応を追加するを参照してください。 |
relevantAudience |
オブジェクト | 必須 | このイベントの対象ユーザーです。 |
relevantAudience.type |
enum | 必須 | このイベントの対象ユーザーです。イベントをサブスクリプションしているすべてのユーザーを対象にする場合はMulticast を使用し、イベントごとに実際のuserId で対象を指定する場合はUnicast を使用します。 |
relevantAudience.payload |
オブジェクト | 必須 | relevantAudience.type がMulticast に設定されている場合は、payload オブジェクトは空ですが、その場合でも必須です。 |
relevantAudience.payload.user |
文字列 | relevantAudience.type がUnicast に設定されている場合は必須です。 |
イベントの対象の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です。 |
432 | Too many requests for customer | ユーザーへの通知が多すぎます。 |
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"
}
]
}
}
}
最終更新日: 2023 年 01 月 27 日