通知API
Alexa通知REST APIを使用して、ユーザーに通知を送信することができます。
通知タイプ
本APIは、1回のリクエストで最大100台のユニットに通知を配信することができます。以下のいずれかの通知タイプを指定できます。
- デバイス通知 – 画面が付いていないAlexa搭載デバイスでは、デバイス通知は黄色のライトリングとチャイム音になります。画面付きデバイスの場合、デバイス通知はバナーと永続通知インジケーターになります。
- アナウンス – 画面の有無にかかわらず、音声でアナウンスします。画面付きのデバイスでは、画面上にメッセージも表示されます。
- 固定視覚アラート – 固定視覚アラートは、画面付きのデバイスにのみ有効です。固定視覚アラートは、期限が切れるか、ゲストまたは居住者が解除するまで画面に表示される通知です。
APIエンドポイント
通知APIのエンドポイントは、https://api.amazonalexa.com
です。
認証
すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。
操作
通知APIには、以下の操作があります。
操作 | HTTPメソッドとURI |
---|---|
| |
| |
|
通知を送信する
ユーザーに通知を送信するには、POST /v3/notifications
を呼び出します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
リクエストの形式
POST /v3/notifications HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエスト本文の例
以下は、デバイス通知の例です。
{
"recipients": [
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId1}"
},
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId2}"
}
],
"notification": {
"variants": [
{
"type": "DeviceNotification",
"content": {
"variants": [
{
"type": "SpokenText",
"values": [
{
"locale": "en-US",
"text": "Example notification text."
}
]
}
]
}
}
]
}
}
以下は、アナウンスの例です。
{
"recipients": [
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId1}"
},
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId2}"
},
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId3}"
}
],
"notification": {
"variants": [{
"type": "Announcement",
"content": {
"variants": [{
"type": "SpokenText",
"values": [{
"locale": "en-US",
"text": "Example notification text."
}]
}]
}
}]
}
}
以下は、固定視覚アラートの例です。
{
"recipients": [
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId1}"
},
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId2}"
},
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId3}"
},
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId4}"
}
],
"notification": {
"variants": [{
"type": "PersistentVisualAlert",
"content": {
"variants": [{
"type": "V0Template",
"values": [{
"locale": "en-US",
"document": {
"type": "Link",
"src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"
},
"datasources": {
"displayText": {
"title": "Example notification title.",
"body": "Example notification text."
},
"background": {
"backgroundImageSource": "https://www.example.com/image.jpg"
}
}
}]
}]
},
"dismissalTime": "2021-04-30T10:00:00.00Z"
}],
"referenceId": "595973fd-5b66-4970-9401-53f19142aa48"
}
}
リクエスト本文のパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
通知の受け取り側。 |
配列 |
◯ |
|
受け取り側のタイプ: |
列挙 |
◯ |
|
ユニットID。 注: 1リクエストにつきユニットIDの最大数は100です。
|
文字列 |
◯ |
|
通知オブジェクト。 |
オブジェクト |
◯ |
|
通知の配信タイプ: |
列挙 |
◯ |
|
通知コンテンツは、開発者が、発話および画面表示を目的とするコンテンツの各種バリアントを指定するのに役立ちます。 |
オブジェクト |
◯ |
|
エンドユーザーに配信されるロケール固有の通知コンテンツ。 |
配列 |
◯ |
|
コンテンツのタイプ: |
列挙 |
◯ |
|
コンテンツ値の配列。配列内の各要素は、ローカライズされたテキスト入力です。 |
配列 |
◯ |
|
発話テキストが出力されるロケール。IETF BCP 47形式で指定します。 |
文字列 |
◯ |
|
プレーンテキスト形式の発話テキスト。最大長は1024文字または2048バイトです。 |
文字列 |
◯ |
|
|
オブジェクト |
◯( |
|
|
文字列 |
◯( |
|
|
文字列 |
◯( |
|
|
オブジェクト |
◯( |
|
|
オブジェクト |
◯( |
|
|
文字列 |
◯( |
|
|
文字列 |
◯( |
|
背景の特徴を指定するオブジェクト。 |
オブジェクト |
✕ |
|
背景画像のURL。 |
文字列 |
◯( |
|
|
文字列 |
✕ |
|
|
文字列 |
✕ |
応答ヘッダー
HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文の例
すべての受け取り側で処理が正常に行われた場合。
{
"type": "ALL_SUCCESS",
"message": "All message published successfully.",
"successResults": [
{
"id": "amzn1.alexa.unit.did.<unitId1>",
"referenceId": "0176a8dd-1f79-4933-a3a4-8e76fc43fd7a"
},
{
"id": "amzn1.alexa.unit.did.<unitId2>",
"referenceId": "475dc098-2319-11ec-9621-0242ac130002"
}
],
"errors": [
]
}
一部の受け取り側へのパブリッシュに失敗した場合。
{
"type": "PARTIAL_SUCCESS",
"message": "1 of 3 failed to publish.",
"successResults": [
{
"id": "amzn1.alexa.unit.did.<unitId1>",
"referenceId": "0176a8dd-1f79-4933-a3a4-8e76fc43fd7a"
},
{
"id": "amzn1.alexa.unit.did.<unitId2>",
"referenceId": "475dc098-2319-11ec-9621-0242ac130002"
}
],
"errors": [
{
"id": "amzn1.alexa.unit.did.<unitId3>",
"status": 400,
"errorCode": "Bad Request",
"errorDescription": "Request or recipient ID is malformed."
}
]
}
すべてのメッセージのパブリッシュに失敗した場合。失敗の理由は各受け取り側によってさまざまです。
{
"type": "ALL_FAILED",
"message": "All messages failed to publish.",
"successResults": [
],
"errors": [
{
"id": "amzn1.alexa.unit.did.<unitId2>",
"status": 403,
"errorCode": "Forbidden",
"errorDescription": "Request is forbidden."
},
{
"id": "amzn1.alexa.unit.did.<unitId2>",
"status": 400,
"errorCode": "Bad Request",
"errorDescription": "Request or recipient ID is malformed."
},
{
"id": "amzn1.alexa.unit.did.<unitId3>",
"status": 400,
"errorCode": "Bad Request",
"errorDescription": "Unit already has active PersistentVisualAlert."
}
]
}
応答のパラメーター
アクションが成功したら、サービスはHTTP 202応答を戻します。サービスから、以下のデータがJSON形式で返されます。
フィールド | 説明 | 型 |
---|---|---|
|
簡単な説明。 |
文字列 |
|
結果の詳細な説明。 |
文字列 |
|
正常に処理されたユニットのリスト。 |
配列 |
|
正常に処理されたユニットID。 |
文字列 |
|
ユニットの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
|
失敗したユニットIDのリスト。 |
配列 |
|
処理に失敗したユニットID。 |
文字列 |
|
エラーのステータス。 |
整数 |
|
簡単なエラーコード。 |
文字列 |
|
ユニットのエラーに関する詳細な説明。 |
文字列 |
エラー応答の例
アクション全体が失敗した場合、サービスは202以外のHTTP応答を返します。サービスから、以下のデータがJSON形式で返されます。
{
"type": "Unauthorized",
"message": "HTTP 401 Unauthorized"
}
エラー応答イベント
フィールド | 説明 | 型 |
---|---|---|
|
簡単な説明。 |
文字列 |
|
結果の詳細な説明。 |
文字列 |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
202 |
Accepted |
リクエストは受け付けられました。個々の受け取り側のステータスは |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
操作を実行する権限がユーザーにありません。 |
429 |
Too many requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サーバーが一時的に使用できません。 |
ユニットIDで通知を削除する
ユニットに関連付けられているすべての通知を削除するには、DELETE /v3/notifications?recipients.id={unitid}&recipients.type=Unit¬ification.variants.type=DeviceNotification
を呼び出します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
リクエストの形式
DELETE /v3/notifications?recipients.id={unitid}&recipients.type=Unit¬ification.variants.type=DeviceNotification
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {LWA Token}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ユニットID。形式は |
文字列 |
◯ |
|
受け取り側のタイプ: |
文字列 |
◯ |
|
通知の配信タイプ: |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答ヘッダー
HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: {request-id}
応答ヘッダーのパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文の例
成功した応答には、本文は含まれません。削除リクエストを正常に受信すると、サーバーはHTTP 202 OKステータス応答を返します。指定されたユニットに削除するDeviceNotification
タイプの通知がない場合にも、サーバーはこの応答を返します。
エラー応答の例
アクション全体が失敗した場合、サービスは202以外のHTTP応答を返します。サービスから、以下のデータがJSON形式で返されます。
{
"type": "Unauthorized",
"message": "HTTP 401 Unauthorized"
}
エラー応答イベント
フィールド | 説明 | 型 |
---|---|---|
|
簡単な説明。 |
文字列 |
|
結果の詳細な説明。 |
文字列 |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
202 |
Accepted |
指定されたユニットに対する削除リクエストが受け付けられました。このユニットのすべての |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
操作を実行する権限がユーザーにありません。 |
429 |
Too many requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サーバーが一時的に使用できません。 |
固定視覚アラートを照会する
ユニットリスト内の固定視覚アラートを照会するには、POST /v3/notifications/query
を呼び出します。
この操作は以下の国で使用できます。
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
米国、英国、フランス、カナダ、イタリア、ドイツ |
米国 |
リクエストの形式
POST /v3/notifications/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
リクエスト本文の形式
{
"query": {},
"paginationContext": {
"maxResults": 10,
"nextToken": "paginationTokenString"
}
}
リクエストのパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
フィルタリング条件を提供するオブジェクト。このオブジェクトは、使用可能なフィールドを1つだけ持ち、 クエリは、以下の規則に従います。
|
オブジェクト |
◯ |
|
1つのリクエストで返される項目の最大数。最小値: 1。最大値: 100。 |
整数 |
✕ |
|
前の応答内の後続データを取得するために使用するトークン。このフィールドはnullか、サーバーから返された有効な値である必要があります。 |
文字列 |
✕ |
クエリオブジェクト
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
論理 |
配列 |
✕ |
|
論理 |
配列 |
✕ |
1つ以上のユニットのアクティブな固定視覚アラート通知を取得するリクエスト本文の例
以下は、1つ以上のユニットのアクティブな固定視覚アラート通知を取得するリクエスト本文の例です。
{
"query": {
"and": [
{
"or": [
{
"match": {
"recipients.id": "U1"
}
},
{
"match": {
"recipients.id": "U2"
}
}
]
},
{
"match": {
"recipients.type": "Unit"
}
},
{
"match": {
"notification.variants.type": "PersistentVisualAlert"
}
}
]
},
"paginationContext": {
"maxResults": 10,
"nextToken": "paginationTokenString"
}
}
1つ以上の参照IDを使用してアクティブな通知を取得するリクエスト本文の例
以下は、1つ以上の参照IDを使用してアクティブな通知を取得するリクエスト本文の例です。
{
"query": {
"or": [
{
"match": {
"notification.referenceId": "R1"
}
},
{
"match": {
"notification.referenceId": "R2"
}
}
]
},
"paginationContext": {
"maxResults": 10,
"nextToken": "paginationTokenString"
}
}
応答ヘッダー
HTTP/1.1 200 OK
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: {request-id}
応答ヘッダーのパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
リクエストの一意のIDです。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。 |
文字列 |
応答本文の例(成功)
以下は、完全または部分的に成功した応答の例です。
{
"paginationContext": {
"nextToken": "paginationTokenString"
},
"successResults": [
{
"recipients": [
{
"type": "Unit",
"id": "amzn1.alexa.unit.did.{unitId1}"
}
],
"notification": {
"variants": [
{
"type": "PersistentVisualAlert",
"content": {
"variants": [
{
"type": "V0Template",
"values": [
{
"locale": "en-US",
"document": {
"type": "Link",
"src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"
},
"datasources": {
"displayText": {
"title": "Example title",
"body": "Example body"
}
},
"background": {
"backgroundImageSource": "https://s3.amazon.com/example_background_large.jpg"
}
}
]
}
]
},
"dismissalTime": "2021-04-30T10:00:00.00Z"
}
],
"referenceId": "595973fd-5b66-4970-9401-example"
}
}
]
}
応答本文の例(エラー)
以下は、エラー応答の例です。
{
"type": "BAD_REQUEST",
"message": "Invalid payload format, please check documentation."
}
応答本文のパラメーター
フィールド | 説明 | 型 |
---|---|---|
|
ページ分割情報を含むオブジェクト。存在しない場合、すべての評価結果が既に返されています。 |
オブジェクト |
|
固定視覚アラートを照会するための次の呼び出しで使用する継続トークン。このフィールドがnullの場合、すべての評価結果が既に返されています。このフィールドがnullでない場合、次のページにまだ結果があります。 |
文字列 |
|
固定視覚アラート通知のリスト。 |
配列 |
|
通知の受け取り側。 |
配列 |
|
受け取り側のタイプ: |
列挙 |
|
ユニットID。形式は |
文字列 |
|
ユニットとアクティブな通知を含むオブジェクト。 |
配列 |
|
通知の配信タイプ: |
列挙 |
|
発話および画面表示を目的とする通知コンテンツの各種バリエーションを指定できるオブジェクトです。 |
オブジェクト |
|
エンドユーザーに配信されるロケール固有の通知コンテンツ。 |
配列 |
|
コンテンツのタイプ: |
列挙 |
|
コンテンツ値の配列。配列内の各要素は、ローカライズされたテキスト入力です。 |
配列 |
|
発話テキストが出力されるロケール。IETF BCP 47形式で指定します。 |
文字列 |
|
|
オブジェクト |
|
|
文字列 |
|
|
文字列 |
|
|
オブジェクト |
|
|
オブジェクト |
|
|
文字列 |
|
|
文字列 |
|
背景の特徴を指定するオブジェクト。 |
オブジェクト |
|
背景画像のURL。 |
文字列 |
|
|
文字列 |
|
|
文字列 |
HTTP応答コード
ステータスコード | 名前 | 説明 |
---|---|---|
200 |
OK |
リクエストが成功しました。 |
400 |
Bad Request |
リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。 |
401 |
Unauthorized |
アクセストークンがないか、期限切れか、無効です。 |
403 |
Forbidden |
操作を実行する権限がユーザーにありません。 |
429 |
Too Many Requests |
リクエストが制限されています。 |
500 |
Internal Server Error |
内部サービスエラーのためリクエストを処理できませんでした。 |
503 |
Service Unavailable |
サービスが一時的に使用できません。 |
最終更新日: 2023 年 03 月 06 日