通知REST APIリファレンス

通知REST APIリファレンス

Alexa通知REST APIを使用すると、Alexa Smart Properties（ASP）のゲストや居住者に通知を送信できます。音声アナウンスや視覚アナウンス、デバイス通知、固定視覚アラートから選択できます。

通知タイプ

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

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

APIエンドポイント

組織が所在する国に応じて、リクエストヘッダーのHostパラメーターを、以下のいずれかのAPIエンドポイントに設定してください。

国 エンドポイント

カナダ、米国

http://api.amazonalexa.com

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

http://api.eu.amazonalexa.com

日本

http://api.fe.amazonalexa.com

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値にはLogin with HAQM（LWA）から取得したアクセストークンが入ります。詳細については、APIアクセスを管理するを参照してください。

操作

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

操作 HTTPメソッドとURI

通知を送信する

POST /v3/notifications

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

DELETE /v3/notifications?recipients.id={unitid}&recipients.type={type}&notification.variants.type={variantType}

すべての通知を削除する

POST /v3/notifications/delete

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

POST /v3/notifications/query

通知を送信する

指定された各受信者に通知を送信します。一度に1つの通知タイプを送信できます。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

デバイスに表示できる固定視覚アラートは一度に1つです。デバイスに既にアクティブなアラートがある場合、最初のアラートが期限切れになるか解除されるまで、別の固定視覚アラートを送信することはできません。別の固定視覚アラートを送信すると失敗応答が返され、 「受信者には、リクエストされたスケジュールと重複するPersistentVisualAlertが既に存在します」という400エラーが出力されます。

また、配信が遅延するまれなシナリオもあります。これに該当するのは、新しい固定視覚アラートを送信し、そのアラートをすぐに解除して、別のアラートを送信しようとした場合です。2番目の固定視覚アラートが表示されるまでに、10秒の遅延が発生します。

リクエスト

通知を送信するには、/v3/notificationsリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v3/notifications HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

次の例は、各通知タイプの通知リクエスト本文を示しています。

リクエスト本文のプロパティ

プロパティ 説明 型 必須

recipients

通知の受信者のリスト。
リストの項目の最大数は 100です。

オブジェクトの配列

◯

recipients[].type

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

文字列

◯

recipients[].id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

notification

通知を記述します。

オブジェクト

◯

notification.variants

通知バリアントのリスト。

オブジェクトの配列

◯

notification.variants[].type

通知の配信タイプ。タイプの詳細については、通知タイプを参照してください。
有効な値は DeviceNotification、Announcement、PersistentVisualAlertのいずれかです。

文字列

◯

notification.variants[].content

通知のコンテンツ。このオブジェクトの固有のフィールドは、通知のtypeによって異なります。

Contentオブジェクト

◯

notification.dismissalTime

通知の有効期限の日時。通知のtypeがPersistentVisualAlertの場合にのみ有効です。
ゲストや居住者が手動で解除しない限り、通知はこの日時までデバイスに表示され続けます。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

×

notification.referenceId

新しく作成される通知の参照ID。
通知のtypeがPersistentVisualAlertの場合にのみ有効です。
referenceIdは、ユニット内の通知ごとに固有です。既に配信済みの固定視覚アラートを更新する場合に指定します。

文字列

×

応答

正常に完了すると、HTTP 202 Acceptedと共に、発行された通知とエラーになった通知のリストが返されます。リクエスト全体が失敗した場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、すべての受信者への通知の送信が正常に完了したことを示す応答の例です。

以下は、一部の受信者への固定通知の送信が正常に完了し、ほかの受信者への送信は失敗したことを示す応答の例です。

以下は、すべての受信者への通知の送信が失敗したことを示す応答の例です。この例では、失敗の理由は受信者ごとに異なります。

応答本文のプロパティ

プロパティ 説明 型

type

結果の簡単な説明。

文字列

message

結果の詳細な説明。

文字列

successResults

成功した通知結果のリスト。

オブジェクトの配列

successResults[].id

通知が送信されたユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

successResults[].referenceId

ユニットと通知の一意の参照識別子。問題が発生する場合、HAQMはこの値をトラブルシューティングに使用します。

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

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

文字列

errors

（オプション）エラーの結果のリスト。

配列

errors[].id

通知に失敗したユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

errors[].status

失敗したリクエスト項目に対するHTTP応答コード。

整数

errors[].errorCode

短いエラーコード。

文字列

errors[].errorDescription

読み取り可能なエラーメッセージ。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーの説明の内容に依存するビジネスロジックは構築しないでください。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は後続のリクエストで使用します。結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

202 Accepted

応答本文に成功とエラーの結果のリストが含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

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

指定されたユニットから、指定されたタイプの通知をすべて削除します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

通知を削除するには、/v3/notificationsリソースに対してDELETEリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

DELETE /v3/notifications?recipients.id={unitid}&recipients.type={recipientType}&notification.variants.type={variantType}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

unitid

クエリ

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

recipientType

クエリ

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

文字列

◯

variantType

クエリ

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

文字列

◯

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

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

リクエスト本文のプロパティ

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

応答

正常に完了すると、HTTP 202 Acceptedが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

応答の本文はありません。

応答本文のプロパティ

応答の本文はありません。

HTTPステータスコード

ステータス 説明

202 Accepted

指定されたユニットからすべての通知が削除されました。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

すべての通知を削除する

指定されたユニットに関連付けられている通知をすべて削除します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

通知を削除するには、/v3/notifications/deleteリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

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

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

クリップボードにコピーされました。

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

リクエスト本文のプロパティ

プロパティ 説明 型 必須

recipients

通知の受信者のリスト。
リストの項目の最大数は 100です。

オブジェクトの配列

◯

recipients[].type

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

文字列

◯

recipients[].id

通知を削除するユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

◯

notificationTypes

削除する通知のタイプ。
最大サイズは 1です。
有効な値は次のとおりです。 PersistentVisualAlert、DeviceNotificationです。

文字列の配列

◯

応答

正常に完了すると、HTTP 202 Acceptedが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

正常に完了した場合、応答の本文はありません。

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

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

応答本文のプロパティ

正常に完了した場合、応答の本文はありません。

エラーの場合、応答本文には以下のプロパティが含まれます。

プロパティ 説明 型

type

結果の簡単な説明。

文字列

message

結果の詳細な説明。

文字列

errors

（オプション）エラーの結果のリスト。

配列

errors[].id

通知に失敗したユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

errors[].status

失敗したリクエスト項目に対するHTTP応答コード。

整数

errors[].errorCode

短いエラーコード。

文字列

errors[].errorDescription

読み取り可能なエラーメッセージ。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーの説明の内容に依存するビジネスロジックは構築しないでください。

文字列

HTTPステータスコード

ステータス 説明

202 Accepted

すべての通知の削除が受け付けられ、現在処理中です。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

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

ユニットリスト内の固定視覚アラートを照会します。

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

Healthcare Hospitality Senior Living Core

米国

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

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

米国

リクエスト

アラートを取得するには、/v3/notifications/queryリソースに対してPOSTリクエストを実行します。

リクエストパスとリクエストヘッダーの例

クリップボードにコピーされました。

POST /v3/notifications/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

リクエストパスとリクエストヘッダーのパラメーター

パラメーター 指定場所 説明 型 必須

access token

ヘッダー

ユーザーのアクセストークン。
LWAトークンに設定します。

文字列

◯

リクエスト本文の例

以下の例では、1つ以上のユニットのアクティブな固定視覚アラート通知を取得します。

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

プロパティ 説明 型 必須

query

フィルタリング条件。受信者IDまたは受信者のタイプでフィルタリングできます。andプロパティとorプロパティのいずれかを含めます。

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

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

オブジェクトの配列

◯

query.and

論理AND演算を使用して適用する条件のリスト。
matchプロパティを含めるか、matchプロパティを含む別のorフィルタリング条件のリストを含めることができます。これらの条件は、JSONをドット演算子でフラット化したものです。
例：{"and": [{"DSN": "DSN1234"}, {"UnitId": "Unit1234"}]}

query.andは以下の基準を満たしている必要があります。

  • andの最大サイズ： 1～3項目。
  • andの有効な一致条件：
    recipients.typeがUnitに設定されている。
    notifications.variants.typeがPersistentVisualAlertに設定されている。
  • and.orの最大サイズ： 1～100項目。
  • and.orの有効な一致条件：
    recipients.idがユニットIDに設定されている。

オブジェクトの配列

×

query.or

論理OR演算を使用して適用する条件のリスト。
matchプロパティを含めることができます。これらの条件は、JSONをドット演算子でフラット化したものです。
例：{"or": [{"DSN": "DSN1234"}, {"DSN": "DSN5678"}]}

query.orは以下の基準を満たしている必要があります。

  • and.orの最大サイズ： 1～100項目。

オブジェクトの配列

×

paginationContext

ページ分割情報。ページ分割された応答の反復処理を行う場合に含めます。省略すると、結果の最初のページが返されます。

オブジェクト

×

paginationContext.maxResults

応答で返される結果の最大数。有効な値は 1～100です。デフォルト値は 10です。

整数

×

paginationContext.nextToken

前回の応答から取得する次のデータセットを識別します。ページ分割された応答の反復処理を行う場合に含めます。それ以外の場合はnullに設定します。

文字列

×

応答

正常に完了すると、HTTP 200 OKと共に、クエリの結果のリストが返されます。エラーの場合は、適切なHTTPステータスコードが返され、応答の本文にErrorオブジェクトが追加されます。

応答本文の例

以下は、成功した応答の例です。

{
    "successResults": [{
        "recipients": [{
            "type": "Unit",
            "id": "amzn1.alexa.unit.did.101"
        }],
        "notification": {
            "variants": [{
                "type": "PersistentVisualAlert",
                "content": {
                    "variants": [{
                        "type": "V0Template",
                        "values": [{
                            "locale": "ja-JP",
                            "document": {
                                "type": "Link",
                                "src": "doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/textWrappingTemplate"
                            },
                            "datasources": {
                                "displayText": {
                                    "primaryText": "サンプルの通知の第1テキストです。",
                                    "secondaryText": "サンプルの通知テキストです。"
                                },
                                "background": {
                                    "backgroundImageSource": "http://www.example.com/image.jpg"
                                }
                            }
                        }]
                    }]
                },
                "dismissalTime": "2021-04-30T10:00:00.00Z"
            }],
            "referenceId": "example-ref-id-1 "
        }
    }],
    "paginationContext": {
        "nextToken": "someToken.2"
    }
}

応答本文のパラメーター

プロパティ 説明 型

successResults

成功した通知結果のリスト。

オブジェクトの配列

successResults[].recipients[].type

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

文字列

successResults[].recipients[].id

ユニットを識別します。
amzn1.alexa.unit.did.{id}というHAQM Common Identifier（ACI）形式で表します。

文字列

successResults[].notification

通知を記述します。

オブジェクト

successResults[].notification.variants

通知バリアントのリスト。

オブジェクトの配列

successResults[].notification.variants[].type

通知の配信タイプ。
有効な値： PersistentVisualAlert。

文字列

successResults[].notification.variants[].content

固定視覚アラートのコンテンツ。

Contentオブジェクト

successResults[].notification.dismissalTime

通知の有効期限の日時。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

successResults[].referenceId

通知の参照ID。
この値は、カスタムIDか、通知を送信する操作によって生成されたUUIDのいずれかです。

文字列

paginationContext

返す結果がほかにもあるかどうかを示します。

オブジェクト

paginationContext.nextToken

応答が分割された場合に含まれます。
この値は後続のリクエストで使用します。結果がこれ以上ない場合、nextTokenはnullになります。

文字列

HTTPステータスコード

ステータス 説明

200 OK

一致する結果のリストが応答本文に含まれています。

400 Bad Request

リクエスト本文の1つ以上のプロパティが無効であることを示します。

401 Unauthorized

リクエストに認可トークンが含まれていないか、含まれているトークンが有効期限切れまたは無効です。または、リソースにアクセスする権限がありません。

403 Forbidden

認可トークンは有効ですが、リクエストされたオペレーションが許可されていないことを示します。

404 Not Found

リクエストされたリソースが見つかりません。

429 Too Many Requests

許可されたレート制限（単位時間あたりのリクエスト数として指定された値）を超過しています。リクエストの再試行には指数バックオフを使用します。

500 Server Error

サーバーでエラーが発生しました。リクエストの再試行には指数バックオフを使用します。

503 Service Unavailable

サーバーがメンテナンスのために停止しているか、過負荷状態または受信リクエストを処理できない状態になっています。

固定視覚アラートテンプレート

固定視覚アラートを定義するときは、アラートのデータを定義するAPLテンプレートを含めます。テンプレートは、通知を送信する操作で、リクエスト本文のnotification.variants[].content.variants[].values[].document.srcプロパティに指定します。その後、テンプレートに応じたフィールドをnotification.variants[].content.variants[].values[].datasourcesオブジェクトに設定します。

背景画像について

各テンプレートには、background.backgroundImageSourceプロパティを使用して背景画像を指定できます。テンプレートでは、画面全体に表示されるように画像のサイズが均一に拡大または縮小されます（「best-fill」）。その結果、画像のアスペクト比とデバイス画面のアスペクト比が一致しない場合は、画像の一部が切り取られることがあります。

画像を適切に表示するには、以下の推奨事項を考慮してください。

  • 画像の端までテキストがある画像は使用しないでください。画像のサイズ調整によって、テキストが切り詰められる可能性があります。
  • 可能であれば、ユニットで使用されているものと同じタイプのデバイスで、画像をテストしてください。
  • 別々のユニットに異なるデバイスが含まれている場合は、デバイスに合わせて画像を最適化できるように、異なる固定視覚アラートを使用して個々のユニットをターゲットにすることを検討してください。この方法は、同一のユニット内ですべてのデバイスのアスペクト比が同じである場合に有効です。
  • デフォルトでは、画像上のテキストを読みやすくするために、テンプレートによって背景画像にレイヤーが適用されます。これにより画像が暗くなりすぎる場合は、テンプレートのbackground.colorOverlayプロパティをfalseに設定して、レイヤーをオフにできます。

PNGまたはJPG形式の画像を指定できます。画像ファイルのサイズは400KB以内にする必要があります。

テキスト折り返しテンプレートのデータソース

テキスト折り返しテンプレートの場合、notification.variants[].content.variants[].values[].datasourcesオブジェクトには以下のプロパティがあります。

プロパティ名 説明 型 必須

attribution.attributionImageSource

表示するアトリビューション画像のURL。attributionImageSourceとattributionTextはどちらか一方を指定し、両方は指定しないでください。

文字列

×

attribution.attributionText

ほかのテキストフィールドの下に表示されるアトリビューションテキスト。attributionTextとattributionImageSourceはどちらか一方を指定し、両方は指定しないでください。

文字列

×

background.backgroundImageSource

背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。

文字列

×

background.colorOverlay

trueの場合、画像上のテキストを読みやすくするために、背景画像にレイヤーが適用されます。

ブール値

×（設定しない場合、デフォルト値はtrue）

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。

文字列

×

displayText.hintText

画面下部に表示されるヒントテキスト。

文字列

×

displayText.primaryText

表示する第1テキスト。このテキストは、ほかのテキストよりも大きいフォントで表示されます。

文字列

◯

displayText.secondaryText

第1テキストの下に小さいフォントで表示される第2テキスト。

文字列

×

displayText.tertiaryText

第2テキストの横に表示される第3テキスト。

文字列

×

メディアテンプレートのデータソース

メディアテンプレートの場合、notification.variants[].content.variants[].values[].datasourcesオブジェクトには以下のプロパティがあります。

プロパティ名 説明 型 必須

attribution.attributionImageSource

表示するアトリビューション画像のURL。attributionImageSourceとattributionTextはどちらか一方を指定し、両方は指定しないでください。

文字列

×

attribution.attributionText

ほかのテキストフィールドの下に表示されるアトリビューションテキスト。attributionTextとattributionImageSourceはどちらか一方を指定し、両方は指定しないでください。

文字列

×

background.backgroundImageSource

背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。

文字列

×

background.colorOverlay

trueの場合、画像上のテキストを読みやすくするために、背景画像にレイヤーが適用されます。

ブール値

×（設定しない場合、デフォルト値はtrue）

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。

文字列

×

displayText.hintText

画面下部に表示されるヒントテキスト。

文字列

×

displayText.primaryText

表示する第1テキスト。このテキストは、ほかのテキストよりも大きいフォントで表示されます。

文字列

◯

displayText.secondaryText

第1テキストの下に小さいフォントで表示される第2テキスト。

文字列

×

displayText.tertiaryText

第2テキストの横に表示される第3テキスト。

文字列

×

thumbnail.thumbnailImageSource

テキストフィールドの横に表示する画像のサムネイルのURL。

文字列

×

レーティングテンプレートのデータソース

レーティングテンプレートの場合、notification.variants[].content.variants[].values[].datasourcesオブジェクトには以下のプロパティがあります。

プロパティ名 説明 型 必須

background.backgroundImageSource

背景画像のURL。画像を選択する際は、背景画像についての推奨事項を参照してください。

文字列

×

background.colorOverlay

trueの場合、画像上のテキストを読みやすくするために、背景画像にレイヤーが適用されます。

ブール値

×（設定しない場合、デフォルト値はtrue）

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。

文字列

×

displayText.hintText

画面下部に表示されるヒントテキスト。

文字列

×

displayText.primaryText

表示する第1テキスト。このテキストは、ほかのテキストよりも大きいフォントで表示されます。

文字列

◯

displayText.ratingNumber

レーティングを表す星の数。レーティングの数値は1～5の範囲で指定でき、3.5のように半分の星を含めることもできます。

1～5の数値

◯

displayText.ratingText

星評価のコンテキストを表す短いテキスト。8文字未満にする必要があります。

文字列

◯

thumbnail.thumbnailImageSource

表示する画像のサムネイルのURL。

文字列

×

オブジェクトの定義

通知APIでは、以下のオブジェクトが定義されています。

Contentオブジェクト

Contentオブジェクトは、通知テキストまたはAPLドキュメントを定義します。このオブジェクトの特定のフィールドは、notification.variants[].typeプロパティで設定した通知の配信タイプ （DeviceNotification、Announcement、PersistentVisualAlert）によって異なります。

プロパティ 説明 型 必須

variants

ロケール固有の通知コンテンツ。

オブジェクトの配列

◯

variants[].type

コンテンツのタイプ。
有効な値は次のとおりです。

  • SpokenText - ローカライズされたテキスト入力。配信タイプがDeviceNotificationおよびAnnouncementの場合に有効です。
  • V0Template - 画面付きデバイスにコンテンツを表示するAlexa Presentation Language（APL）ドキュメント。配信タイプがPersistentVisualAlertの場合に有効です。

文字列

◯

variants[].values

通知コンテンツ。すべての通知タイプに含めます。
配列内の各要素は、ローカライズされた通知を表します。

オブジェクトの配列

◯

variants[].values[].locale

読み上げテキストのロケール。BCP-47形式で指定します。ロケールには言語と国／地域の両方を含める必要があります。例：en-US。

文字列

◯

variants[].values[].text

プレーンテキスト形式の読み上げテキスト。通知タイプがDeviceNotificationまたはAnnouncementの場合に指定します。
最大長は 1024文字または2048バイトです。

文字列

×

variants[].values[].document

表示するAPLドキュメントを定義します。通知タイプがPersistentVisualAlertの場合に指定します。

オブジェクト

×

variants[].values[].document.type

表示するAPLドキュメントのタイプ。通知タイプがPersistentVisualAlertの場合に指定します。
有効な値は Linkです。

文字列

×

variants[].values[].document.src

表示するAPLテンプレート。通知タイプがPersistentVisualAlertの場合に指定します。
有効な値は次のとおりです。

  • テキスト折り返し - doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/textWrappingTemplate
  • メディアサムネイル - doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/mediaThumbnailTemplate
  • レーティング - doc://alexa/apl/documents/enterprise/notifications/persistentvisualalert/ratingTemplate

文字列

×

variants[].values[].datasources

指定したsrcドキュメントのデータ。通知タイプがPersistentVisualAlertの場合に指定します。
具体的なデータは、document.srcプロパティに設定したテンプレートによって異なります。詳細については、以下のリファレンスを参照してください。

オブジェクト

×

Errorオブジェクト

Errorオブジェクトは、エラーが発生したときに応答に含まれるエラーのタイプとメッセージを定義します。

以下は、応答本文の例です。

{
    "type": "BAD_REQUEST",
    "message": "The request is malformed or is missing any required parameters."
}
プロパティ 説明 型

type

発生したエラーのタイプ。
具体的なエラータイプについては、各操作のHTTPステータスコードの表を参照してください。

文字列

message

読み取り可能なエラーメッセージ。エラーメッセージはデバッグやログ記録のみを目的としたものです。ユーザーには表示しないようにする必要があります。エラーメッセージの内容に依存するビジネスロジックを構築しないようにする必要があります。

文字列

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

最終更新日: 2025 年 06 月 16 日