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

Note: Sign in to the developer console to build or publish your skill.

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

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

注：プロアクティブイベントAPIは、24時間以内にユーザーに送信する通知の数を制限します。Amazonは、ユーザーからのフィードバックに基づいてこの制限を調整する可能性があります。特定のスキルのユーザーに対して通知制限に達すると、APIはステータスコード432番とともに"Too many notifications for customer"の応答を返します。通知制限は公開中スキルにのみ適用され、開発中スキルでプロアクティブイベントAPIの開発エンドポイントの1つを使用する場合には適用されません。

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

スキルにプロアクティブイベントを追加する
通知APIから移行する
イベントとスキーマについて
ローカライズ対応を追加する
SMAPIを使用したプロアクティブイベントを定義する
Alexaへのプロアクティブイベントの送信を準備する
ProactiveEvents APIを呼び出す

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

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

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

通知APIから移行する

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

注：ProactiveEvents機能でスキルが認定されてから移行が完了するまでに、最大で48時間かかる場合があります。

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

スキルを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`	この応答には、以下の理由が考えられます。認可サーバーでコンテンツタイプがサポートされていません。つまり、これはapplication/x-www-form-urlencodedではありません。リクエストに次のいずれかの必須パラメーターが不足しています。`grant-type`、`scope`、`client_id`、`client_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/`
リクエストヘッダー	`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アプリで通知を有効にする必要があります。

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

イベントの形式

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

重要：これらのイベントは順不同で到着する可能性があるため、スキルサービスがイベントのtimestampを使用して、ユーザーの最新のサブスクリプション状態を正しく記録するようにしてください。

{
  "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 日