予算使用状況APIの使用を開始する

予算使用状況は、個々のキャンペーンレベルとポートフォリオレベルの両方で確認できます。

各広告タイプには、独自の予算使用状況エンドポイントがあります。たとえば、スポンサープロダクト広告キャンペーンの予算使用状況を確認するには、POST /sp/campaigns/budget/usageエンドポイントを使用します。

ヒント

ポートフォリオの場合は、POST /portfolios/budget/usageエンドポイントを使用します。

広告タイプ	エンドポイント
スポンサープロダクト広告	POST /sp/campaigns/budget/usage
スポンサーブランド広告	POST /sb/campaigns/budget/usage
スポンサーディスプレイ広告	POST /sd/campaigns/budget/usage

1つ以上のキャンペーンの予算使用率の取得

この例は、スポンサーブランド広告キャンペーンの予算使用状況を取得する方法を示しています。3つのすべての広告タイプでパターンは同じです。

POST /sb/campaigns/budget/usage

リクエストボディ

使用状況リソースのリクエストオブジェクトは、リクエストごとに最大100のキャンペーンをサポートします。

{
` `"campaignIds":  [
  "campaign1"
 ]
}

レスポンスボディ

成功時のレスポンスは、207と予算使用状況レスポンスオブジェクトのリストを返します。このリストには、入力と同じ順序が反映されています。

{
` `"success":  [
  {
   "lastUpdatedDate":  "2022-01-05T02:45:32.486Z",
   "budgetUsagePercent": 0,
   "campaignId":  "campaign1",
   "index": 0,
   "budget": 0
 }
 ],
 "error":  [
  {
   "code":  "string",
   "campaignId":  "string",
   "index": 0,
   "details":  "string"
  }
 ]
}

その他の例

次の例は、usageリソースを取得する際に想定できるいくつかのシナリオを示しています。

この例は、リクエストされたすべてのcampaignIdsが正常に取得されていることを示しています。

リクエストボディ

{
 "campaignIds": [
  "campaign1",
  "campaign2",
  "campaign3"
 ]
}

レスポンスボディ

{
` `"success":  [
  {
   "lastUpdatedDate":  "2022-01-05T02:45:32.486Z",
   "budgetUsagePercent": 50,
   "campaignId":  "campaign1",
   "index":  0,
   "budget": 100
  }
  {
   "lastUpdatedDate": "2022-01-05T02:45:32.486Z",
   "budgetUsagePercent": 60,
   "campaignId": "campaign2",
   "index": 1,
   "budget": 100
  }
  {
   "lastUpdatedDate": "2022-01-05T02:45:32.486Z",
   "budgetConsumptionPercent": 75,
   "campaignId": "campaign3",
   "index": 2,
   "budget": 100
  }
 ],
 "error":  [
 ]
}

この例では、campaign1は正常に取得されましたが、campaign2とcampaign3ではエラーが発生しました。

リクエストボディ

{
 "campaignIds": [
  "campaign1",
  "campaign2",
  "campaign3"
 ]
}

レスポンスボディ

{
` `"success":  [
  {
   "lastUpdatedDate":  "2022-01-05T02:45:32.486Z",
   "budgetUsagePercent":  50,
   "campaignId":  "campaign1",
   "index":  0,
   "budget":  100
  }
 ],
 "error": [
  {
   "code": "string",
   "campaignId": "campaign2",
   "index": 1,
   "details": "string"
  }
  {
   "code": "string",
   "campaignId": "campaign3",
   "index": 2,
   "details": "string"
  }
 ]
}

ポートフォリオの予算使用率の取得

ポートフォリオは、ブランド別、製品カテゴリー別、またはシーズン別に整理できるキャンペーンのグループです。この例は、リクエストされたすべてのportfolioIdsが正常に取得されていることを示しています。

注

各キャンペーンに関連付けられている個々の予算使用率を表示するには、その広告タイプのリストキャンペーンリソースを使用し、ヘッダーでportfolioIdFilterパラメーターを使用して、portfolioIdFilterパラメーターで指定したポートフォリオIDに関連付けられているキャンペーンオブジェクトの配列を取得する必要があります。次に、前述のように、関連付けられているキャンペーン予算使用状況リソースを使用して、各キャンペーン予算使用率を取得できます。

POST /portfolios/budget/usage

リクエストボディ

使用状況リソースのリクエストオブジェクトは、リクエストごとに最大100のポートフォリオをサポートします。

{
 "portfolioIds": [
  "`portfolio1`",
  "portfolio2",
  "portfolio3"
 ]
}

レスポンスボディ

{
` `"success":  [
  {
   "lastUpdatedDate":  "2022-01-05T02:45:32.486Z",
   "budgetUsagePercent":  50,
   "portfolioId":  "portfolio1",
   "index":  0,
   "budget":  100
  }
 ],
 "error": [
  {
   "code": "string",
   "portfolioId": "portfolio2",
   "index": 1,
   "details": "string"
  }
  {
   "code": "string",
   "portfolioId": "portfolio3",
   "index": 2,
   "details": "string"
  }
 ]
}