オーディエンスAPI¶

オーディエンスAPIを使うと、任意のユーザーID のリストを使ってオーディエンスを作成、もしくは更新することができます。

自社の分析基盤や、他社サービスなどで作成したユーザーIDのリストをReproに登録し、マーケティング施策の配信対象として利用することができます。

注釈

Reproに登録されているユーザーが対象となります。Reproに登録されていないユーザーが含まれている場合は、対象として計上されません。

はじめに¶

Repro API トークンの確認¶

オーディエンスAPIを使うには、Repro API トークンを使用します。

設定 > プロジェクト設定 に行き、 認証情報 > Repro API トークン を確認します。

警告

「APIトークンの再発行」をすると既存のAPIトークンを利用できなくなり、あとから復元することはできません。

オーディエンスAPI v3¶

現在、オーディエンスAPI v3では下記の機能を提供しています。データをアップロードするために異なるエンドポイントに対して 2 回リクエストを送る必要があります。なお、2回目のリクエストについては、新規作成と更新で全く同じです。

機能	HTTPメソッド	エンドポイント
新規作成	`POST`	`https://api.reproio.com/v3/audiences`
更新	`PUT`	`https://api.reproio.com/v3/audiences/<オーディエンスID>`

以降では、リクエスト方法の詳細を記載していきます。

注釈

pre-signed URLの有効期限は5分です。そのため、1回目のレスポンスを受け取ってから5分以内に2回目のリクエストを開始してください。

単位時間あたりのアクセス上限¶

オーディエンスAPIには単位時間当たりのアクセス上限があります。

アクセス上限設定値は、APIトークンごとに10分あたり15件です。
リクエストが正常に完了すると、レスポンスの X-RateLimit-Limit ヘッダーに単位時間あたりのリクエスト上限回数が記載されます。
リクエスト数がアクセス上限数を超えると、 HTTP Status 429 (Too Many Requests) が返ります。

レスポンスヘッダーの詳細レスポンスヘッダーをご覧ください。

警告

アクセス上限設定値は予告なく変動する場合があります。
アクセス上限設定値は、機能単位でのAPIトークンごととなります。

例えば、プッシュAPIとユーザープロフィールAPIは同じAPIトークンを利用していますが、別機能のため同時にリクエストしたとしても、それぞれ１件づつのカウントとなります。

サンプルコード¶

オーディエンスの新規作成のサンプルコードを以下に記載します。オーディエンスの更新用に変更するには以下2点を変更してください。

1回目のリクエストのエンドポイントを更新用のものに変更する
1回目のリクエストメソッドを POST から PUT に変更する

#!/bin/bash

set -e

API_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
AUDIENCES_URI=https://api.reproio.com/v3/audiences

file=$(realpath -e $1)
checksum=$(openssl dgst -md5 -binary ${file} | base64)
content_size=$(stat -c %s ${file})

body=$(cat <<EOF
{
  "name": "my-audience-api",
  "checksum":"${checksum}",
  "byte_size":"${content_size}"
}
EOF
)

# First request
response=$(curl -v -X POST \
                -H "X-Repro-Token: ${API_TOKEN}" \
                -H "Content-Type: application/json" \
                --data "${body}" \
                ${AUDIENCES_URI})
echo $response

# Get the value needed for the second request from the response
url=$(echo ${response} | jq -r .direct_upload.url)
content_type=$(echo ${response} | jq -r '.direct_upload.headers["Content-Type"]')
content_md5=$(echo ${response} | jq -r '.direct_upload.headers["Content-MD5"]')

# Second request
curl -X PUT \
    -H "Content-Type: ${content_type}" \
    -H "Content-MD5: ${content_md5}" \
    --upload-file ${file} \
    "${url}"

echo done

オーディエンスの新規作成¶

以下の2ステップを実行することで、オーディエンスの新規作成を行うことができます。

POST /v3/audiences を実行し、S3にダイレクトアップロードするためのpre-signed URLを取得する
PUT <pre-signed URL> を実行し、S3にファイルをアップロードする

1回目のリクエスト¶

エンドポイント¶

機能	HTTPメソッド	エンドポイント
新規作成	`POST`	`https://api.reproio.com/v3/audiences`

リクエストヘッダー¶

ヘッダー	説明	任意 / 必須
Content-Type	application/jsonを指定します。	必須
X-Repro-Token	Repro API トークンの確認で取得したトークンを指定します。	必須

リクエストパラメータ¶

フィールド	説明	任意 / 必須
name	作成するオーディエンスの名前。	必須
checksum	ファイルのmd5 checksumをbase64エンコードしたもの。 `openssl dgst -md5 -binary hoge.csv \| base64` で算出することができます。	必須
byte_size	オーディエンスの作成・更新に利用するファイルのファイルサイズ	必須

ペイロード例¶

{
  "name": "audience name",
  "checksum": "J1h240z2CdsRjz2Et5mnkA==",
  "byte_size": "1024"
}

レスポンスヘッダー¶

レスポンスのヘッダーには、以下の値が含まれます。

ステータス	ヘッダー	説明
正常	`X-RateLimit-Limit`	単位時間あたりのアクセス上限
正常	`X-RateLimit-Remaining`	アクセスできる残り回数
正常	`X-RateLimit-Reset`	アクセス数がリセットされる時刻(unixtime)
リクエスト制限	`Retry-After`	再実行可能になるまでの秒数

正常系レスポンス¶

リクエスト成功時、レスポンスボディはJSON形式で以下の内容が返ってきます。

フィールド	説明
response.id	オーディエンスのID
response.name	オーディエンスの名前
response.direct_upload	2回目のリクエストに必要な情報を格納したオブジェクト
response.direct_upload.url	2回目のリクエストのエンドポイントURL
response.direct_upload.headers	2回目のリクエストに必要なヘッダー情報

正常系レスポンスボディ例¶

{
  "id": "ym6nnpkd",
  "direct_upload": {
    "url": "https://repro-direct-upload-production.s3.ap-northeast-1.amazonaws.com/Sx9367LtCmGDRdqfUJVjirRv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAITZGHBHURRYGMYHA%2F20200312%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20200312T062037Z&X-Amz-Expires=300&X-Amz-SignedHeaders=content-md5%3Bcontent-type%3Bhost&X-Amz-Signature=ef75a6b81944375822bcd4c2cdabf362bd02ccce5850577917b6b3fe087de0c5",
    "headers": {
      "Content-Type": "text/csv",
      "Content-MD5": "J1h240z2CdsRjz2Et5mnkA=="
    }
  },
  "name": "my-audience-api"
}

エラーレスポンス¶

レスポンスに含まれるステータスコードとエラーメッセージの一覧は下記になります。

400 Bad Request¶

リクエストにエラーがあります。エラーメッセージを確認の上、対応してください。

checksumに不正な文字列が含まれています。

レスポンスボディ:

{
  "error": {
    "messages": [
      "Validation failed: Checksum is invalid"
    ]
  }
}

byte_sizeが指定されていません。

レスポンスボディ:

{
  "error": {
    "messages": [
      "param is missing or the value is empty: byte_size"
    ]
  }
}

401 Unauthorized¶

Repro API トークンが指定されていません。

レスポンスボディ:

{
  "status": "unauthorized",
  "error": {
    "messages": [
      "Please include your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

403 Forbidden¶

指定した Repro API トークンが間違っています。

レスポンスボディ:

{
  "status": "forbidden",
  "error": {
    "messages": [
      "Please check your Repro API Token as \"X-Repro-Token\" HTTP header."
    ]
  }
}

404 Not Found¶

エンドポイントが存在しません。

レスポンスボディ:

{
  "status": "not_found",
  "error": {
    "messages": [
      "Not found."
    ]
  }
}

429 Too Many Requests¶

リクエスト数が多すぎます。 Retry-After ヘッダーに記載された秒数待った後、リクエストを再開してください。

レスポンスボディ:

{
  "status": "too_many_requests",
  "error": {
    "messages": [
      "Too many requests hit the API too quickly."
    ]
  }
}

2回目のリクエスト¶

エンドポイント¶

HTTPメソッド	エンドポイント
`PUT`	1回目のリクエストが成功した場合、レスポンスに含まれる `response.direct_upload.url` の値

リクエストヘッダー¶

1回目のリクエストが成功した場合、レスポンスに含まれる response.direct_upload.headers の値全てをヘッダーとして指定してください。

リクエストパラメータ¶

オーディエンスを作成するためのCSVファイルをセットしてください。セット可能なファイルサイズの上限は500MBです。ファイルの形式は、1行に1つのユーザーIDを指定した以下のようなCSVです。例えば qwpeoifjadlskf, zxocjvasdfoiji, azxcpoqnadslpx のようなユーザーIDを設定している場合、次のような形式のファイルになります。

qwpeoifjadlskf
zxocjvasdfoiji
azxcpoqnadslpx
:

正常系レスポンス¶

オーディエンスの作成に成功したら、 200 のステータスコードが返されます。

エラーレスポンス¶

エラーレスポンスについてはこちらのドキュメントを参照してください。

インポート結果のメールを受信する¶

インポートが完了すると、下記のようなメールが送信されます。 URLにアクセスし、インポート結果を確認してください。

オーディエンスの更新¶

以下の2ステップを実行することで、オーディエンスの更新を行うことができます。

PUT /v3/audiences/<オーディエンスID> を実行し、S3にダイレクトアップロードするためのpre-signed URLを取得する
PUT <pre-signed URL> を実行し、S3にファイルをアップロードする

以降の手順はサンプルコードと同様になります。こちらを参照してください。エンドポイントについては、以下管理画面上のオーディエンス詳細画面から確認することもできます。

オーディエンスAPI v2(廃止)¶

警告

オーディエンスAPI v2は2021年8月31日に廃止しました。 オーディエンスAPIをご利用する場合はオーディエンスAPI v3 をご利用ください。