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



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

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

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

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

  1. ユーザーに送信するイベントを表すスキーマを選択します。
  2. プロアクティブイベント機能を使用して、スキルマニフェストを更新します。詳細については、SMAPIを使用したプロアクティブイベントを定義するを参照してください。
  3. Alexaアプリの通知設定ページで、スキルの通知を有効にします。
  4. プロアクティブイベントを送信し、Alexa搭載デバイスで通知を受信できることを確認します。詳細については、Alexaへのプロアクティブイベントの送信を準備するProactiveEvents APIを呼び出すを参照してください。
  5. スキルの認定を申請します。詳細については、スキルをテストして認定を申請するを参照してください。

通知APIから移行する

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

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

開発者は、ユーザーに通知するイベントを表すスキーマを選択し、これらのイベントをProactiveEvents APIに送信します。これらのイベントに関する通知を受け取るようにスキルからサブスクリプションを行ったユーザーは、Alexa通知を受信します。スキーマはASKによって定義されています。詳細については、プロアクティブイベントのスキーマを参照してください。

スキルでは、ユーザーエンゲージメントを高めたいテーマを表現した、さまざまなスキーマを使用できます。これにより、ユーザーはこのようなテーマと対話できるようになります。スキルには、同じスキーマのインスタンスを複数実装することはできません。

利用を開始するには、SMAPI(スキル管理API)を使用してスキルを設定する際に、最初にプロアクティブイベント機能を追加する必要があります。スキルによって送信されるイベントを設定する場合、事前定義された一連のスキーマ定義から、イベント内容に沿ったものを選択する必要があります。

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

{
    "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": "Amazon"
                }
            ],
    "relevantAudience": {
        "type": "Unicast",
        "payload": {
            "user": "amzn1.ask.account.<identifier>"
        }
    }
}

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

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

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

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

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

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

以下は、ローカライズされたリソースをイベントAMAZON.WeatherAlert.Activatedに伝える方法を示した例です。

{
  "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オブジェクトがあります。イベントの公開を指定するときは、次の例に示すように、権限としてalexa::devices:all:notifications:writeを含める必要があります。次の例には、2つのプロアクティブイベント 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:040623927470:function:sampleSkill"
    },
    "subscriptions": [
      {
        "eventName": "SKILL_PROACTIVE_SUBSCRIPTION_CHANGED"
      }
    ],
    "regions": {
      "NA": {
        "endpoint": {
          "uri": "arn:aws:lambda:us-east-1:040623927470:function:sampleSkill"
        }
      }
    }
  } 
フィールド 説明
events スキルの宣言をサポートする1​​つ以上のイベントを含む最上位のオブジェクトです。 オブジェクト
events.publications eventNameオブジェクトの配列です。それぞれに、ProactiveEvents APIがサポートするイベントの名前が含まれます。 配列
events.publications.eventName ProactiveEvents APIがサポートするイベントの名前である列挙値です。 列挙

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": [array of localized attributes],
    "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": [array of localized attributes],
    "relevantAudience": {
        "type": "Multicast",
        "payload": {}
    }
}

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が、イベントの前のインスタンスに置き換わります。

入力を検証する

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

これらの入力検証テストに失敗したものがあった場合、ステータスコード400(Bad Request)が返されます。

イベントのべき等性

ProactiveEvents APIは、クライアント提供のreferenceIdと、skillIdおよびcustomerIdとの組み合わせに基づいたべき等性を持ちます。

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

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

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

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

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

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

イベントの形式

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

{
    "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"
            }]
        }
    }
}