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

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

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

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

APIエンドポイント

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

国 エンドポイント

カナダ、米国

https://api.amazonalexa.com

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

https://api.eu.amazonalexa.com

日本

https://api.fe.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 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": "ja-JP",
                    "document": {},
                    "datasources": {}
                }]
            }
        }]
    },
    "targeting": {
       （タイプがユニットのポリモーフィックオブジェクト）
    },
    "scheduling": {
        "activationWindow": {
            "start": "2021-01-01T10:00:00.00Z",
            "end": "2021-01-31T10:00:00.00Z"
        }
    }
}

リクエスト本文の例

以下は、キャンペーンのリクエスト本文の例です。この例は、英語（米国）のデバイスではen-USのコンテンツを表示し、日本語のデバイスではja-JPのコンテンツを表示します。デバイスには、ロケールごとに常に1つのキャンペーンのみが表示されます。

{
   "suggestion": {
      "variants": [
         {
            "placement": {
               "channel": "HOME"
            },
            "content": {
               "values": [
                  {
                    "locale": "ja-JP",
                    "document": {
                       "type": "Link",
                       "src": "<ドキュメントへのリンクのプレースホルダー>"
                    },
                    "datasources": {
                       "displayText": {
                          "primaryText": "Example notification title.",
                          "secondaryText": "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": {
                          "primaryText": "サンプルの通知タイトルです。",
                          "secondaryText": "サンプルの通知テキストです。",
                          "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つ以上のバリアントが含まれている必要があります。ただし、1つの配信先チャンネルに提供できるバリアントは最大1つです。

配列

◯

suggestion.variants[].placement

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

オブジェクト

◯

suggestion.variants[].placement.channel

チャンネルの名前。現在サポートされている値は"HOME"のみで、これはAlexaマルチモーダルデバイスのホーム画面を指します。1回のリクエストで1つの配信先チャンネルに提供できるバリアントは最大1つです。

文字列

◯

suggestion.variants[].content.values[]

デフォルトのコンテンツタイプに固有のローカライズされたプレゼンテーションデータを含むオブジェクトの配列。少なくとも1つのローカライズされたプレゼンテーションデータ要素を提供する必要があります。さまざまなロケールに対応するために、この配列に複数のオブジェクトを指定できます。ただし、1つのロケールに対して複数のオブジェクトを定義することはできません。デバイスでは、そのデバイスのロケールに一致する最初のオブジェクトが表示されます。

配列

◯

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

コンテンツがレンダリングされるロケール。BCP-47形式で指定します。ロケールには言語と国／地域の両方を含める必要があります。例：en-US。

文字列

◯

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/home/cards/textWrapping
  • メディアサムネイル - doc://alexa/apl/documents/home/cards/media
  • レーティング - doc://alexa/apl/documents/home/cards/rating
  • あなたの1日 - doc://alexa/apl/documents/home/cards/suggestedActions
  • この日 - doc://alexa/apl/documents/home/cards/primePhoto
  • 写真カード - doc://alexa/apl/documents/home/cards/selectedPhoto

文字列

◯

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

APLドキュメントにデータをバインドするほかのオブジェクトを含むことができるオブジェクト。datasourcesオブジェクトに指定する固有のフィールドは、document.srcプロパティに設定したテンプレートによって異なります。以下を参照してください。

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

◯

targeting

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

オブジェクト

◯

scheduling

キャンペーンのスケジュール情報。このフィールドが存在しない場合、デフォルトの開始時刻は現在の時刻、終了時刻は現在の時刻の24時間後になります。

オブジェクト

✕

scheduling.activationWindow

キャンペーンがアクティブになる期間を指定するタイムウィンドウオブジェクト。

オブジェクト

〇（schedulingを含む場合）

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を含むオブジェクトのリスト。ユニット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

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

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

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

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

Healthcare Hospitality 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: {リクエストで使用されたホストの値}
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 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

サジェスチョンを取得するためのフィルタリング条件を提供するオブジェクト。このオブジェクトには、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～100の間で指定します。デフォルト値は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": {
                                            "primaryText": "Light and warm patio breakfast",
                                            "secondaryText": "Breakfast is served until 11:30 am!"
                                        }
                                    }
                                },
                                {
                                    "locale": "ja-JP",
                                    "document": {
                                        "type": "Link",
                                        "src": "<ドキュメントへのリンクのプレースホルダー>"
                                    },
                                    "datasources": {
                                        "displayText": {
                                            "primaryText": "明るく暖かいテラスで朝食を",
                                            "secondaryText": "朝食は午前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

コンテンツがレンダリングされるロケール。BCP-47形式で指定します。ロケールには言語と国／地域の両方を含める必要があります。例：en-US。

文字列

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ドキュメントのリンク。

文字列

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

APLドキュメントにデータをバインドするほかのオブジェクトを含むことができるオブジェクト。このオブジェクト内の固有のフィールドは、document.srcプロパティに指定したテンプレートによって異なります。以下を参照してください。

オブジェクト

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

キャンペーンがアクティブになる期間を指定するタイムウィンドウオブジェクト。

オブジェクト

scheduling.activationWindow.start

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

文字列

scheduling.activationWindow.end

タイムウィンドウの終了時刻。ISO 8601形式（YYYY-MM-DDThh:mm:ssZ）に則ったRFC 3339プロファイルを使用する文字列です。

文字列

HTTP応答コード

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

200

OK

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

400

Bad Request

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

401

Unauthorized

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

403

Forbidden

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

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

キャンペーンを取得する

作成したアクティブなキャンペーンを取得します。この操作では、有効期限が切れたキャンペーンは返されません。

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

Healthcare Hospitality 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: {リクエストで使用されたホストの値}
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

指定されたcampaignIdがアクティブなキャンペーンと一致しませんでした。campaignIdが正しいこと、および有効期限が切れたキャンペーンを参照していないことを確認してください。

429

Too Many Requests

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

500

Internal Server Error

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

503

Service Unavailable

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

キャンペーンを削除する

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

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

Healthcare Hospitality 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: {リクエストで使用されたホストの値}
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

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

キャンペーンテンプレート

以下のセクションでは、プロアクティブキャンペーンに使用できる各テンプレートについて詳しく説明します。テンプレートは、キャンペーンを作成するリクエスト本文のsuggestion.variants[].content.values[].document.srcプロパティに指定します。その後、テンプレートに応じたフィールドをsuggestion.variants[].content.values[].datasourcesプロパティに設定します。

背景画像について

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

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

  • 画像の端までテキストがある画像は使用しないでください。画像のサイズ調整によって、テキストが切り詰められる可能性があります。
  • 可能であれば、ユニットで使用されているものと同じタイプのデバイスで、画像をテストしてください。
  • 別々のユニットに異なるデバイスが含まれている場合は、デバイスに合わせて画像を最適化できるように、異なるプロアクティブキャンペーンを使用して個々のユニットをターゲットにすることを検討してください。この方法は、同一のユニット内ですべてのデバイスのアスペクト比が同じである場合に有効です。

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

テキスト折り返し

テキスト折り返しテンプレート（doc://alexa/apl/documents/home/cards/textWrapping）は、背景画像の上にテキストを表示します。このテンプレートでは、スキルを起動するボタンを含めることもできます。

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

プロパティ名 説明 型 必須

attribution.attributionImageSource

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

文字列

✕

attribution.attributionText

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

文字列

✕

background.backgroundImageSource

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

文字列

✕

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。最大文字数は 80文字です。

文字列

✕

displayText.hintText

画面下部に表示されるヒントテキスト。最大文字数は 60文字です。

文字列

✕

displayText.primaryText

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

文字列

◯

displayText.secondaryText

第1テキストの下に小さいフォントで表示される第2テキスト。最大文字数は 80文字です。

文字列

✕

displayText.tertiaryText

第2テキストの横に表示される第3テキスト。最大文字数は 25文字です。

文字列

✕

displayText.playbackEnabled

trueの場合、第1テキストの前に「再生」ボタンが表示されます。ユーザーがボタンをタップすると、指定したactionが実行されます。

ブール値

✕

displayText.callToActionButtonText

設定すると、指定したラベルの付いたアクションボタンがテキストの下に表示されます。ユーザーがボタンをタップすると、指定したactionが実行されます。最大文字数は 35文字です。

文字列

✕

displayText.action

ユーザーが再生ボタンまたはアクションボタンをタップしたときに実行するアクションを定義するオブジェクト。

オブジェクト

◯

displayText.action.type

アクションのタイプ。
有効な値： SkillConnection

文字列

◯

displayText.action.uri

カードに関連付けるスキルのURI。connection://AMAZON.ColdLaunch/1?provider=<スキルID>という形式で指定します。

例：connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345

文字列

◯

メディア

メディアテンプレート（doc://alexa/apl/documents/home/cards/media）は、テキストの横に大きいサムネイル画像を表示します。

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

プロパティ名 説明 型 必須

attribution.attributionImageSource

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

文字列

✕

attribution.attributionText

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

文字列

✕

background.backgroundImageSource

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

文字列

✕

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。最大文字数は 40文字です。

文字列

✕

displayText.hintText

画面下部に表示されるヒントテキスト。最大文字数は 35文字です。

文字列

✕

displayText.primaryText

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

文字列

◯

displayText.secondaryText

第1テキストの下に小さいフォントで表示される第2テキスト。最大文字数は 25文字です。

文字列

✕

displayText.tertiaryText

第2テキストの横に表示される第3テキスト。最大文字数は 25文字です。

文字列

✕

thumbnail.thumbnailImageSource

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

文字列

✕

レーティング

レーティングテンプレート（doc://alexa/apl/documents/home/cards/rating）は、テキストを星評価と共に表示します。

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

プロパティ名 説明 型 必須

background.backgroundImageSource

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

文字列

✕

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。最大文字数は 60文字です。

文字列

✕

displayText.hintText

画面下部に表示されるヒントテキスト。最大文字数は 35文字です。

文字列

✕

displayText.primaryText

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

文字列

◯

displayText.ratingNumber

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

1～5の数値

◯

displayText.ratingText

星評価のコンテキストを表す短いテキスト。最大文字数は 8文字です。

文字列

◯

thumbnail.thumbnailImageSource

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

文字列

✕

あなたの1日

あなたの1日テンプレート（doc://alexa/apl/documents/home/cards/suggestedActions）は、ヒントテキストとサムネイル画像から成る項目を3つまで表示します。ユーザーが項目をタップしたときに実行するアクションを定義できます。

このテンプレートで表示される項目の数は、デバイスのサイズによって異なります。たとえば、Echo Show 15では3つすべてが表示され、Echo Show 8では最初の2つが表示されます。Echo Show 5などの小型デバイスでは1つの項目だけが表示されます。

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

プロパティ名 説明 型 必須

background.backgroundImageSource

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

文字列

✕

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。最大文字数は 60文字です。

文字列

✕

displayText.listItems

表示する最大3つのリスト項目オブジェクトの配列。

オブジェクトの配列

✕

displayText.listItems[].hintText

項目に表示するテキスト。最大文字数は 80文字です。

文字列

✕

displayText.listItems[].thumbnailSource

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

文字列

✕

displayText.action

ユーザーがリスト項目のいずれかをタップしたときに実行するアクションを定義するオブジェクト。すべてのリスト項目で使用される単一のアクションを定義できます。

オブジェクト

◯

displayText.action.type

アクションのタイプ。
有効な値： SkillConnection

文字列

◯

displayText.action.uri

カードに関連付けるスキルのURI。connection://AMAZON.ColdLaunch/1?provider=<スキルID>という形式で指定します。

例：connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345

文字列

◯

displayText.action.input

スキルに渡すデータ。この機能はサポートされていないため、このプロパティは空のオブジェクト{}に設定してください。

オブジェクト

◯

この日

この日テンプレート（doc://alexa/apl/documents/home/cards/primePhoto）は、写真と短いテキストを全画面に表示します。

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

プロパティ名 説明 型 必須

background.backgroundImageSource

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

文字列

✕

displayText.headerText

ほかのすべてのテキストフィールドの前に表示されるヘッダーテキスト。最大文字数は 60文字です。

文字列

✕

displayText.hintText

画面下部に表示されるヒントテキスト。最大文字数は 35文字です。

文字列

✕

displayText.primaryText

ヘッダーの後に表示する第1テキスト。最大文字数は 60文字です。

文字列

◯

displayText.action

ユーザーが画面上の任意の場所をタップしたときに実行するアクションを定義するオブジェクト。

オブジェクト

◯

displayText.action.type

アクションのタイプ。
有効な値： SkillConnection

文字列

◯

displayText.action.uri

カードに関連付けるスキルのURI。connection://AMAZON.ColdLaunch/1?provider=<スキルID>という形式で指定します。

例：connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345

文字列

◯

displayText.action.input

スキルに渡すデータ。この機能はサポートされていないため、このプロパティは空のオブジェクト{}に設定してください。

オブジェクト

◯

写真カード

写真カードテンプレート（doc://alexa/apl/documents/home/cards/selectedPhoto）は、写真と短い第1テキストおよび第2テキストを全画面に表示します。

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

プロパティ名 説明 型 必須

background.backgroundImageSource

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

文字列

✕

displayText.hintText

画面下部に表示されるヒントテキスト。最大文字数は 35文字です。

文字列

✕

displayText.primaryText

表示する第1テキスト。やや大きいフォントで表示されます。最大文字数は 60文字です。

文字列

◯

displayText.secondaryText

第1テキストの下に表示する第2テキスト。最大文字数は 80文字です。

文字列

◯

displayText.action

ユーザーが画面上の任意の場所をタップしたときに実行するアクションを定義するオブジェクト。

オブジェクト

◯

displayText.action.type

アクションのタイプ。
有効な値： SkillConnection

文字列

◯

displayText.action.uri

カードに関連付けるスキルのURI。connection://AMAZON.ColdLaunch/1?provider=<スキルID>という形式で指定します。

例：connection://AMAZON.ColdLaunch/1?provider=amzn1.ask.skill.12345

文字列

◯

displayText.action.input

スキルに渡すデータ。この機能はサポートされていないため、このプロパティは空のオブジェクト{}に設定してください。

オブジェクト

◯

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

最終更新日: 2024 年 11 月 20 日