通知API


通知API

Alexa通知REST APIを使用すると、ユーザーに通知を送信できます。

通知タイプ

このAPIでは、1回のリクエストで最大100個の別々のユニットに通知を配信できます。以下のいずれかの通知タイプを指定できます。

  • デバイス通知 - 画面のないAlexa搭載デバイスの場合、デバイス通知は黄色いリングとチャイム音になります。画面付きのデバイスの場合、デバイス通知はバナーと固定通知インジケーターになります。
  • アナウンス - デバイスの画面の有無にかかわらず、Alexaは音声でアナウンスします。画面付きのデバイスでは、画面にもメッセージが表示されます。
  • 固定視覚アラート - 固定視覚アラートは、画面付きのデバイスでのみ使用できます。固定視覚アラートは、有効期限が切れるか、ゲストや居住者がアラートを解除するまで画面に表示される通知です。

APIエンドポイント

リクエストヘッダーでは、組織が所在する地域に応じて、Hostを以下のいずれかに設定してください。

エンドポイント

カナダ、米国

https://api.amazonalexa.com

ドイツ、スペイン、フランス、イタリア、英国

https://api.eu.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with Amazon(LWA)から取得したアクセストークンが入ります。

操作

通知APIには、以下の操作が用意されています。

操作 HTTPメソッドとURI

通知を送信する

POST /v3/notifications

ユニットIDを指定して通知を削除する

DELETE /v3/notifications

すべての通知を削除する

POST /v3/notifications/delete

固定視覚アラートを照会する

POST /v3/notifications/query

通知を送信する

ユーザーに通知を送信するには、POST /v3/notificationsを呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality 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": "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"
    }
}

リクエスト本文のパラメーター

フィールド 説明 必須

recipients

通知の受信者。

配列

recipients[].type

受信者のタイプ。 値はUnitです。

列挙

recipients[].id

ユニットID。"amzn1.alexa.unit.did.{unitId}"形式で表します。

文字列

notification

通知オブジェクト。

オブジェクト

notification.variants[].type

通知の配信タイプ。 DeviceNotificationAnnouncementPersistentVisualAlertのいずれかです。通知タイプを参照してください。

列挙

notification.variants[].content

通知コンテンツ。開発者は、読み上げ用および画面表示用に、コンテンツの各種バリアントを指定することができます。

オブジェクト

notification.variants[].content.variants[]

エンドユーザーに配信される、ロケール固有の通知コンテンツ。

配列

notification.variants[].content.variants[].type

コンテンツのタイプ。 SpokenText(配信タイプがDeviceNotificationおよびAnnouncementの場合)、V0Template(配信タイプがPersistentVisualAlertの場合)のどちらかです。SpokenTextは、ローカライズされたテキスト入力を表します。V0Templateは、APLドキュメントを使用して通知をレンダリングするために必要なデータを格納します。APLドキュメントとは、画面付きのデバイスに表示するテンプレートを定義するJSONオブジェクトです。APLドキュメントは構造とレイアウトを制御します。

列挙

notification.variants[].content.variants[].values[]

コンテンツの値の配列。配列内の各要素は、ローカライズされたテキスト入力を表します。

配列

notification.variants[].content.variants[].values[].locale

読み上げテキストがレンダリングされるロケール。IETF BCP 47形式で表します。

文字列

notification.variants[].content.variants[].values[].text

プレーンテキスト形式の発話テキスト。最大長は1024文字または2048バイトです。

文字列

notification.variants[].content.variants[].values[].document

PersistentVisualAlert通知の場合)通知のレンダリングに使用するAPLドキュメント。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。

オブジェクト

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].document.type

PersistentVisualAlert通知の場合)APLドキュメントのタイプ。Linkを指定する必要があります。

文字列

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].document.src

PersistentVisualAlert通知の場合)APLドキュメントのリンク。現在サポートされているのは、"doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"のみです。

文字列

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].datasources

PersistentVisualAlert通知の場合)APLドキュメントのデータ。

オブジェクト

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].datasources.displayText

PersistentVisualAlert通知の場合)このオブジェクトには通知で表示されるテキストが含まれます。

オブジェクト

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].datasources.displayText.title

PersistentVisualAlert通知の場合)通知で表示されるタイトル。最大長は25文字です。

文字列

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].datasources.displayText.body

PersistentVisualAlert通知の場合)通知に表示される本文テキスト。最大長は60文字です。

文字列

◯(PersistentVisualAlert通知の場合)

notification.variants[].content.variants[].values[].datasources.background

背景の各要素を指定するオブジェクト。

オブジェクト

notification.variants[].content.variants[].values[].datasources.background.backgroundImageSource

背景画像のURL。

文字列

◯(notification.variants[].content.variants[].values[].datasources.backgroundを含む場合)

notification.dismissalTime

PersistentVisualAlert通知の場合)通知の有効期限の日時。ISO 8601形式で表します。これは、カードの有効期限が切れて表示画面から消去される時刻です。

文字列

notification.referenceId

PersistentVisualAlert通知の場合)新しく作成される通知の参照ID。referenceIdは、ユニット内の通知ごとに固有のUUIDです。これは、以前に配信された通知を更新する必要がある場合に使用します。

文字列

応答ヘッダー

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明

X-Amzn-RequestId

リクエストの一意の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形式で返されます。

フィールド 説明

type

簡単な説明。

文字列

message

結果の詳細な説明。

文字列

successResults

正常に処理されたユニットのリスト。

配列

successResults[].id

正常に処理されたユニットID。

文字列

successResults[].referenceId

ユニットの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

タイプがDeviceNotificationの通知の場合、referenceIdはユニットごとに作成される各通知の一意のIDです。つまり、referenceIdと通知の間には1対1のリレーションシップがあります。

タイプがPersistentVisualAlertの通知の場合、referenceIdは開発者が通知を送信するときに指定します。この場合、すべてのユニットが同じreferenceIdを持ち、referenceIdと通知の間には1対多のリレーションシップが形成されます。

文字列

errors

失敗したユニットIDのリスト。

配列

errors[].id

処理に失敗したユニットID。

文字列

errors[].status

エラーのステータス。

整数

errors[].errorCode

短いエラーコード。

文字列

errors[].errorDescription

ユニットのエラーに関する詳細な説明。

文字列

エラー応答の例

アクション全体が失敗した場合、サービスは202以外のHTTP応答を返します。サービスから、以下のデータがJSON形式で返されます。

{
    "type": "Unauthorized",
    "message": "HTTP 401 Unauthorized"
}

エラー応答の要素

フィールド 説明

type

簡単な説明。

文字列

message

結果の詳細な説明。

文字列

HTTP応答コード

ステータスコード 名前 説明

202

Accepted

リクエストが受け付けられました。個々の受信者のステータスは、successfulResultserrorsのどちらかに含まれます。

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&notification.variants.type=DeviceNotificationを呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン

米国、英国、フランス、カナダ、イタリア、ドイツ、スペイン

米国

リクエストの形式

DELETE /v3/notifications?recipients.id={unitid}&recipients.type=Unit&notification.variants.type=DeviceNotification
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {LWA Token}

リクエストのパスパラメーター

フィールド 説明 必須

recipients.id

ユニットID。amzn1.alexa.unit.did.{unitId}形式で表します。

文字列

recipients.type

受信者のタイプ。 値はUnitです。

文字列

notification.variants.type

通知の配信タイプ。有効な値は PersistentVisualAlertDeviceNotificationです。

文字列

リクエスト本文の例

リクエストの本文はありません。

リクエスト本文のパラメーター

リクエストの本文はありません。

応答ヘッダー

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: {request-id}

応答ヘッダーのパラメーター

フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

成功応答には本文はありません。削除リクエストを正常に受信すると、サーバーはHTTP 202 OKのステータス応答を返します。指定されたユニットに削除する通知タイプがない場合でも、サーバーからはこの応答が返されます。

エラー応答の例

アクション全体が失敗した場合、サービスは202以外のHTTP応答を返します。サービスから、以下のデータがJSON形式で返されます。

{
    "type": "Unauthorized",
    "message": "HTTP 401 Unauthorized"
}

エラー応答の要素

フィールド 説明

type

簡単な説明。

文字列

message

結果の詳細な説明。

文字列

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/deleteを呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality Senior Living Core

米国

米国、英国、フランス、カナダ、イタリア、ドイツ

米国、英国、フランス、カナダ、イタリア、ドイツ

米国

リクエストの形式

以下は、デバイス通知を削除する方法の例です。

POST /v3/notifications/delete
Host: api.amazonalexa.com
Content-type: application/json
Authorization: Bearer {LWA Token}

リクエスト本文の例

{
  "recipients" : [
      {
          "type": "Unit",
          "id": "amzn1.alexa.unit.did.{unitId1}"
      },
      {
          "type": "Unit",
          "id": "amzn1.alexa.unit.did.{unitId2}"
      }
   ],
  "notificationTypes" : ["PersistentVisualAlert"]  
}

リクエスト本文のパラメーター

パラメーター 説明 必須

recipients

通知を削除するユニットのIDのリスト。最小サイズは 1、最大サイズは 100です。

配列

recipients[*].type

通知を削除する受信者のタイプ。有効な値は Unitです。

列挙

recipients[*].id

通知を削除するユニットのID。"amzn1.alexa.unit.did.{id}"形式で表します。

文字列

notificationTypes

削除する通知のタイプ。有効な値は PersistentVisualAlertDeviceNotificationです。最大サイズは 1。

配列

応答ヘッダー

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: {request-id}

応答ヘッダーのパラメーター

フィールド 説明

X-Amzn-RequestId

リクエストの一意のID。問題が発生する場合、Amazonはこの値をトラブルシューティングに使用します。

文字列

応答本文の例

成功応答には本文はありません。削除リクエストを正常に受信すると、サーバーはHTTP 202 OKのステータス応答を返します。

エラー応答の例

アクション全体が失敗した場合、サービスは202以外のHTTP応答を返します。

たとえば、認証が401応答コードで失敗した場合は、次のデータがJSON形式で返されます。

{
    "type": "Unauthorized",
    "message": "The access token is missing, expired, or invalid.",
    "errors": []
}

以下は、指定されたユニットIDが無効な場合の400応答の本文の例です。

{
   "type": "Bad Request",
   "message": "Invalid payload format, please check documentation.",
   "errors": [{
        "id": "amzn1.alexa.unit.did.{unitId1}",
        "status": 400,
        "errorCode": "Bad Request",
        "errorDescription": "Invalid UnitId."
   }]
}

以下は、1つ以上のユニットIDを操作する権限がない場合の、400応答の本文の例です。

{
   "type": "Bad Request",
   "message": "Invalid payload format, please check documentation.",
   "errors": [{
        "id": "amzn1.alexa.unit.did.{unitId1}",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "User not authorized"
   },{
        "id": "amzn1.alexa.unit.did.{unitId2}",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "User not authorized"
   },{
        "id": "amzn1.alexa.unit.did.{unitId3}",
        "status": 403,
        "errorCode": "Forbidden",
        "errorDescription": "User not authorized"
   }]
}

エラー応答の要素

フィールド 説明

type

簡単な説明。

文字列

message

結果の詳細な説明。

文字列

errors

処理に失敗したユニットIDと関連するエラー情報のリスト。

文字列

errors[*].id

処理に失敗したユニットID。

文字列

errors[*].status

エラーのステータスコード。

整数

errors[*].errorCode

エラータイプを示すコード。

文字列

errors[*].errorDescription

エラーの説明。

文字列

HTTP応答コード

ステータスコード 名前 説明

202

Accepted

ユニットリストの削除リクエストが受け付けられ、処理されています。

400

Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

401

Unauthorized

アクセストークンがないか、期限切れか、無効です。

429

Too many requests

リクエストが制限されています。

500

Internal Server Error

内部サービスエラーのためリクエストを処理できませんでした。

503

Service Unavailable

サーバーが一時的に使用できません。

固定視覚アラートを照会する

ユニットのリストから固定視覚アラートを照会するには、POST /v3/notifications/queryを呼び出します。

この操作は以下の国で使用できます。

Healthcare Hospitality 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"
    }
 }

リクエストのパラメーター

フィールド 説明 必須

query

フィルタリング条件を提供するオブジェクト。このオブジェクトには、ANDまたはORのどちらかのフィールドを1つだけ含めることができます。それぞれのフィールドはリスト型です。通常、これらのフィールドは、その後に特定のアトリビュートに対するフィルタリング条件を続けて、別のAND/ORフィルタリング条件のリストを入れ子として含めることができます。照会可能なフィールドは、「.」演算子を使用してJSONからフラット化されます。

クエリは以下のルールに従う必要があります。

  • クエリは、リクエスト本文の例に示す一般的な構造のいずれかに合致する必要があります。
  • クエリには、and演算またはor演算のキーを、1つだけ含めることができます。
  • 使用できる条件はmatchのみです。

query.andは、3つの項目を含むリストで、以下の条件に従います。
  • query.and.orは、最小サイズ1、最大サイズ100のリストで、使用可能なフィールドはrecipients.idのみです。
  • recipients.typeに指定できる値はUnitのみです。
  • notifications.variants.typeに指定できる値はPersistentVisualAlertのみです。

query.orは、最小サイズ1、最大サイズ100のリストで、以下の条件に従います。
  • 使用可能なフィールドはnotification.referenceIdのみです。

オブジェクト

paginationContext.maxResults

1回のリクエストで返される項目の最大数。最小値は 1、最大値は 100です。

Integer

paginationContext.nextToken

前回の応答に続くデータがある場合に、後続データを取得するために使用するトークン。このフィールドには、nullまたはサーバーから返された有効な値を指定する必要があります。

文字列

Queryオブジェクト

フィールド 説明 必須

or

論理OR演算を使用して適用する条件。

例:{"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}

配列

and

論理AND演算を使用して適用する条件。

例:{"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}

配列

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}

応答ヘッダーのパラメーター

フィールド 説明

X-Amzn-RequestId

リクエストの一意の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."
 }

応答本文のパラメーター

フィールド 説明

paginationContext

ページ分割情報を含むオブジェクト。存在しない場合、すべての評価結果が既に返されています。

オブジェクト

paginationContext.nextToken

固定視覚アラートを照会する次回の呼び出しで使用するための継続トークン。このフィールドがnullの場合、すべての評価結果が既に返されています。このフィールドがnullでない場合、次のページにまだ結果があります。

文字列

results[*]

固定視覚アラート通知のリスト。

配列

results[*].recipients[*]

通知の受信者。

配列

results[*].recipients[*].type

受信者のタイプ。 値はUnitです。

列挙

results[*].recipients[*].id

ユニットID。"amzn1.alexa.unit.did.{unitId}"形式で表します。

文字列

results[*].notifications[*]

ユニットとアクティブな通知を含むオブジェクト。

配列

results[*].notifications[*].variants[*].type

通知の配信タイプ。 DeviceNotificationAnnouncementPersistentVisualAlertのいずれかです。通知タイプを参照してください。

列挙

results[*].notifications[*].variants[*].content

読み上げ用および画面表示用に、通知コンテンツの各種バリアントを指定するために使用できるオブジェクト。

オブジェクト

results[*].notifications[*].variants[*].content.variants[*]

エンドユーザーに配信される、ロケール固有の通知コンテンツ。

配列

results[*].notifications[*].variants[*].content.variants[*].type

コンテンツのタイプ。 SpokenText(配信タイプがDeviceNotificationおよびAnnouncementの場合)、V0Template(配信タイプがPersistentVisualAlertの場合)のどちらかです。SpokenTextは、ローカライズされたテキスト入力を表します。V0Templateは、APLドキュメントを使用して通知をレンダリングするために必要なデータを格納します。APLドキュメントとは、画面付きのデバイスに表示するテンプレートを定義するJSONオブジェクトです。APLドキュメントは構造とレイアウトを制御します。

列挙

results[*].notifications[*].variants[*].content.variants[*].values[*]

コンテンツの値の配列。配列内の各要素は、ローカライズされたテキスト入力を表します。

配列

results[*].notifications[*].variants[*].content.variants[*].values[*].locale

読み上げテキストがレンダリングされるロケール。IETF BCP 47形式で表します。

文字列

results[*].notifications[*].variants[*].content.variants[*].values[*].document

PersistentVisualAlert通知の場合)通知のレンダリングに使用するAPLドキュメント。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。

オブジェクト

results[*].notifications[*].variants[*].content.variants[*].values[*].document.type

PersistentVisualAlert通知の場合)APLドキュメントのタイプ。Linkを指定する必要があります。

文字列

results[*].notifications[*].variants[*].content.variants[*].values[*].document.src

PersistentVisualAlert通知の場合)APLドキュメントのリンク。現在サポートされているのは、"doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/defaultTemplate"のみです。

文字列

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources

PersistentVisualAlert通知の場合)APLドキュメントのデータ。

オブジェクト

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.displayText

PersistentVisualAlert通知の場合)このオブジェクトには通知で表示されるテキストが含まれます。

オブジェクト

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.displayText.title

PersistentVisualAlert通知の場合)通知で表示されるタイトル。最大長は25文字です。

文字列

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.displayText.body

PersistentVisualAlert通知の場合)通知に表示される本文テキスト。最大長は60文字です。

文字列

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.background

背景の各要素を指定するオブジェクト。

オブジェクト

results[*].notifications[*].variants[*].content.variants[*].values[*].datasources.background.backgroundImageSource

背景画像のURL。

文字列

results[*].notifications[*].dismissalTime

PersistentVisualAlert通知の場合)通知の有効期限の日時。ISO 8601形式で表します。これは、カードの有効期限が切れて表示画面から消去される時刻です。

文字列

results[*].notifications[*].referenceId

PersistentVisualAlert通知の場合)新しく作成される通知の参照ID。referenceIdは、ユニット内の通知ごとに固有のUUIDです。これは、以前に配信された通知を更新する必要がある場合に使用します。

文字列

HTTP応答コード

ステータスコード 名前 説明

200

OK

リクエストが成功しました。

400

Bad Request

リクエストの形式が正しくないか、1つ以上の必須パラメーターがありません。

401

Unauthorized

アクセストークンがないか、期限切れか、無効です。

403

Forbidden

操作を実行する権限がユーザーにありません。

429

Too Many Requests

リクエストが制限されています。

500

Internal Server Error

内部サービスエラーのためリクエストを処理できませんでした。

503

Service Unavailable

サービスが一時的に使用できません。


このページは役に立ちましたか?

最終更新日: 2023 年 11 月 30 日