通知API

通知API

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

通知タイプ

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

  • デバイス通知 - 画面のないAlexa搭載デバイスの場合、デバイス通知は黄色いリングとチャイム音になります。画面付きのデバイスの場合、デバイス通知はバナーと固定通知インジケーターになります。
  • アナウンス - デバイスの画面の有無にかかわらず、Alexaは音声でアナウンスします。画面付きのデバイスでは、画面にもメッセージが表示されます。
  • 固定視覚アラート - 固定視覚アラートは、画面付きのデバイスで使用できます。固定視覚アラートは、有効期限が切れるか、ゲストや居住者が解除するまで画面に表示される通知です。固定視覚アラートには、プレミアムマルチモーダルアドオンサブスクリプションが必要です。詳細については、プレミアムマルチモーダルを参照してください。

APIエンドポイント

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

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.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

通知の受信者。

配列

◯

recipients[].type

受信者のタイプ。
有効な値は Unit、Endpointです。同一のリクエストの受信者はすべて同じタイプである必要があります。

列挙

◯

recipients[].id

エンドポイントまたはユニットのID。

  • ユニットの場合、"amzn1.alexa.unit.did.{id}"の形式で表します。
  • エンドポイントの場合、amzn1.alexa.endpoint.{identifier}の形式で表します。

文字列

◯

notification

通知オブジェクト。

オブジェクト

◯

notification.referenceId

新しく作成される固定視覚アラートの参照ID。referenceIdは、ユニット内の通知ごとに固有のUUIDです。これは、以前に配信された通知を更新する場合に使用します。通知のtypeがPersistentVisualAlertの場合に適用されます。指定しない場合、デフォルト値は生成されたIDの値になります。

文字列

✕

notification.variants[].type

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

詳しい違いについては、通知タイプを参照してください。

列挙

◯

notification.variants[].content

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

オブジェクト

◯

notification.variants[].content.variants[]

ユニットに配信される、ロケール固有の通知コンテンツ。

オブジェクトの配列

◯

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

通知のタイプ。有効な値は次のとおりです。

  • SpokenText - DeviceNotificationまたはAnnouncementを送信します。通知は、ローカライズされたテキスト入力を表します。
  • V0Template - PersistentVisualAlert配信タイプを送信します。通知は、画面付きデバイスにコンテンツを表示するAlexa Presentation Language（APL）ドキュメントを表します。

どちらのタイプでも、values配列内に通知の内容を指定します。

列挙

◯

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

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

オブジェクトの配列

◯

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

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

文字列

◯

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

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

文字列

◯（DeviceNotificationまたはAnnouncementの場合）

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

表示するAPLドキュメントを定義するオブジェクト。通知のtypeがPersistentVisualAlertの場合に適用されます。

オブジェクト

◯（PersistentVisualAlert通知の場合）

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

表示するAPLドキュメントのタイプ。Linkに設定します。

文字列

◯（PersistentVisualAlert通知の場合）

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

表示するテンプレートに応じて、4つのサポートされているAPLテンプレートのいずれかに設定します。

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

文字列

◯（PersistentVisualAlert通知の場合）

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

指定されたsrcドキュメントのデータが含まれます。固有のフィールドは、document.srcプロパティに設定したテンプレートによって異なります。以下を参照してください。

通知のtypeがPersistentVisualAlertの場合に適用されます。

オブジェクト

◯（PersistentVisualAlert通知の場合）

notification.variants[].deliveryPreferences

Alexaからの通知の配信方法に関するオプションを含むオブジェクト。通知のtypeがPersistentVisualAlertの場合に適用されます。

オブジェクト

✕

notification.variants[].deliveryPreferences.indictor.sound.type

通知がデバイスに届いたときに再生するサウンドを指定します。
有効な値は SILENT、CHIMEです。CHIMEに設定した場合、通知が届くとチャイム音が1回鳴ります。デフォルト値はSILENTです。

列挙値

✕

notification.variants[].deliveryPreferences.interruption.level

通知によってデバイスでの既存のエクスペリエンスがどのように中断されるかを指定します。有効な値は次のとおりです。

  • HIGH - 通知はフォアグラウンドでレンダリングされるため、現在のデバイスエクスペリエンスが中断されます。たとえば、ユーザーがスキルを操作している場合、通知によってスキルが中断されます。
  • LOW - 通知はバックグラウンドでレンダリングされ、ユーザーが現在のエクスペリエンスを完了するとホーム画面に置き換わります。たとえば、ユーザーがスキルを操作している場合、通知によってスキルが中断されることはありません。代わりに、スキルセッションの終了後に通知がレンダリングされます。

デフォルト値はLOWです。

列挙値

✕

notification.variants[].scheduling

通知の配信日時と終了日時のスケジュール方法を決定するオブジェクト。指定しない場合、Alexaは通知をすぐに配信します。通知のtypeがPersistentVisualAlertの場合に適用されます。

schedulingプロパティとdismissalTimeプロパティはどちらか一方を指定し、両方は指定しないでください。

オブジェクト

✕

notification.variants[].scheduling.activationWindow.start

通知を配信する日時。ISO 8601形式で表します。

文字列

✕

notification.variants[].scheduling.activationWindow.end

通知の有効期限が切れる日時。ISO 8601形式で表します。ゲストや居住者が手動で解除しない限り、通知はこの日時までデバイスに表示され続けます。

文字列

✕

notification.variants[].dismissalTime

通知の有効期限の日時。ISO 8601形式で表します。ゲストや居住者が手動で解除しない限り、通知はこの日時までデバイスに表示され続けます。通知のtypeがPersistentVisualAlertの場合に適用されます。

schedulingプロパティとdismissalTimeプロパティはどちらか一方を指定し、両方は指定しないでください。

文字列

✕

応答ヘッダー

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

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

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

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

文字列

◯

リクエスト本文の例

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

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

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

応答ヘッダー

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、Endpointです。同一のリクエストの受信者はすべて同じタイプである必要があります。

列挙

◯

recipients[*].id

エンドポイントまたはユニットのID。

  • ユニットの場合、"amzn1.alexa.unit.did.{id}"の形式で表します。
  • エンドポイントの場合、amzn1.alexa.endpoint.{identifier}の形式で表します。

文字列

◯

notificationTypes

削除する通知のタイプ。有効な値は PersistentVisualAlert、DeviceNotificationです。最大サイズは 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、Endpointのいずれかです。
  • notifications.variants.typeに指定できる値はPersistentVisualAlertのみです。

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

オブジェクト

◯

paginationContext.maxResults

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

整数

✕

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/textWrappingTemplate"
                      },
                      "datasources": {
                        "displayText": {
                          "primaryText": "サンプルの通知の第1テキストです。",
                          "secondaryText": "サンプルの通知テキストです。"
                        },
                        "background": {
                          "backgroundImageSource": "https://www.example.com/image.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[*]

クエリ条件に一致する固定視覚アラート通知のリスト。指定できる通知のプロパティについては、通知を送信する操作のリクエスト本文を参照してください。

オブジェクトの配列

HTTP応答コード

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

200

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

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

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

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

以下のセクションでは、固定視覚アラートに使用できる各テンプレートについて詳しく説明します。テンプレートは、通知を送信する操作で、リクエスト本文の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。

文字列

✕

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

最終更新日: 2024 年 06 月 19 日