targetingsに入れるターゲティングIDとオプションIDを調べたり、オプションに設定したプロパティ・イベントの条件を確認したりするときに使います。
このAPIでできるのは取得のみです。オーディエンスターゲティングを作成・更新するには、コンソールを使ってください。オーディエンスターゲティングの作成を参照してください。コンテキストターゲティングはコンテキストターゲティングAPIで扱います。
事前準備
audience-targeting:readスコープを持つAPIキーが必要です。このスコープは、コンソールの [設定] > [連携] メニューでは選択できません。Adropにご依頼いただければ、スコープを含むキーを発行します。広告商品APIのスコープも、同じキーにあわせて含めることができます。
基本情報
429を受け取ったら、Retry-Afterヘッダーの秒数だけ待ってから再送信してください。サーバーが混雑しているときは、リクエストを1件ずつ送っても429を受け取ることがあります。
用語
APIのパスやフィールドには、コンソールと異なる名前が使われているものがあります。本ドキュメントではコンソールの名称を使います。エンドポイント
パスはBase URLを基準とします。すべてのエンドポイントにaudience-targeting:readスコープが必要です。
ターゲティングオブジェクト
ターゲティングオブジェクトにはオプションが含まれません。オプションはオプション一覧の取得で読み込みます。
ターゲティング一覧の取得
プロジェクトのすべてのオーディエンスターゲティングを、コンソールに表示される順に、ページに分けずに一度に返します。コンテキストターゲティングは含まれません。リクエスト
リクエスト例
レスポンス例
200で、ターゲティングオブジェクトの配列を返します。
ターゲティングの取得
1つのターゲティングを返します。リクエスト
リクエスト例
レスポンス
200でターゲティングオブジェクトを返します。
エラー
404 TARGETING_NOT_FOUND: ターゲティングが存在しないか、ほかのプロジェクトのターゲティングか、コンテキストターゲティングです。
オプションオブジェクト
オプションの取得は、これに
targeting(所属するターゲティングのID)、convertible、conditionsを加えて返します。
オプション一覧の取得
ターゲティングの最上位オプションを、コンソールに表示される順に、ページ単位で返します。オプショングループの下位オプションは、parentで別途読み込みます。
リクエスト
クエリパラメーター
リクエスト例
レスポンス例
200で、items(オプションオブジェクトの一覧)とnext(次のページのカーソル)を返します。nextがなければ最後のページです。
- オプション一覧には条件が含まれません。条件はオプションの取得で読み込みます。
usersが0の場合は、ユーザー統計がまだ蓄積されていないか、統計を一時的に読み込めなかった可能性があります。0だけでオプションを判断せず、疑わしい場合は少し時間をおいてから取得し直してください。- ページを読み込んでいる途中でオプションが追加・削除・移動されると、結果が実際と異なることがあります。
nextに指定したオプションがその間に削除または移動されると404 TARGETING_CATEGORY_NOT_FOUNDを返すため、最初のページから読み込み直してください。
エラー
400 TARGETING_CATEGORY_NOT_SUPPORTED:parentがオプショングループではなく、通常のオプションです。404 TARGETING_NOT_FOUND: ターゲティングが存在しないか、ほかのプロジェクトのターゲティングか、コンテキストターゲティングです。404 TARGETING_CATEGORY_NOT_FOUND:nextがこのターゲティングの最上位オプションではない(削除・移動された)か、parentがこのターゲティングのオプションではありません。
オプションの取得
1つのオプションを条件と一緒に返します。リクエスト
リクエスト例
レスポンス例
200で、オプションオブジェクトに次のフィールドを加えて返します。usersは含まれません。
エラー
404 TARGETING_CATEGORY_NOT_FOUND: オプションが存在しないか、ほかのプロジェクトのオプションか、オーディエンスターゲティングに属するオプションではありません。
条件
conditionsは、オプションの条件をall(かつ)とany(または)でまとめたツリーです。広告配信で実際に使われる条件と同じ意味で表します。
ノード
- 最も外側は常に
allまたはanyです。条件が1つだけの場合は{ "all": [条件] }です。 - 同じ種類のノードを重ねて使うことはありません。たとえば、
allのすぐ内側にallが来ることはありません。
levelが10以上で、直近30日以内にitem_categoryがbookの購入を1回以上したユーザー)または(性別がFのユーザー)」を表します。
プロパティ条件
イベント条件
コンソールでイベント条件を複数つなげると、広告配信では決められたルールで結合されるため、コンソールで or でつないだ条件が、ツリーでは
allとして表示されることがあります。ツリーのallとanyにそのまま従ってください。
オプショングループの条件
オプショングループには独自の条件がなく、下位オプションの条件のいずれかを満たすと含まれます。そのため、オプショングループのconditionsは、下位オプションの条件をanyでまとめたものです。
- 下位オプションの条件が
anyで始まる場合は、その中の条件が外側のanyに直接入るため、分岐の数が下位オプションの数と異なることがあります。 - 下位オプションが1つだけの場合は、
anyで囲まず、その下位オプションの条件をそのまま返します。 - 条件のない下位オプションはスキップします。
条件を読み取れない場合
2つの値は互いに関係ありません。
convertibleがtrueで、operableがfalseの場合もあります。
エラー処理
エラーレスポンスにはstatusCodeが含まれ、下の表でerrorCodeの欄が-ではないエラーにはerrorCodeも含まれます。処理はerrorCodeで分け、errorCodeがない場合はstatusCodeで分けてください。リクエスト形式のエラー(VALIDATION_FAILED)では、誤っている箇所をdetail.errors[]のpathで知らせます。