通知API
Alexa通知REST APIを使用すると、ユーザーに通知を送信できます。
通知タイプ
このAPIでは、1回のリクエストで最大100個の別々のユニットに通知を配信できます。以下のいずれかの通知タイプを指定できます。
- デバイス通知 - 画面のないAlexa搭載デバイスの場合、デバイス通知は黄色いリングとチャイム音になります。画面付きのデバイスの場合、デバイス通知はバナーと固定通知インジケーターになります。
- お知らせ - デバイスの画面の有無にかかわらず、Alexaはお知らせを音声で通知します。画面付きのデバイスでは、画面にもメッセージが表示されます。
- 固定視覚アラート - 固定視覚アラートは、画面付きのデバイスでのみ使用できます。固定視覚アラートは、有効期限が切れるまで、またはゲストや居住者が消去するまで画面に表示される通知です。
APIエンドポイント
通知APIのエンドポイントは、https://api.amazonalexa.com
です。
認証
すべてのAPIリクエストには認可ヘッダーが必要であり、その値には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トークン}
リクエスト本文の例
以下は、デバイス通知の例です。
{
"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": "ja-JP",
"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": "ja-JP",
"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": "ja-JP",
"document": {
"type": "Link",
"src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"
},
"datasources": {
"displayText": {
"title": "サンプルの通知タイトルです。",
"body": "サンプルの通知テキストです。"
},
"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です。 |
文字列 |
◯( |
|
|
文字列 |
✕ |
|
|
文字列 |
✕ |
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。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トークン}
リクエストのパスパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
ユニットIDです。形式は |
文字列 |
◯ |
|
受信者のタイプです。 値は |
文字列 |
◯ |
|
通知の配信タイプです。 値は |
文字列 |
◯ |
リクエスト本文の例
リクエストの本文はありません。
リクエスト本文のパラメーター
リクエストの本文はありません。
応答ヘッダー
Host
値は、リクエストのHost
値と同じになります。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トークン}
リクエスト本文の形式
{
"query": {},
"paginationContext": {
"maxResults": 10,
"nextToken": "paginationTokenString"
}
}
リクエストのパラメーター
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
フィルタリング条件を提供するオブジェクトです。このオブジェクトには、 クエリは以下のルールに従う必要があります。
|
オブジェクト |
◯ |
|
1回のリクエストで返される項目の最大数です。最小値は 1、最大値は 100です。 |
整数 |
✕ |
|
前回の応答に続くデータがある場合に、後続データを取得するために使用するトークンです。このフィールドには、nullまたはサーバーから返された有効な値を指定する必要があります。 |
文字列 |
✕ |
Queryオブジェクト
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
論理 |
配列 |
✕ |
|
論理 |
配列 |
✕ |
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": "ja-JP",
"document": {
"type": "Link",
"src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"
},
"datasources": {
"displayText": {
"title": "サンプルタイトル",
"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 月 16 日