プロアクティブサジェスチョンAPI

プロアクティブサジェスチョンAPI

Alexa Smart Properties for Hospitalityの施設のオペレーターにとって、Alexaマルチモーダルデバイスのホーム画面は、ブランディングを高めたり、製品やサービスのアップセル（ハッピーアワーやスパサービスの提供など）を実現したり、イベント、アップデート、スキルに関する情報をゲストに提供したりできる絶好の場です。

ソリューションインテグレーターは、AlexaプロアクティブサジェスチョンREST APIを使用して、施設のマネージャーが視覚コンテンツをサジェスチョンとしてAlexaに提供できるようにすることが可能です。Alexaは、これらのサジェスチョンからコンテンツ項目を選択し、ユーザーのデバイスのホーム画面に表示します。サジェスチョンの視覚エクスペリエンスを作成するには、Alexa Presentation Language（APL）を使用します。

APIエンドポイント

プロアクティブサジェスチョンAPIのエンドポイントはhttps://api.amazonalexa.comです。

認証

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

操作

プロアクティブサジェスチョンAPIには、以下の操作が用意されています。

説明 HTTPメソッドとパス

キャンペーンを作成する

POST /v1/proactive/campaigns

キャンペーンのリストを取得する

GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken}

キャンペーンを照会する

POST /v1/proactive/campaigns/query

キャンペーンを取得する

GET /v1/proactive/campaigns/{campaignId}

キャンペーンを削除する

DELETE /v1/proactive/campaigns/{campaignId}

キャンペーンを作成する

ターゲット受信者へのサジェスチョンとしてコンテンツをレンダリングするキャンペーンを作成します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

POST /v1/proactive/campaigns HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

リクエスト本文の形式

リクエスト本文には、サジェスチョンをその受信者およびスケジュールの詳細と共にカプセル化する、キャンペーンエンティティが含まれます。以下の例は、キャンペーンエンティティを示しています。

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    },
    "targeting": {
       （タイプがユニットのポリモーフィックオブジェクト）
    },
    "scheduling": {
        "activationWindow": {
            "start": "2021-01-01T10:00:00.00Z",
            "end": "2021-01-31T10:00:00.00Z"
        }
    }
}

リクエスト本文の例

{
   "suggestion": {
      "variants": [
         {
            "placement": {
               "channel": "HOME"
            },
            "content": {
               "values": [
                  {
                    "locale": "en-US",
                    "document": {
                       "type": "Link",
                       "src": "<ドキュメントへのプレースホルダーリンク>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Example notification title.",
                          "body": "Example notification text.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                          
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                       
                    }
                  },
                  {
                    "locale": "ja-JP",
                    "document": {
                       "type": "Link",
                       "src": "<ドキュメントへのプレースホルダーリンク>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "サンプルの通知タイトルです。",
                          "body": "サンプルの通知テキストです。",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                             
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                         
                    }
                  }
                ]
            }
        }]
   },
   "targeting": {
      "type": "UNITS",
      "values": [
        {
           "id": "amzn1.alexa.unit.did.unitId"
        }
      ]
   },
   "scheduling": {
      "activationWindow": {
         "start": "2021-01-01T10:00:00.00Z",
         "end": "2021-01-31T10:00:00.00Z"
      }
   }
}

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

フィールド 説明 型 必須

suggestion

Alexaがユーザーにプロアクティブに配信できる情報です。

オブジェクト

◯

suggestion.variants[]

ユーザーに提供するサジェスチョンバリアントのリストです。リストには1つ以上のバリアントが含まれている必要があります。

配列

◯

suggestion.variants[].placement

コンテンツをレンダリングできる場所です。

オブジェクト

◯

suggestion.variants[].placement.channel

チャンネルの名前です。現在サポートされている値は"HOME"のみで、これはAlexaマルチモーダルデバイスのホーム画面を参照します。

文字列

◯

suggestion.variants[].content.values[]

デフォルトのコンテンツタイプに固有のローカライズされたプレゼンテーションデータを含むオブジェクトです。少なくとも1つのローカライズされたプレゼンテーションデータ要素が必要です。

オブジェクト

◯

suggestion.variants[].content.values[].locale

コンテンツがレンダリングされるロケールです。IETF BCP 47形式で表します。

文字列

◯

suggestion.variants[].content.values[].document

レンダリングに使用するAPLドキュメントへのリンクです。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。すべてのAPL機能がサポートされるわけではありません。

文字列

◯

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

APLドキュメントのタイプです。Linkを指定する必要があります。

文字列

◯

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

APLドキュメントのリンクです。現在サポートされているのは、"doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate"のみです。

文字列

◯

suggestion.variants[].content.values[].datasources

APLドキュメントにデータをバインドするために、ほかのオブジェクトを含むことができるオブジェクトです。

データソースオブジェクトのマップ

◯

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

ドキュメントのタイトルフィールドにレンダリングされるテキストです。このテキストは、ホーム画面上に大きいフォントで表示されます。最大長は25文字です。

文字列

✕

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

ドキュメントの本文フィールドにレンダリングされるテキストです。このテキストは、ホーム画面上のタイトルの下に、タイトルよりも小さいフォントで表示されます。最大長は60文字です。

文字列

✕

suggestion.variants[].content.values[].datasources.displayText.action

画面上のカードをユーザーがタップしたときに起動するスキルを指定するオブジェクトです。

オブジェクト

✕

suggestion.variants[].content.values[].datasources.displayText.action.type

アクションのタイプです。使用できる値はSkillConnectionのみです。

文字列

✕

suggestion.variants[].content.values[].datasources.displayText.action.uri

起動するスキルです。"connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345"という形式を使用して、providerの値を実際のスキルIDに置き換えてください。

文字列

✕

suggestion.variants[].content.values[].datasources.displayText.action.input

使用されません。空のままにしてください。

オブジェクト

✕

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

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

オブジェクト

✕

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

背景画像のURLです。

文字列

◯（suggestion.variants[].content.values[].datasources.backgroundを含む場合）

targeting

キャンペーンの受信者を定義するポリモーフィックオブジェクトです。ターゲットのタイプはユニットです。

オブジェクト

◯

scheduling

キャンペーンのスケジュール情報です。

オブジェクト

◯

scheduling.activationWindow

キャンペーンがアクティブになる期間を指定するタイムウィンドウオブジェクトです。このフィールドが指定されていない場合、Alexaはデフォルト値を使用します。

オブジェクト

✕

scheduling.activationWindow.start

タイムウィンドウの開始時刻です。ISO 8601形式に則ったRFC 3339プロファイルを使用する、YYYY-MM-DDThh:mm:ssZという形式の文字列です。デフォルト値は現在の時刻です。

文字列

✕

scheduling.activationWindow.end

タイムウィンドウの終了時刻です。ISO 8601形式に則ったRFC 3339プロファイルを使用する、YYYY-MM-DDThh:mm:ssZという形式の文字列です。開始時刻と同じかそれ以降の時刻を表している必要があります。デフォルト値は、現在の時刻から24時間後です。

文字列

✕

ユニットターゲット

キャンペーンのターゲットとなるユニットです。

{
   "type": "UNITS",
   "values": [
      {
         "id": "amzn1.alexa.unit.did.unitId"
      }
   ]
}
フィールド 説明 型 必須

type

適用されるターゲット条件のタイプです。有効な値は UNITSです。

文字列

◯

values[]

ルームのユニットIDを含むオブジェクトのリストです。ユニットIDの形式はamzn1.alexa.unit.did.{id}です。このリストには、最大100個のユニットIDを含めることができます。

配列

◯

values[].id

ルームのユニットIDです。形式はamzn1.alexa.unit.did.{id}です。

文字列

◯

成功応答ヘッダー

HTTP/1.1 202 Accepted
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 型 必須

X-Amzn-RequestId

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

文字列

◯

応答本文の形式

{
    "campaignId": "{exampleId}"
}

応答本文のパラメーター

フィールド 説明 型

campaignId

キャンペーンのキャンペーンIDです。キャンペーンを削除するときやキャンペーンを取得するときは、このIDを使用します。

文字列

HTTP応答コード

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

201

Created

キャンペーンが正常に作成されました。

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

アクセストークンは有効ですが、必要なLWAスコープの権限がユーザーにありません。

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

キャンペーンを更新する

キャンペーンのsuggestionエンティティを更新します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

PUT /v1/proactive/campaigns/{campaignId}/suggestion HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

リクエスト本文の形式

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    }
}

リクエスト本文の例

{
   "suggestion": {
      "variants": [
         {
            "placement": {
               "channel": "HOME"
            },
            "content": {
               "values": [
                  {
                    "locale": "en-US",
                    "document": {
                       "type": "Link",
                       "src": "<ドキュメントへのプレースホルダーリンク>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Example notification title.",
                          "body": "Example notification text.",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                          
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                       
                    }
                  },
                  {
                    "locale": "ja-JP",
                    "document": {
                       "type": "Link",
                       "src": "<ドキュメントへのプレースホルダーリンク>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "サンプルの通知タイトルです。",
                          "body": "サンプルの通知テキストです。",
                          "action": {
                              "type": "SkillConnection",
                              "uri": "connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345",
                              "input": {}
                          }                             
                       },
                       "background": {
                          "backgroundImageSource": "https://www.example.com/image.jpg"
                       }                         
                    }
                  }
                ]
            }
        }
     ]
   }
}

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

フィールド 説明 型 必須

suggestion

Alexaがユーザーにプロアクティブに配信できる情報です。

オブジェクト

◯

suggestion.variants[]

ユーザーに提供するサジェスチョンバリアントのリストです。リストには1つ以上のバリアントが含まれている必要があります。

配列

◯

suggestion.variants[].placement

コンテンツをレンダリングできる場所です。

オブジェクト

◯

suggestion.variants[].placement.channel

チャンネルの名前です。現在サポートされている値は"HOME"のみで、これはAlexaマルチモーダルデバイスのホーム画面を参照します。

文字列

◯

suggestion.variants[].content.values[]

デフォルトのコンテンツタイプに固有のローカライズされたプレゼンテーションデータを含むオブジェクトです。少なくとも1つのローカライズされたプレゼンテーションデータ要素が必要です。

オブジェクト

◯

suggestion.variants[].content.values[].locale

コンテンツがレンダリングされるロケールです。IETF BCP 47形式で表します。

文字列

◯

suggestion.variants[].content.values[].document

レンダリングに使用するAPLドキュメントへのリンクです。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。すべてのAPL機能がサポートされるわけではありません。

文字列

◯

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

APLドキュメントのタイプです。Linkを指定する必要があります。

文字列

◯

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

APLドキュメントのリンクです。現在サポートされているのは、"doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate"のみです。

文字列

◯

suggestion.variants[].content.values[].datasources

APLドキュメントにデータをバインドするために、ほかのオブジェクトを含むことができるオブジェクトです。

データソースオブジェクトのマップ

◯

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

ドキュメントのタイトルフィールドにレンダリングされるテキストです。このテキストは、ホーム画面上に大きいフォントで表示されます。最大長は25文字です。

文字列

✕

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

ドキュメントの本文フィールドにレンダリングされるテキストです。このテキストは、ホーム画面上のタイトルの下に、タイトルよりも小さいフォントで表示されます。最大長は60文字です。

文字列

✕

suggestion.variants[].content.values[].datasources.displayText.action

画面上のカードをユーザーがタップしたときに起動するスキルを指定するオブジェクトです。

オブジェクト

✕

suggestion.variants[].content.values[].datasources.displayText.action.type

アクションのタイプです。使用できる値はSkillConnectionのみです。

文字列

✕

suggestion.variants[].content.values[].datasources.displayText.action.uri

起動するスキルです。"connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345"という形式を使用して、providerの値を実際のスキルIDに置き換えてください。

文字列

✕

suggestion.variants[].content.values[].datasources.displayText.action.input

使用されません。空のままにしてください。

オブジェクト

✕

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

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

オブジェクト

✕

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

背景画像のURLです。

文字列

◯（suggestion.variants[].content.values[].datasources.backgroundを含む場合）

成功応答ヘッダー

HTTP/1.1 202 Accepted
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 型 必須

X-Amzn-RequestId

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

文字列

◯

応答本文の形式

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

応答本文のパラメーター

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

HTTP応答コード

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

202

Accepted

リクエストが受け付けられました。

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

アクセストークンは有効ですが、必要なLWAスコープの権限がユーザーにありません。

404

Not Found

キャンペーンが見つかりません。

429

Too Many Requests

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

500

Internal Server Error

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

キャンペーンのリストを取得する

作成したキャンペーンのリストを取得します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

GET /v1/proactive/campaigns?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

リクエスト本文の形式

ありません。

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

フィールド 説明 型 必須

maxResults

表示する結果の最大数です。値は1～10の間で指定します。デフォルト値は10です。

整数

✕

nextToken

前回のキャンペーンリストの取得に対する応答で、応答オブジェクトに返された継続トークンです。

文字列

✕

成功応答ヘッダー

Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 型 必須

X-Amzn-RequestId

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

文字列

◯

応答本文の形式

{
   "results": [
      {
         "campaignId": "campaignId",
         "suggestion": {
            "variants": [{
               "placement": {
                  "channel": "HOME"
               },
               "content": {
                  "values": [{
                     "locale": "en-US",
                     "document": {},
                     "datasources": {}
                  }]
               }
            }]          
         },
         "targeting": {
            （タイプがユニットのポリモーフィックオブジェクト）
         },
         "scheduling": {
            "activationWindow": {
               "start": "2021-01-01T10:00:00.00Z",
               "end": "2021-01-31T10:00:00.00Z"
            }
         },
         "validationStatus": {
            "value": "string enum",   // IN_PROGRESS、APPROVED、REJECTED
            "reason": "Explanation"
         }
     },
     {
        ... （別のキャンペーンおよびステータス）...
     }
   ],
   "paginationContext": {
      "nextToken": "（前回の呼び出しで返されたトークン）"
   }
}

応答本文のパラメーター

フィールド 説明 型

results[]

作成したキャンペーンのリストと、それぞれの検証ステータスです。

配列

results[].campaign

キャンペーンの作成時に指定した詳細です。フィールドについては、キャンペーン作成時のリクエスト本文の形式を参照してください。

オブジェクト

results[].validationStatus

キャンペーンの最新の検証ステータスです。

オブジェクト

results[].validationStatus.value

キャンペーンの最新の検証ステータスを表す列挙値です。有効な値は、 IN_PROGRESS、APPROVED、REJECTEDです。

文字列

results[].validationStatus.reason

検証ステータスの値の説明です（該当する場合）。

文字列

paginationContext

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

オブジェクト

paginationContext.nextToken

キャンペーンのリストを取得する次回の呼び出しで使用するための継続トークンです。

文字列

HTTP応答コード

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

202

Request Accepted

リクエストが受け付けられました。

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

アクセストークンは有効ですが、必要なLWAスコープの権限がユーザーにありません。

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

キャンペーンを照会する

ユニットのリストに対してキャンペーンを照会します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

POST /v1/proactive/campaigns/query HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

リクエスト本文の形式

以下のクエリは、1つ以上のユニットを使用してアクティブなサジェスチョンを返します。

{
    "query": {
        "and": [
            {
                "or": [
                    {
                        "match": {
                            "targeting.values.id": "U1"
                        }
                    },
                    {
                        "match": {
                            "targeting.values.id": "U2"
                        }
                    }
                ]
            },
            {
                "match": {
                    "targeting.type": "UNITS"
                }
            }
        ]
    },
    "paginationContext": {
        "maxResults": 10,
        "nextToken": "paginationTokenString"
    }
 }

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

フィールド 説明 型 必須

query

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

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

  • クエリは、リクエスト本文の形式に示す構造に合致する必要があります。
  • クエリには、and演算を1つだけ含めることができます。
  • 使用できる条件はmatchのみです。
  • query.andは、2つの項目を含むリストです。
  • query.and.orは、最小サイズ1、最大サイズ100のリストです。使用可能なフィールドはtargeting.values.idのみです。
  • targeting.typeに指定できる値はUNITSのみです。

Queryオブジェクト

◯

paginationContext

ページ分割情報を含むオブジェクトです。

オブジェクト

✕

paginationContext.maxResults

1回のリクエストで返されるサジェスチョンの最大数です。値は1～10の間で指定します。デフォルト値は10です。

整数

✕

paginationContext.nextToken

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

文字列

✕

Queryオブジェクト

フィールド 説明 型 必須

and

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

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

配列

✕

or

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

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

配列

✕

成功応答ヘッダー

HTTP/1.1 200 OK
Host: api.amazonalexa.com
Content-Type: application/json
X-Amzn-RequestId: sample-request-id-value
フィールド 説明 型 必須

X-Amzn-RequestId

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

文字列

◯

応答本文の例

{
    "paginationContext": {
        "nextToken": "paginationTokenString"
    },
    "results": [
        {
            "campaignId": "sample-id",
            "validationStatus": {
                "value": "IN_PROGRESS",
                "reason": "Explanation"
            },
            "suggestion": {
                "variants": [
                    {
                        "placement": {
                            "channel": "HOME"
                        },
                        "content": {
                            "values": [
                                {
                                    "locale": "en-US",
                                    "document": {
                                        "type": "Link",
                                        "src": "<ドキュメントへのプレースホルダーリンク>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "title": "Light and warm patio breakfast",
                                            "body": "Breakfast is served until 11:30 am!"
                                        }
                                    }
                                },
                                {
                                    "locale": "ja-JP",
                                    "document": {
                                        "type": "Link",
                                        "src": "<ドキュメントへのプレースホルダーリンク>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "title": "明るく暖かいテラスで朝食を",
                                            "body": "朝食は午前11:30までご利用いただけます。"
                                        }
                                    },
                                    "background": {
                                        "backgroundImageSource": "https://url-of-image.jpg"
                                    }
                                }
                            ]
                        }
                    }
                ]
            },
            "targeting": {
                "type": "UNITS",
                "values": [
                    {
                        "id": "amzn1.alexa.unit.did.unitId"
                    }
                ]
            },
            "scheduling": {
                "activationWindow": {
                    "start": "2021-01-01T10:00:00.00Z",
                    "end": "2021-01-31T10:00:00.00Z"
                }
            }
        }
    ]
 }

応答本文のパラメーター

フィールド 説明 型

paginationContext

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

オブジェクト

paginationContext.nextToken

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

文字列

results[*]

ユニットに対して作成したキャンペーンのリストと、各キャンペーンの検証ステータスです。

配列

results[*].campaignId

キャンペーンIDです。

文字列

results[*].validationStatus

キャンペーンの最新の検証ステータスです。

オブジェクト

results[*].validationStatus.value

キャンペーンの最新の検証ステータスを表す列挙値です。有効な値は、 IN_PROGRESS、APPROVED、REJECTEDです。

文字列

results[*].validationStatus.reason

検証ステータスの値の説明です（該当する場合）。

文字列

results[*].suggestion

ユーザーに配信するメッセージです。

オブジェクト

results[*].suggestion.variants[*]

ユーザーに提供するサジェスチョンバリアントのリストです。リストには1つ以上のバリアントが含まれている必要があります。

配列

results[*].suggestion.variants[*].placement

コンテンツをレンダリングできる場所です。

オブジェクト

results[*].suggestion.variants[*].placement.channel

チャンネルの名前です。現在サポートされている値は"HOME"のみで、これはAlexaマルチモーダルデバイスのホーム画面を参照します。

文字列

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

デフォルトのコンテンツタイプに固有のローカライズされたプレゼンテーションデータを含むオブジェクトです。少なくとも1つのローカライズされたプレゼンテーションデータ要素が必要です。

配列

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

コンテンツがレンダリングされるロケールです。IETF BCP 47形式で表します。

文字列

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

レンダリングに使用するAPLドキュメントへのリンクです。詳細については、RenderDocumentでリンクドキュメントを使用するを参照してください。すべてのAPL機能がサポートされるわけではありません。

オブジェクト

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

APLドキュメントのタイプです。Linkを指定する必要があります。

文字列

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

APLドキュメントのリンクです。現在サポートされているのは、"doc://alexa/apl/documents/enterprise/suggestions/home/defaultTemplate"のみです。

文字列

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

APLドキュメントにデータをバインドするために、ほかのオブジェクトを含むことができるオブジェクトです。

オブジェクト

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

ドキュメントのタイトルフィールドにレンダリングされるテキストです。このテキストは、ホーム画面上に大きいフォントで表示されます。最大長は25文字です。

文字列

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

ドキュメントの本文フィールドにレンダリングされるテキストです。このテキストは、ホーム画面上のタイトルの下に、タイトルよりも小さいフォントで表示されます。最大長は60文字です。

文字列

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

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

オブジェクト

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

背景画像のURLです。

文字列

results[*].targeting

キャンペーンの受信者を定義するポリモーフィックオブジェクトです。ユニット、ユーザー、スキルサブスクライバーの3つのターゲットタイプのいずれかを表します。

オブジェクト

results[*].targeting.type

適用されるターゲット条件のタイプです。

文字列

results[*].targeting.values[*]

ルームのユニットIDを含むオブジェクトのリストです。ユニットIDの形式はamzn1.alexa.unit.did.{id}です。

配列

results[*].targeting.values[*].id

ルームのユニットIDです。形式はamzn1.alexa.unit.did.{id}です。

文字列

results[*].scheduling

キャンペーンのスケジュール情報です。

オブジェクト

results[*].scheduling.activationWindow

キャンペーンがアクティブになる期間を指定するタイムウィンドウオブジェクトです。このフィールドが指定されていない場合、Alexaはデフォルト値を使用します。

オブジェクト

scheduling.activationWindow.start

タイムウィンドウの開始時刻です。ISO 8601形式に則ったRFC 3339プロファイルを使用する、YYYY-MM-DDThh:mm:ssZという形式の文字列です。デフォルト値は現在の時刻です。

文字列

scheduling.activationWindow.end

タイムウィンドウの終了時刻です。ISO 8601形式に則ったRFC 3339プロファイルを使用する、YYYY-MM-DDThh:mm:ssZという形式の文字列です。開始時刻と同じかそれ以降の時刻を表している必要があります。デフォルト値は、現在の時刻から24時間後です。

文字列

HTTP応答コード

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

200

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

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

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

キャンペーンを取得する

作成したキャンペーンを取得します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

GET /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

リクエスト本文の形式

ありません。

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

フィールド 説明 型 必須

campaignId

取得するキャンペーンのIDです。この値は、キャンペーンを作成したときに返されます。

文字列

◯

成功応答ヘッダー

Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 型 必須

X-Amzn-RequestId

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

文字列

◯

応答本文の形式

{
   "campaignId": "campaignId",
   "suggestion": {
      "variants": [{
         "placement": {
            "channel": "HOME"
         },
         "content": {
            "values": [{
               "locale": "en-US",
               "document": {},
               "datasources": {}
            }]
         }
      }]  
   },
   "targeting": {
      （タイプがユニットのポリモーフィックオブジェクト）
   },
   "scheduling": {
      "activationWindow": {
         "start": "2021-01-01T10:00:00.00Z",
         "end": "2021-01-31T10:00:00.00Z"
      }
   },
   "validationStatus": {
      "value": "string enum",   // IN_PROGRESS、APPROVED、REJECTED
      "reason": "Explanation"
   }
}

応答本文のパラメーター

フィールド 説明 型

キャンペーン情報

キャンペーンの作成時に指定した詳細です。フィールドについては、キャンペーン作成時のリクエスト本文の形式を参照してください。

オブジェクト

ValidationStatus

キャンペーンの検証ステータスです。

オブジェクト

validationStatus

キャンペーンの最新の検証ステータスです。

オブジェクト

validationStatus.value

キャンペーンの最新の検証ステータスです。有効な値は、 IN_PROGRESS、APPROVED、REJECTEDです。

文字列

validationStatus.reason

検証ステータスの値の説明です（該当する場合）。

文字列

HTTP応答コード

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

200

Successful

リクエストが正常に処理されました。

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

アクセストークンは有効ですが、必要なLWAスコープの権限がユーザーにありません。

404

Not Found

削除するキャンペーンが見つかりません。

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

キャンペーンを削除する

キャンペーンを削除します。

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

Healthcare Hospitality Residential Senior Living Core

米国

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

米国

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

米国

リクエストの形式

DELETE /v1/proactive/campaigns/{campaignId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWAトークン}

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

フィールド 説明 型 必須

campaignId

削除するキャンペーンのIDです。この値は、キャンペーンを作成したときに返されます。

文字列

◯

リクエスト本文

ありません。

成功応答ヘッダー

HTTP/1.1 202 OK
Host: {リクエストで使用されたホストの値}
X-Amzn-RequestId: {request-id}
Content-Type: application/json
フィールド 説明 型 必須

X-Amzn-RequestId

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

文字列

◯

応答本文

ありません。

HTTP応答コード

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

202

Accepted

指定されたキャンペーンに対する削除リクエストが受け付けられました。キャンペーンは削除されますが、サジェスチョンが配信済みでない保証はありません。

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

アクセストークンは有効ですが、必要なLWAスコープの権限がユーザーにありません。

404

Not Found

削除するキャンペーンが見つかりません。

429

Too Many Requests

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

500

Internal Server Error

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

最終更新日: 2023 年 03 月 16 日