Amazon Marketing Streamオンボーディングガイド

このチュートリアルの手順に従って、AWSアプリケーションをAmazon Marketing Streamデータセットに接続します。チュートリアルを終了すると、SQSキューへのパフォーマンスとキャンペーンのデータの受信が始まります。

始める前に

このチュートリアルを完了するには、次のものが必要です。

Amazon Ads APIへのアクセス
有効なAds APIアクセストークン
Ads APIのプロファイルID
AWSアカウント
TerminalやPostmanなどのツールを使用してベーシックcURLリクエストを行う機能
Amazon Marketing Streamデータセットの理解

ヒント

リファレンスアプリケーションを使用してストリーミングにオンボーディングします。AWS CDKを使用したPythonベースのリファレンスアプリケーションは、ドキュメントに記載されている手順をプログラム的に完了するのに役立ちます。詳細についてはこちらをご覧ください。

手順1： SQSキューを作成する

Amazon Marketing Streamを使用してデータを受信するには、まずAWS Simple Queue Service（SQS）を使用してキューを設定する必要があります。AWSの設定は、AWSに精通した担当者が行うことをおすすめします。

キューを作成するには、AWSアカウントにログインしてSQSコンソールを使用するか、AWS CloudFormationテンプレートを使用します。

CloudFormation

ヒント

オンボーディング中のエラーを避けるため、SQSコンソールでキューを手動で設定する代わりにCloudFormationテンプレートを使用することをおすすめします。

CloudFormationテンプレートを使用するには、[CloudFormationによるオンボーディング](../../ guides/amazon-marketing-stream/cloud-formation.html)の指示に従ってください。

CloudFrontテンプレートによって有効なリソースベースのIAMポリシーが自動的に追加されるため、CloudFormationを使用する場合は、このガイドの手順2をスキップして、手順3に直接進むことができます。

SQSコンソール

SQSコンソールを使用して、SQSキューを手動で作成することもできます。AWSドキュメントの指示に従います。

次の表を使用して、キューを作成する地域を決定します。

広告主様の地域	AWS地域
NA	us-east-1
EU	eu-west-1
FE	us-west-2

サポートされている国の詳細については、利用可能な地域をご覧ください。

注

標準キューを作成する必要があります。FIFOキューは現在サポートされていません。

手順2：リソースベースのIAMポリシーを追加する

警告

Amazon Marketing Streamデータを受信するには、有効なIAMポリシーをキューに追加する必要があります。

データセットと地域の組み合わせごとに異なるIAMポリシーがあります。たとえば、sp-trafficデータセットは、NA、EU、FEでIAMポリシーが異なります。登録するデータセットと地域に基づいて正しいIAMポリシーを適用していることを確認してください。利用可能なすべてのデータセットと地域のリソースベースのIAMポリシーを確認するには、Amazon Marketing Streamデータガイドをご覧ください。

キューの作成中にアクセスポリシーを追加するか、既存のキューを編集できます。

注

IAMポリシーを挿入するときは、リソースが自分のキューのAmazonリソース名（ARN）を指していることを確認してください。

手順3： Amazon Marketing Streamデータセットに登録する

キューを設定してIAMポリシーを追加したら、Amazon Marketing Stream登録APIを使用して広告主様データに登録できます。登録するデータセットごとに個別のリクエストを行う必要があります。

警告

登録リクエストを送信する前に、データセットに関連付けられているIAMポリシーがSQSキューにすでに適用されていることを確認してください。

複数のプロファイルのデータに登録する場合は、それぞれについて個別に呼び出しを行う必要があります。

ヒント

Postmanコレクションを使用して、Amazon Marketing Stream APIをテストします。コレクションと環境を設定したら、Amazon Marketing StreamフォルダーをチェックしてAPIを呼び出します。

リクエスト

ヘッダー

パラメーター	説明
Amazon-Advertising-API-ClientId	Login with Amazonアプリケーションに関連付けられているクライアントID。
Amazon-Advertising-API-Scope	プロファイルID。
認可	アクセストークン。
Content-Type	`application/vnd.MarketingStreamSubscriptions.StreamSubscriptionResource.v1.0+json`

パラメーター

| パラメーター | 必須 | 説明 | |-----------|-------------| | dataSetId | はい | 利用可能なすべてのデータセットを確認するには、データガイドをご覧ください。 | | destinationArn | はい | データを受信するSQSキューのARN。 | | clientRequestToken | はい | 同一のAPIリクエストを追跡するために使用される、呼び出し元によって提供される一意の値。リクエストを再試行する場合、呼び出し元は同じ値を指定する必要があります。GUIDの使用をおすすめします。 | | notes | いいえ | リンク先の識別に使用できるその他の情報。 |

例

Amazon-Advertising-API-ClientId、Amazon-Advertising-API-Scope、Authorization、destinationArnはアカウント固有の値に置き換えてください。clientRequestTokenには、必要に応じてリクエストを識別するために使用できる任意の冪等性トークンを使用できます。

    curl --location --request POST 'https://advertising-api.amazon.com/streams/subscriptions' \
    --header 'Amazon-Advertising-API-ClientId: xxxxxx' \
    --header 'Amazon-Advertising-API-Scope: xxxxxxx' \
    --header 'Content-Type: application/vnd.MarketingStreamSubscriptions.StreamSubscriptionResource.v1.0+json' \
    --header 'Authorization: Bearer xxxxxxxxx' \
    --data-raw '{
    "clientRequestToken": "123456789xyz1234567",
    "dataSetId": "sp-conversion",
    "notes": "Advertiser 1 sp-conversion subscription",
    "destinationArn": "QUEUE_ARN"
    }‘

応答

リクエストが成功すると、レスポンスにsubscriptionIdが含まれます。

{
    "subscriptionId": "xxxxxxxxxxxxxx",
    "clientRequestToken": "123456789xyz1234567",
}

手順4： SQSで登録を確認する

APIを使用してAmazon Marketing Streamに正常に登録すると、SQSで登録を確認してデータの受信を開始する必要があります。

SQSキューに次のようなメッセージが表示されます。

{
    "Type" : "SubscriptionConfirmation",
    "MessageId" : "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
    "Token" : "2336412f37...",
    "TopicArn" : "arn:aws:sns:us-west-2:123456789012:MyTopic",
    "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:123456789012:MyTopic.To confirm the subscription, visit the SubscribeURL included in this message.",
    "SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:123456789012:MyTopic&Token=2336412f37...",
    "Timestamp" : "2012-04-26T20:45:04.751Z",
    "SignatureVersion" : "1",
    "Signature" : "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
    "SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem"
}

キューでデータの受信を開始するには、次のいずれかの方法で登録を確認する必要があります。

SQSキュー確認メッセージで返されたSubscribeURL値に対してGETリクエストを行います。この呼び出しにより、登録が確認されてキューがメッセージの受信を開始することを示すメッセージが返されます。

確認メッセージの例

<ConfirmSubscriptionResponse>
    <ConfirmSubscriptionResult>
        <SubscriptionArn>arn:aws:sns:us-east-2:123456789012:MyTopic:1234a567-bc89-012d-3e45-6fg7h890123i</SubscriptionArn>
    </ConfirmSubscriptionResult>
    <ResponseMetadata>
        <RequestId>abcd1efg-23hi-jkl4-m5no-p67q8rstuvw9</RequestId>
    </ResponseMetadata>
</ConfirmSubscriptionResponse>

AWS SDKで、SQSキュー確認メッセージで返されたTokenとTopicArnの値を使用してConfirmSubscriptionを呼び出します。

注

登録している広告主様とデータセットそれぞれの登録を確認する必要があります。

同じキューで複数の広告主様またはデータセットのデータを受信する場合は、上記のオプション2を使用して、プログラムで登録を確認するアプリケーションを作成することを検討してください。アプリケーションでキューを監視し、確認メッセージをデータイベントと区別する必要があります。

次のようなロジックを使用して、登録メッセージとデータイベントを区別できます。

    if "Type" in content and content['Type'] == 'SubscriptionConfirmation':

    def confirm_subscription(content):
        token = content['Token']
        topicArn = content['TopicArn']
        print(f"Confirming subscription for {topicArn}")
        sns.confirm_subscription(TopicArn=topicArn, Token=token)

登録ステータスフロー

ストリーム登録のステータスフローは、次の図をご覧ください。

ストリームステータスフロー図

登録について考えられるステータスの詳細については、登録の管理をご覧ください。

次の手順

登録を確認してデータの受信を開始したら、次に進むことができます。

トラブルシューティングに関するよくある質問

最初の数日間のデータに負の値が表示されるのはなぜですか？

負の値は、Amazonのクリック数とコンバージョンの検証プロセスに基づいて遡及的に修正が行われていることを意味します。接続を有効にした最初の1日か2日は、元のトラフィックを受け取っておらず、修正のみ行われるため、集計値が負の値になる可能性があります。最初の1～2日間は負の値を無視することをおすすめします。

最初の2日が経過すると、正の値が表示されるようになるはずです。2日経っても正の集計値が表示されない場合は、サポートにお問い合わせください。

クリックの無効化によって修正が行われると、引き続き負の差分が表示されますが、常に正の値に集計されるはずです。

空欄のレコードが表示されるのはなぜですか？

これらの行は無視できます。これは想定どおりで、これらの行は問題ではなく、0に集計されるためデータに問題はありません。

キューを作成しましたが、POST /streams/subscriptionsを使用して登録しようとすると、地域がサポートされていないことを示すエラーコード400が表示されます。

現在の状況では、Amazon Marketing Streamはus-east-1（NA）、eu-west-1（EU）、およびus-west-2（FE）の3つの地域のみをサポートしています。SQSキューを作成するときは、サポートされている地域のみを使用していることを確認してください。このエラーを回避するには、提供されているCloudFormationテンプレートを使用してキューを作成することをおすすめします。

登録ステータスは`PENDING_CONFIRMATION`ですが、SQSで確認メッセージが表示されません。

キューに間違ったIAMポリシーを適用した可能性があります。キューで使用しているIAMポリシーが、広告主様のプロファイルの地域および登録しようとしているデータセットと一致していることを確認してください。

キューに間違ったIAMポリシーを適用した場合は、新しいキューを作成して正しいポリシーを適用し、新しいキューARNを使用してデータセットに再度登録する必要があります。

ヒント

手動エラーのリスクを減らすため、提供されているCloudFormationテンプレートを使用してキューを作成することをおすすめします。

正しいIAMポリシーを適用しているのにPENDING_CONFIRMATIONのままになっている場合は、チケットを送信してください。サポートチームが確認メッセージを手動で再送信できます。

登録が`PENDING_CONFIRMATION`のままで、`FAILED_CONFIRMATION`に移行しません。

3日以内に登録が確認されない場合、ステータスは自動的にFAILED_CONFIRMATIONに移行するはずです。ステータスがFAILED_CONFIRMATIONに移行したら、別のリクエストを送信してデータセットに登録できます。まれに、ステータスが自動的にFAILED_CONFIRMATIONに切り替わらない場合があります。その場合はサポートチームにチケットを送信してください。

または、新しいキューを作成して関連性の高いIAMポリシーを適用し、新しいキューARNを使用してデータセットへの登録を再試行することもできます。

SQSで登録を正常に確認しましたが、SQSリンク先キューにメッセージが届きません。

Amazon Marketing Streamはほぼリアルタイムでデータを配信するため、何かが送信されるには、登録されているデータセットとマーケットプレイス内の広告主様とそのキャンペーンに関連するイベントが発生する必要があります。これらのイベントがない場合、データはありません。つまり、1時間以内にそのキャンペーンのパフォーマンスがあった場合にのみデータが送信されます。

重複したデータを受信しているようです。

重複したレコードを受信しているように見える場合は、まずデータを調べてください。受信したデータが重複しているように見えても、実際には有効であるというシナリオがいくつかあります。

まず、2つの異なる時間のデータが非常に似ている可能性があります。たとえば、特定の日の時間1に10回のインプレッションと3回のクリックを獲得したキーワードを考えてみましょう。時間2で再び10回のインプレッションと3回のクリックを獲得します。Streamは、両方の時間でそのキーワードについて同様のレコードを送信し、これらのレコードはデータが関連する時間のみで区別されます。インプレッション数が少ないキーワードでは、1日を通して何時間もインプレッションが1回しか表示されず、クリックがない可能性があります。

次に、Amazon Marketing Streamはキャンペーンについて1時間ごとの差分を送信するため、修正により、レコードがほぼ同じように見えることがあります。これにより、同じキーワードで同じ時間帯に同じクリック数とインプレッションデータを持つレコードが2つ作成される可能性がありますが、1つは元の差分で、もう1つは修正したものです。これは重複ではなく、2つのレコードのidempotency_idを調べることで確認できます。冪等性IDが異なる場合、それらは重複しておらず、そのキーワードと時間における2つの異なるレコードです。

登録をキャンセルするにはどうすればよいですか？

現在、登録を削除またはキャンセルする方法はありません。登録のデータ受信を停止するには、subscriptionStatusをARCHIVEDに設定する必要があります。詳細については、登録の管理をご覧ください。

開発者ガイドの概要

Amazon Ads APIの概要

Amazon Marketing Streamオンボーディングガイド

始める前に

ヒント

手順1： SQSキューを作成する

CloudFormation

ヒント

SQSコンソール

注

手順2：リソースベースのIAMポリシーを追加する

警告

注

手順3： Amazon Marketing Streamデータセットに登録する

警告

ヒント

リクエスト

ヘッダー

パラメーター

例

応答

手順4： SQSで登録を確認する

注

登録ステータスフロー

次の手順

トラブルシューティングに関するよくある質問

最初の数日間のデータに負の値が表示されるのはなぜですか？

空欄のレコードが表示されるのはなぜですか？

キューを作成しましたが、POST /streams/subscriptionsを使用して登録しようとすると、地域がサポートされていないことを示すエラーコード400が表示されます。

登録ステータスは`PENDING_CONFIRMATION`ですが、SQSで確認メッセージが表示されません。

ヒント

登録が`PENDING_CONFIRMATION`のままで、`FAILED_CONFIRMATION`に移行しません。

SQSで登録を正常に確認しましたが、SQSリンク先キューにメッセージが届きません。

重複したデータを受信しているようです。

登録をキャンセルするにはどうすればよいですか？

開発者ガイドの概要

Amazon Ads APIの概要

Amazon Marketing Streamオンボーディングガイド

始める前に

ヒント

手順1： SQSキューを作成する

CloudFormation

ヒント

SQSコンソール

注

手順2： リソースベースのIAMポリシーを追加する

警告

注

手順3： Amazon Marketing Streamデータセットに登録する

警告

ヒント

リクエスト

ヘッダー

パラメーター

例

応答

手順4： SQSで登録を確認する

注

登録ステータスフロー

次の手順

トラブルシューティングに関するよくある質問

最初の数日間のデータに負の値が表示されるのはなぜですか？

空欄のレコードが表示されるのはなぜですか？

キューを作成しましたが、POST /streams/subscriptionsを使用して登録しようとすると、地域がサポートされていないことを示すエラーコード400が表示されます。

登録ステータスはPENDING_CONFIRMATIONですが、SQSで確認メッセージが表示されません。

ヒント

登録がPENDING_CONFIRMATIONのままで、FAILED_CONFIRMATIONに移行しません。

SQSで登録を正常に確認しましたが、SQSリンク先キューにメッセージが届きません。

重複したデータを受信しているようです。

登録をキャンセルするにはどうすればよいですか？

手順2：リソースベースのIAMポリシーを追加する

登録ステータスは`PENDING_CONFIRMATION`ですが、SQSで確認メッセージが表示されません。

登録が`PENDING_CONFIRMATION`のままで、`FAILED_CONFIRMATION`に移行しません。