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

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

Alexa Smart Properties in Senior Living施設運営側で、Alexaマルチモーダルデバイスのホーム画面から、ブランディング、製品やサービスのアップセル（ハッピーアワーサービスやスパサービスなど）を行ったり、イベント、アップデート、スキルに関する情報をゲストに提供したりできます。

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

APIエンドポイント

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

認証

すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値には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 Token}

リクエスト本文の形式

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

{
    "suggestion": {
        "variants": [{
            "placement": {
                "channel": "HOME"
            },
            "content": {
                "values": [{
                    "locale": "en-US",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    },
    "targeting": {
       ( unitsタイプのポリモーフィックオブジェクト)
    },
    "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": "<placeholderLinkToDocument>"
                    },
                    "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": "pt-BR",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Exemplo de título de notificação.",
                          "body": "Texto de notificação de exemplo.",
                          "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

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

文字列

◯

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"の形式を使用し、プロバイダーの値をスキル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

キャンペーンの受け取り側を定義するポリモーフィックオブジェクト。ターゲットのタイプ：units。

オブジェクト

◯

scheduling

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

オブジェクト

◯

scheduling.activationWindow

キャンペーンの有効期限を指定するタイムウィンドウオブジェクト。このフィールドの指定がない場合は、Alexaはデフォルト値を使用します。

オブジェクト

✕

scheduling.activationWindow.start

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

文字列

✕

scheduling.activationWindow.end

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

文字列

✕

ユニットターゲット

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

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

type

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

文字列

◯

values[]

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

配列

◯

values[].id

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

文字列

◯

成功応答のヘッダー

HTTP/1.1 202 Accepted
Host: {host value used in the request}
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 Token}

リクエスト本文の形式

{
    "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": "<placeholderLinkToDocument>"
                    },
                    "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": "pt-BR",
                    "document": {
                       "type": "Link",
                       "src": "<placeholderLinkToDocument>"
                    },
                    "datasources": {
                       "displayText": {
                          "title": "Exemplo de título de notificação.",
                          "body": "Texto de notificação de exemplo.",
                          "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

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

文字列

◯

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"の形式を使用し、プロバイダーの値をスキル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: {host value used in the request}
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 Token}

リクエスト本文の形式

なし。

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

フィールド 説明 型 必須

maxResults

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

整数

✕

nextToken

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

文字列

✕

成功応答のヘッダー

Host: {host value used in the request}
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": {
            ( unitsタイプのポリモーフィックオブジェクト)
         },
         "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": "token from previous call"
   }
}

応答本文のパラメーター

フィールド 説明 型

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 Token}

リクエスト本文の形式

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

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

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

フィールド 説明 型 必須

query

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

クエリは、以下の規則に従います。

  • クエリは、リクエスト本文の例で示した構造と一致している必要があります。
  • クエリは1つのand演算のみを持つことができます。
  • 使用できる条件はmatchのみです。
  • query.andは2項目のリストです。
  • query.and.orは、最小サイズ1、最大サイズ100のリストです。使用できるフィールドはtargeting.values.idのみです。
  • targeting.typeの値はUNITSのみです。

クエリオブジェクト

◯

paginationContext

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

オブジェクト

✕

paginationContext.maxResults

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

整数

✕

paginationContext.nextToken

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

文字列

✕

クエリオブジェクト

フィールド 説明 型 必須

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": "<placeholderLinkToDocument>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "title": "Light and warm patio breakfast",
                                            "body": "Breakfast is served until 11:30 am!"
                                        }
                                    }
                                },
                                {
                                    "locale": "pt-BR",
                                    "document": {
                                        "type": "Link",
                                        "src": "<placeholderLinkToDocument>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "title": "Café da manhã leve e quente no pátio",
                                            "body": "O café da manhã é servido até as 11h30!"
                                        }
                                    },
                                    "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

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

文字列

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を含むオブジェクトのリスト。形式は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形式YYYY-MM-DDThh:mm:ssZに則ったRFC 3339プロファイルを使用する文字列です。デフォルト値は現在の時刻です。

文字列

scheduling.activationWindow.end

タイムウィンドウの終了時刻。ISO 8601形式YYYY-MM-DDThh:mm:ssZに則ったRFC 3339プロファイルを使用する文字列です。開始時刻と同じか、それより遅い時間である必要があります。デフォルト値は、現在の時刻の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 Token}

リクエスト本文の形式

なし。

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

フィールド 説明 型 必須

campaignId

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

文字列

◯

成功応答のヘッダー

Host: {host value used in the request}
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": {
      ( unitsタイプのポリモーフィックオブジェクト)
   },
   "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

成功

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

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 Token}

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

フィールド 説明 型 必須

campaignId

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

文字列

◯

リクエスト本文

なし。

成功応答のヘッダー

HTTP/1.1 202 OK
Host: {host value used in the request}
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 月 06 日