Rewards API

Rewards APIを使用すると、Amazonが届ける商品をリワードとしてユーザーに送ることができます。同APIは、Android、iOS、Fire OSのアプリやウェブサイトを含む、さまざまなサービスに対応しています。

このガイドでは、Rewards APIの活用手順について、使用例を挙げながら説明します。

概要
APIエンドポイント
API認可
APIスロットリング制限
APIタイムアウト
各種言語でのAPIリクエスト
エラーメッセージ
テストアカウント

概要

重要： MomentsのRewards APIは、アプリのクライアント側ではなく、サーバー側から呼び出す必要があります。

Rewards APIを使用するための大まかな手順は、以下のとおりです。

Momentsコンソールを使用してサービスを登録し、リワードを構成します。詳しくは、サービスを登録するを参照してください。
キャンペーンがチャレンジの場合、getRewardInfoエンドポイントを呼び出して、対象ユーザーに通知するコンテンツを取得します。
ルールエンジンを活用して、ユーザーがキャンペーンの対象条件を満たしているかどうかを判定する必要があります。ユーザーが条件を満たしている場合は、getRewardエンドポイントを呼び出してリワードを使い、リワード引き換え用URLをユーザーに送信します。

以下のワークフローマップで、大まかなやり取りの流れを説明します。

APIエンドポイント

重要：セキュリティ上の問題が生じる恐れがあるため、アプリのクライアントからRewards APIメソッドを呼び出すことは避け、必ずサーバー側のコードから呼び出すようにしてください。

APIエンドポイントの詳細については、APIエンドポイントの仕様を参照してください。エンドポイントはOpenAPI形式で指定されます。用意された対話型APIエクスプローラーを使用すれば、APIのサンプル呼び出しを試すことが可能です。

Rewards APIには、2つのエンドポイントがあります。

どちらのエンドポイントも同じリクエストパラメーターを使用します。主な違いは、GetRewardエンドポイントがリワードを消費するのに対して、GetRewardInfoエンドポイントはリワードに関する情報を返すだけで、リワード自体は消費されません。

API認可

Rewards APIは、ヘッダーで渡されるAPIキーを使用してリクエストを認可します。

x-api-key: "API KEY"

サービスのAPIキーは、Momentsコンソールの [Registration Details] で確認できます。

警告： APIキー値をクライアントソフトウェアに埋め込むことは避けてください。リバースエンジニアリングされた場合に、財務上の損失につながる恐れがあります。

APIスロットリング制限

登録するサービスごとに、API呼び出しに含める一意のAPIキーが用意されます。
APIキーごとに、API呼び出しは1秒あたり5つまでというデフォルトの制限が設けられています（getRewardInfo呼び出しとgetReward呼び出しの任意の組み合わせが可能です）。
APIキーからのトラフィックが1秒あたり5呼び出しを超える場合、超過分のAPI呼び出しに対してエラーレスポンスが送信され、フローが制限されます。
APIスロットリング制限を処理するロジックの実装をお勧めします。API呼び出しが制限された場合、以下のような処理を行ってください。
- 遅延が発生した後、API呼び出しを再試行する。
- 再試行の回数を制限する。

注：遅延を設定せず、再試行の回数を制限しない場合、再試行リクエストの回数が原因でスロットリング制限に悪影響が生じる可能性があります。

APIタイムアウト

Momentsでは、Rewards APIのリクエストごとに10秒間のタイムアウトが設定されています。Momentsから常にレスポンス（成功レスポンス、エラーレスポンス、またはタイムアウト）を得られるように、サーバーの実装では必ずより長いタイムアウトを設定するようにしてください。

Momentsより先にサーバーがタイムアウトすると、getReward呼び出しの成功レスポンスが得られない可能性があります。このような場合、Momentsからリワードの請求があっても、アプリ側でそのリワードを認識することができないため、ユーザーへの提供もできません。

上記のAPIスロットリング制限で説明したロジックと同様のロジックを使用して、APIタイムアウトから回復するためのコードの実装をお勧めします。

各種言語でのAPIリクエスト

言語ごとのエンドポイント呼び出し方法を、以下のタブで説明します。

cURL

curl -X POST -H "x-api-key: kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi" -H "Content-Type: application/json; charset=UTF-8" -d "{
	'appId': 'DEMO1',
	'momentId':'MomentsReward',
	'deviceType' : 'Android',
	'campaignId' : 'DEMOCAMP1',
	'rewardGroupId': 'US'
}" "https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetReward"

Java

String url = "https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetReward";
URL obj = new URL(url);
HttpsURLConnection connection = (HttpsURLConnection) obj.openConnection();

connection.setRequestMethod("POST");
connection.setRequestProperty("Accept-Language", "UTF-8");
connection.setRequestProperty("Content-Type", "application/json");
connection.setRequestProperty("x-api-key", "kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi");

connection.setDoOutput(true);
OutputStreamWriter outputStreamWriter = new OutputStreamWriter(connection.getOutputStream());
JSONObject json = new JSONObject();
json.put("appId", "DEMO1");
json.put("momentId", "MomentsReward");
json.put("deviceType", "Android");
json.put("campaignId", "DEMOCAMP1");
json.put("rewardGroupId", "US");

outputStreamWriter.write(json.toString());
outputStreamWriter.flush();

int responseCode = connection.getResponseCode();
System.out.println("\nSending 'POST' request to URL : " + url);
System.out.println("Post parameters : " + urlParameters);
System.out.println("Response Code : " + responseCode);

BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
String output;
StringBuffer response = new StringBuffer();

while ((output = bufferedReader.readLine()) != null) {
 response.append(output);
}
bufferedReader.close();

System.out.println(response.toString());

Python

# 次のURLの手順に従って、Requestsライブラリをインストールする必要があります: http://docs.python-requests.org/en/master/user/install/#install
import requests

API_ENDPOINT = "https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetReward"
API_KEY = "kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi" # ここでAPIキーを指定する
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"} # ヘッダー
# APIに送信されるデータ
data = {
    'appId': 'DEMO1',
    'momentId': 'MomentsReward',
    'deviceType': 'Android',
    'campaignId': 'DEMOCAMP1',
    'rewardGroupId': 'US'
}
# POSTリクエストを送信し、レスポンスをレスポンスオブジェクトとして保存
r = requests.post(url = API_ENDPOINT, headers=headers, json = data)
# レスポンスのテキストを抽出
response = r.text
print("headers: %s"%headers)
print("data: %s"%data)
print("The response is: %s"%response)

Node.js

var options = {
    url: 'https://dnxr7vm27d.execute-api.us-east-1.amazonaws.com/prod/GetRewardInfo',
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi'
    }
};
var req = http.request(options, function(res) {
    console.log('Status:' + res.statusCode);
    console.log('Headers: ' + JSON.stringify(res.headers));
    res.on('data', function(body) {
        console.log('Body:' + body);
    });
});

req.on('error', function(e) {
    console.log('problem with request: ' + e.message);
});

// リクエスト本文にデータを書き込む
req.write('{"x-api-key":"12345", "Content-Type":"application/json", "appId":"DEMO1","momentId":"MomentsReward","deviceType":'
    Android ','
    campaignId ':"DEMOCAMP1","rewardGroupId":"US"}');
req.end();

ここで紹介していない言語でRewards APIを呼び出す場合は、その言語のAPIリクエスト形式を特定する必要があります。

エラーメッセージ

MomentsサービスがAPIリクエストを正常に完了できない場合、rewardNotificationTextフィールドには、発生したエラーに関するテキストメッセージが含まれます。
これらのエラー応答では、HTTPステータスコード200が使用されます。エラーメッセージの種類は以下のとおりです。

Invalid Credentials（無効な認証情報です）： APIへのアクセスに使用されたAPIキーが正しくない場合に返されます。
Inactive Campaign（非アクティブなキャンペーンです）：キャンペーンがアクティブでない場合（つまり、現在の日付がキャンペーンの開始日と終了日の間にない場合）に返されます。
Invalid Campaign（無効なキャンペーンです）：アプリID、キャンペーンID、モーメントID、リワードグループIDの組み合わせがMomentsキャンペーンに関連付けられていない場合、またはキャンペーンの開始日と終了日が無効である場合に返されます。
Invalid Reward Group（無効なリワードグループです）：アプリID、キャンペーンID、モーメントIDの組み合わせがMomentsキャンペーンに関連付けられているが、リワードグループIDがキャンペーンに関連付けられていない場合に返されます。
No Available Reward Found（利用可能なリワードが見つかりませんでした）：キャンペーンまたはキャンペーンに関連付けられたリワードグループにリワードが残っていない場合に返されます。
Campaign Monthly Limit Reached（キャンペーンの1か月ごとの上限に達しました）：キャンペーンで引き換えられたリワード数が1か月ごとの上限に達した場合に返されます。

テストアカウント

Rewards APIについて調べる際は、以下に用意したテストアカウントと構成を使用してください（エンドポイントを呼び出すときは、これらのパラメーターのほとんどをリクエスト本文で使用します）。

このデモでは、アプリ（DEMO1）に対して1つのキャンペーン（DEMOCAMP1）が定義されています。キャンペーンの構成では、Androidのデバイスタイプに対して1つのモーメント（MomentsReward）が定義されています。このモーメントでは1つのリワードグループを使用でき、そのグループに5つのリワードが設定されているため、このキャンペーンにおけるリワードの総数は5になります。

フィールド	値
DEV ID	`MOMENTS` （この値はエンドポイントリクエストでは使用されません。これは、開発者別にアプリをグループ化するためにバックグラウンドで使用されます）
API KEY	`kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi`
`appId`	`DEMO1`
`campaignId`	`DEMOCAMP1`
`deviceType`	`Android`
`rewardGroupId`	`US`
`momentId`	`MomentsReward`

テストと開発の最中に、テストアカウントのリワードをすべて使用した場合は、同じAPIキーでGETリクエストをhttps://at0xry1l42.execute-api.us-east-1.amazonaws.com/prodに送信すると、リワードを元の5つにリセットすることができます。たとえば、次のようにcURLを使用してターミナル経由での送信が可能です。

curl -H "x-api-key: kE2xi2OgUa7jfijmsd0jQ74aJntJwUEW2EU8LUsi" "https://at0xry1l42.execute-api.us-east-1.amazonaws.com/prod/"

このレスポンスはnullですが、リワードはリセットされます。