事前準備
ad-product:readとad-product:writeのスコープを持つAPIキーが必要です。この2つのスコープは、コンソールの [設定] > [連携] メニューでは選択できません。Adropにご依頼いただければ、2つのスコープを含むキーを発行します。アプリAPI、広告ユニットAPI、オーディエンスターゲティングAPIのスコープも同じキーにまとめて付与できます。- 2つのスコープは別々に確認されます。
ad-product:writeだけのキーは、取得(GET)リクエストで403を受け取ります。作成・更新・削除の取り消しのレスポンスには商品全体が含まれますが、商品を別途取得するにはad-product:readも必要です。 - 商品に入れる広告ユニットIDは、広告ユニットAPIで取得するか、コンソールの 広告ユニット メニューで確認します。ターゲティングIDとターゲティングオプションのIDは、オーディエンスターゲティングAPIとコンテキストターゲティングAPIで取得します。
基本情報
429を受け取ったら、Retry-Afterヘッダーの秒数だけ待ってから再送信してください。サーバーが混雑しているときは、リクエストを1件ずつ送っても429を受け取ることがあります。リクエストの上限は上限を参照してください。
エンドポイント
パスはBase URLを基準とします。商品の作成
新しい広告商品を作成します。リクエスト
ad-product:writeスコープが必要です。リクエスト本文に入れられるフィールドはリクエスト本文を参照してください。
必須フィールド
省略したフィールドは次のデフォルト値で作成されます。
インハウス商品は、
title、pricing.pricingType: "INHOUSE"、unitGroupsだけを送れば作成できます。非公開(private: true)、単価・商品割引率・最低予算0などの残りの値は自動で設定されます。これらのフィールドを一緒に送る場合は、自動で設定される値と同じ値のみ送れます。異なる値は400を返します。
リクエスト例
レスポンス例
201で、作成した商品を商品オブジェクトとして返します。
作成リクエストは冪等(idempotent)ではありません。レスポンスを受け取れずに同じリクエストを再送信すると、商品が重複して作成されることがあります。再送信する前に、商品一覧で商品が作成されたか確認してください。
エラー
400: リクエスト本文が商品ルールに合っていません。エラー処理を参照してください。409 AD_PRODUCT_LIMIT_EXCEEDED: プロジェクトの商品がすでに1,000件あります。削除予約中の商品も件数に含まれます。
商品オブジェクト
取得、作成、更新、削除の取り消しのエンドポイントは、次の形式で商品を返します。商品一覧の取得はこのうち一部だけを返します。discountRate、minBudget、frequencyは、値がない場合に0で埋めて返すことはありません。値がない場合は、更新時にも送らないでください。frequencyに0を送ると、制限なしになります。- コンソールでのみ設定できる商品オプションはレスポンスに含まれません。APIで商品を更新しても、これらのオプションはそのまま維持されます。
- インハウス商品は、
privateがtrue、price・discountRate・minBudget・metric.eCTRが0、metric.eImpressionsが9007199254740991に固定されます。
リクエスト本文
作成と更新のリクエスト本文には、次のフィールドを入れられます。ここにないフィールドと、レスポンスにのみあるフィールド(_id、createdAt、updatedAt、deleteAt、unitGroups[].fixRequired、targetings[].kind)を送ると、400 VALIDATION_FAILEDを返します。
商品ルール
リクエスト本文を下の商品ルールで確認します。ルールに違反すると400 AD_PRODUCT_VALIDATION_FAILEDを返し、違反した箇所をdetail.errorsで知らせます。ただし、広告商品名が空文字列の場合や、課金タイプが一覧にない値の場合は、リクエスト形式のエラー(400 VALIDATION_FAILED)を返します。
クリエイティブセット
unitGroupsの1項目が、コンソールのクリエイティブセット1つにあたります。nameは広告主に表示されるクリエイティブセット名で、unitsはそのセットに入れる広告ユニットIDの一覧です。
- 1つのクリエイティブセットのユニットは、フォーマット、サイズ、オプション(テンプレート、透かしなど)が同じである必要があります。新しく入れたユニットがセットの基準と異なる場合は
400 AD_UNIT_FIX_REQUIREDを返します。基準はクリエイティブセットを設定するを参照してください。 - 同じユニットIDは、すべてのクリエイティブセットを通して1回だけ入れられます。
- フォーマット、サイズ、オプションが同じクリエイティブセット同士は、同じ名前にできません。
- 新しく作るクリエイティブセットには、ユニットが1つ以上必要です。
- 商品には、セットの基準に合うユニットが1つ以上残っている必要があります。修正必要ステータスのユニットは数えません。
fixRequiredは、商品に入れた後にユニットのフォーマット、サイズ、オプションが変わり、クリエイティブセットの基準に合わなくなったユニットです。コンソールの 修正必要 ステータスと同じです。これらのユニットがある商品では新しいキャンペーンを予約できない(既存のキャンペーンはそのまま運用されます)ため、ユニットの設定を元に戻すか、クリエイティブセットから外してください。
広告ユニットAPIで商品に含まれるユニットの設定を変更したり、ユニットを削除したりすると、商品のクリエイティブセットにも影響します。
ターゲティングポリシー
targetingsの1項目が、商品に表示するターゲティング1つにあたります。コンソールと同じく、1つの商品にはオーディエンスターゲティングかコンテキストターゲティングのどちらか一方だけを入れてください。
policyには、コンソールの適用方法と同じ値を入れます。
policiesのキーには、そのターゲティングの最上位オプションのIDだけを入れられます。オプショングループはグループのIDを入れ、下位オプションのIDは入れません。ほかのIDを入れると400 AD_PRODUCT_TARGETING_INVALIDを返します。- 含む(
included)と除外(excluded)のポリシーは、商品ごとに500件まで入れられます。選択(any)には上限がありません。 - 含むまたは除外のポリシーがあるコンテキストターゲティングがある場合、ポリシーがあるほかのコンテキストターゲティングを同じ商品に一緒に入れることはできません(
400 TARGETING_CONTEXT_EXCLUSIVE)。 - 同じターゲティングを2回入れると
400 TARGETING_DUPLICATED_IN_REQUESTを返します。 - ほかのプロジェクトのターゲティングIDや存在しないターゲティングIDは
400 AD_PRODUCT_TARGETING_INVALIDを返します。
商品一覧の取得
プロジェクトの商品を新しい順に、ページ単位で返します。削除予約中の商品もdeleteAt付きで含まれます。
リクエスト
ad-product:readスコープが必要です。
クエリパラメーター
リクエスト例
レスポンス例
200で、items(商品の一覧)とnext(次のページのカーソル)を返します。nextがなければ最後のページです。
targetingsにpoliciesがありません。ポリシーが必要な場合は、商品の取得で商品ごとに読み込んでください。unitGroupsには、ユニットIDの代わりにunitCount(ユニット数)とfixRequiredCount(修正必要のユニット数)が入っています。
nextで続きを読み込んでください。
商品の取得
1つの商品をターゲティングポリシーと一緒に返します。リクエスト
ad-product:readスコープが必要です。
リクエスト例
レスポンス
200で商品オブジェクトを返します。
policiesには、現在そのターゲティングの最上位オプションのポリシーだけが入っています。削除されたオプションや、オプショングループの下に移されたオプションのポリシーはレスポンスに含まれません。- オプションの多いコンテキストターゲティングを使う商品は、レスポンスが大きくなることがあります。必要な商品だけを取得してください。
エラー
404 AD_PRODUCT_NOT_FOUND: 商品が存在しないか、ほかのプロジェクトの商品です。
商品の更新
送ったフィールドだけを変更します。リクエスト
ad-product:writeスコープが必要です。リクエスト本文はリクエスト本文と同じです。
クエリパラメーター
変更のされ方
- 送らなかったフィールドはそのままです。空の本文
{}を送っても何も変わりません。 unitGroupsとtargetingsは、配列全体が送った内容に置き換わります。送らなかったクリエイティブセットとターゲティングは商品から外れます。pricing、metric、options、localeのオブジェクトは、送ったキーだけが変わります。targetingsの項目でpoliciesを省略すると、そのターゲティングのポリシーはそのままです。policiesを送ると送った一覧に置き換わり、一覧にない最上位オプションのポリシーは削除されます。- クリエイティブセットは同じ名前の既存のクリエイティブセットと対応付けられ、新しく入れたユニットだけを確認します。すでに入っていた修正必要のユニットはそのまま送ってかまいません。
- 課金タイプを
INHOUSEに変えると、インハウスで設定される値も一緒に変わります。 - 広告商品名を空にしたり、商品のユニットをすべて外したりすることはできません。
unitGroupsやtargetingsのように配列全体を置き換える更新は、その間にコンソールで変更した内容を上書きすることがあるため、ifUpdatedAtを一緒に送ってください。
リクエスト例
レスポンス
200で、更新した商品オブジェクトを返します。
エラー
404 AD_PRODUCT_NOT_FOUND: 商品が存在しないか、ほかのプロジェクトの商品です。409 AD_PRODUCT_CONFLICT:ifUpdatedAtが商品のupdatedAtと異なります。商品を取得し直してから更新してください。409 AD_PRODUCT_MUTATION_NOT_ACCEPTABLE: 削除予約中の商品です。先に削除の取り消しを行ってください。
商品の削除
商品の削除を予約します。予約した商品は、削除予定時刻(deleteAt)までは削除の取り消しで元に戻せます。
リクエスト
ad-product:writeスコープが必要です。
リクエスト例
レスポンス例
200で、商品IDと削除予定時刻を返します。
- この商品のキャンペーンのうち最も遅く終わるキャンペーンの終了時刻が現在より後であれば、その3日後が削除予定時刻です。そうでなければ、現在から3日後です。
- 削除予定時刻を過ぎると、通常1分以内に商品が削除され、その後の取得には
404を返します。 - 削除予約中の商品も一覧と取得のレスポンスに
deleteAt付きで表示され、プロジェクトの商品数に含まれます。もう一度削除すると、削除予定時刻を計算し直します。
エラー
404 AD_PRODUCT_NOT_FOUND: 商品が存在しないか、ほかのプロジェクトの商品です。
削除の取り消し
削除予約を取り消して、商品を元に戻します。リクエスト
ad-product:writeスコープが必要です。リクエスト本文は送りません。
リクエスト例
レスポンス
200で、元に戻した商品オブジェクトを返します。削除予約中でない商品も200を返し、その場合は何も変わりません。
エラー
404 AD_PRODUCT_NOT_FOUND: 商品が存在しないか、ほかのプロジェクトの商品か、すでに削除された商品です。
エラー処理
エラーレスポンス
エラーレスポンスにはstatusCodeが含まれ、下の表でerrorCodeの欄が-ではないエラーにはerrorCodeも含まれます。リクエストのどの部分が誤っているかを知らせるエラーは、detailも一緒に返します。処理はerrorCodeで分け、errorCodeがない場合はstatusCodeで分けてください。
detail.errors[]のpathは誤ったフィールドの位置(pricing.price、unitGroups[0].name、targetings[0].policies.<オプションID>など)で、valueは送った値です。detail.errorsには最大100件まで含まれるため、すべて直して再送信すると残りのエラーが表示されます。リクエスト形式のエラー(VALIDATION_FAILED)にはmessageとerrorフィールドも含まれます。
エラーコード
再送信
429の場合は、Retry-Afterヘッダーの時間だけ待ってから再送信してください。- 書き込みリクエスト(
POST、PATCH、DELETE、削除の取り消し)が502を受け取ったか、レスポンスなしで切断された場合は、リクエストが反映されている可能性があります。再送信する前に商品を取得して確認してください。作成リクエストは冪等ではないため、そのまま再送信すると商品が重複して作成されることがあります。 ifUpdatedAtを付けた更新リクエストを再送信する場合、前のリクエストが反映されていると409 AD_PRODUCT_CONFLICTを受け取ることがあります。商品を取得し直して確認してください。