Campaign management

キャンペーン

Postmanで実行 ❯

GET accounts/:account_id/campaigns

現在のアカウントに関連付けられている一部またはすべてのキャンペーンの詳細を取得します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/campaigns

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t
campaign_ids
任意

カンマ区切りのIDリストを指定して、応答の範囲を目的のキャンペーンのみに設定します。最大200件のIDを指定できます。

タイプ: 文字列

例: 8wku2
count
任意

個別のリクエストごとに試行および取得するレコード数を指定します。

タイプ: 整数

デフォルト: 200
最小、最大: 1、1000
cursor
任意

結果の次のページを取得するためのカーソルを指定します。詳細については、「ページネーション」を参照してください。

タイプ: 文字列

例: 8x7v00oow
funding_instrument_ids
任意

カンマ区切りのIDリストを指定して、応答の範囲を特定のお支払い方法のキャンペーンのみに設定します。最大200件のIDを指定できます。

タイプ: 文字列

例: lygyi
q
任意

リソースをnameごとに範囲設定する任意のクエリ。

タイプ: 文字列

最小および最長の長さ: 1、255
sort_by
任意

サポートされている属性で昇順または降順に並べ替えます。詳細については、「並べ替え」を参照してください。

タイプ: 文字列

例: created_at-asc
with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: true、false
with_draft
任意

リクエストに下書きキャンペーンの結果を含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: true、false
with_total_count
任意

total_count応答属性を含めます。

注: このパラメーターとcursorとは相互に排他的です。

注: total_countを含むリクエストの場合、レート制限が低くなります。現在15分あたり200に設定されています。

タイプ: ブール値

デフォルト: false
使用可能な値: true、false

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/campaigns?campaign_ids=8wku2

応答の例

{
  "request": {
    "params": {
      "campaign_ids": [
        "8wku2"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "batch campaigns",
      "start_time": "2017-06-30T00:00:00Z",
      "reasons_not_servable": [
        "PAUSED_BY_ADVERTISER",
        "INCOMPLETE"
      ],
      "servable": false,
      "daily_budget_amount_local_micro": 140000000,
      "end_time": null,
      "funding_instrument_id": "lygyi",
      "standard_delivery": true,
      "total_budget_amount_local_micro": null,
      "id": "8wku2",
      "entity_status": "PAUSED",
      "currency": "USD",
      "created_at": "2017-06-30T21:17:16Z",
      "updated_at": "2017-06-30T21:17:16Z",
      "deleted": false
    }
  ]
}

GET accounts/:account_id/campaigns/:campaign_id

現在のアカウントに関連付けられている特定のキャンペーンを取得します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/campaigns/:campaign_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t
campaign_id
必須

リクエスト内で操作するキャンペーンへの参照。

タイプ: 文字列

例: 8wku2
with_deleted
任意

削除した結果をリクエストに含めます。

タイプ: ブール値

デフォルト: false
使用可能な値: true、false

リクエストの例

GET https://ads-api.x.com/10/accounts/18ce54d4x5t/campaigns/8wku2

応答の例

{
  "request": {
    "params": {
      "campaign_id": "8wku2",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "batch campaigns",
    "start_time": "2017-06-30T00:00:00Z",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": null,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": null,
    "id": "8wku2",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-06-30T21:17:16Z",
    "updated_at": "2017-06-30T21:17:16Z",
    "deleted": false
  }
}

POST accounts/:account_id/campaigns

現在のアカウントに関連付けられている新しいキャンペーンを作成します。

注: アカウントあたり200件のアクティブキャンペーンのデフォルト制限があります。ただし、非アクティブキャンペーンの数に制限はありません。このアクティブキャンペーンの制限は8,000件に引き上げることができます。上限を引き上げるには、広告主はTwitterアカウントマネージャーにリクエストを送信する必要があります。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/campaigns

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t
funding_instrument_id
必須

キャンペーンを作成するお支払い方法のID。

タイプ: 文字列

例: lygyi
name
必須

キャンペーンの名前。最大長: 255文字。

タイプ: 文字列

例: demo
start_time
必須

キャンペーンの開始時間（ISO 8601で表したもの）。

タイプ: 文字列

例: 2017-07-05T00:00:00Z
daily_budget_amount_local_micro
必須の場合あり

キャンペーンに割り当てる日別予算額。指定したお支払い方法に関連付けられている通貨が使用されます。米国ドル（USD）の場合、$5.50は5,500,000として表されます。

注: この値はtotal_budget_amount_local_micro以下である必要があり、ほとんどの支払い方法の種類で必須です。

タイプ: 長整数型

例: 5500000
end_time
任意

キャンペーンの終了時間（ISO 8601で表したもの）。

タイプ: 文字列

例: 2017-10-05T00:00:00Z
entity_status
任意

キャンペーンのステータス。

タイプ: 列挙

デフォルト: ACTIVE
使用可能な値: ACTIVE、DRAFT、PAUSED
purchase_order_number
任意

予約参照番号。このフィールドを使用すると請求書を照合しやすくなります。最大長: 50文字。

タイプ: 文字列

例: D00805843
standard_delivery
任意

標準配信または集中配信を有効にします。標準配信と集中配信の詳細については、「予算のペーシング」を参照してください。

タイプ: ブール値

デフォルト: true
使用可能な値: true、false
total_budget_amount_local_micro
任意

キャンペーンに割り当てる合計予算額。指定したお支払い方法に関連付けられている通貨が使用されます。米国ドル（USD）の場合、$37.50は37,500,000として表されます。

タイプ: 長整数型

例: 37500000

リクエストの例

POST https://ads-api.x.com/10/accounts/18ce54d4x5t/campaigns?funding_instrument_id=lygyi&name=demo&start_time=2017-07-05&daily_budget_amount_local_micro=140000000&entity_status=PAUSED

応答の例

{
  "data": {
    "name": "demo",
    "start_time": "2017-07-05T00:00:00Z",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": 140000000,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": null,
    "id": "8slvg",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-06-23T01:59:12Z",
    "updated_at": "2017-06-23T01:59:12Z",
    "deleted": false
  },
  "request": {
    "params": {
      "name": "demo",
      "start_time": "2017-07-05T00:00:00Z",
      "daily_budget_amount_local_micro": 140000000,
      "funding_instrument_id": "lygyi",
      "entity_status": "PAUSED",
      "account_id": "18ce54d4x5t"
    }
  }
}

POST batch/accounts/:account_id/campaigns

1回のリクエストで新しいキャンペーンをバッチ作成できます。

バッチリクエスト

  • 現在の最大バッチサイズは40です。
  • すべてのパラメーターはリクエストボディで送信され、application/jsonのContent-Typeが必須です。
  • バッチリクエストはグループ単位で失敗または成功となります。エラーの場合も、成功の場合も、API応答には、最初のリクエストの項目の順序が保持されます。

バッチ応答

バッチAPIの応答は、項目のコレクションを順番どおりに返します。その点を除くと、バッチAPIの構造は、対応する単一項目のエンドポイントと同じです。

バッチエラー

  • リクエストレベルのエラー（最大バッチサイズの超過など）は、errorsオブジェクトの応答に表示されます。
  • 項目レベルのエラー（必須キャンペーンパラメーターの不足など）は、operation_errorsオブジェクトの応答に表示されます。

リソースURL

https://ads-api.x.com/10/batch/accounts/:account_id/campaigns

パラメーター

名前 説明
operation_type
必須

実行中の、項目ごとの操作タイプ。

タイプ: 列挙

使用可能な値: Create、Delete、Update
params
必須
 キャンペーンオブジェクトのすべてのパラメーターを含むJSONオブジェクト。必須および任意のキャンペーンパラメーターの一覧については、こちらを参照してください。

リクエストの例

POST 'Content-Type: application/json' https://ads-api.x.com/10/batch/accounts/18ce54d4x5t/campaigns

[  
  {  
    "operation_type":"Create",
    "params":{  
      "start_time":"2017-07-10",
      "name":"batch campaigns",
      "funding_instrument_id":"lygyi",
      "daily_budget_amount_local_micro":140000000,
      "entity_status":"PAUSED"
    }
  }
]

応答の例

{
  "data": [
    {
      "name": "batch campaigns",
      "start_time": "2017-07-10T00:00:00Z",
      "reasons_not_servable": [
        "PAUSED_BY_ADVERTISER",
        "INCOMPLETE"
      ],
      "servable": false,
      "daily_budget_amount_local_micro": 140000000,
      "end_time": null,
      "funding_instrument_id": "lygyi",
      "standard_delivery": true,
      "total_budget_amount_local_micro": null,
      "id": "8yn7m",
      "entity_status": "PAUSED",
      "currency": "USD",
      "created_at": "2017-07-07T17:28:50Z",
      "updated_at": "2017-07-07T17:28:50Z",
      "deleted": false
    }
  ],
  "request": [
    {
      "params": {
        "name": "batch campaigns",
        "start_time": "2017-07-10T00:00:00Z",
        "funding_instrument_id": "lygyi",
        "daily_budget_amount_local_micro": 140000000,
        "entity_status": "PAUSED",
        "account_id": "18ce54d4x5t"
      },
      "operation_type": "Create"
    }
  ]
}

PUT accounts/:account_id/campaigns/:campaign_id

現在のアカウントに関連付けられている指定されたキャンペーンを更新します。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/campaigns/:campaign_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t
campaign_id
必須

リクエスト内で操作するキャンペーンへの参照。

タイプ: 文字列

例: 8wku2
daily_budget_amount_local_micro
任意

キャンペーンに割り当てる日別予算額。指定したお支払い方法に関連付けられている通貨が使用されます。米国ドル（USD）の場合、$5.50は5,500,000として表されます。指定しない場合、合計予算とキャンペーンの配信時間に基づいてキャンペーンの支出額は均等になります。

注: これはtotal_budget_amount_local_micro以下でなければなりません。

タイプ: 長整数型

例: 5500000
end_time
任意

キャンペーンの終了時間（ISO 8601で表したもの）。

タイプ: 文字列

例: 2017-10-05T00:00:00Z
entity_status
任意

キャンペーンのステータス。

タイプ: 列挙

使用可能な値: ACTIVE、PAUSED
name
任意

キャンペーンの名前。最大長: 255文字。

タイプ: 文字列

例: demo
purchase_order_number
任意

予約参照番号。このフィールドを使用すると請求書を照合しやすくなります。最大長: 50文字。

タイプ: 文字列

例: D00805843
standard_delivery
任意

標準配信または集中配信を有効にします。標準配信と集中配信の詳細については、「予算のペーシング」を参照してください。

タイプ: ブール値

デフォルト: true
使用可能な値: true、false
start_time
任意

キャンペーンの開始時間（ISO 8601で表したもの）。

タイプ: 文字列

例: 2017-07-05T00:00:00Z
total_budget_amount_local_micro
任意

キャンペーンに割り当てる合計予算額。指定したお支払い方法に関連付けられている通貨が使用されます。米国ドル（USD）の場合、$37.50は37,500,000として表されます。

タイプ: 長整数型

例: 140000000

リクエストの例

PUT https://ads-api.x.com/10/accounts/18ce54d4x5t/campaigns/8wku2?total_budget_amount_local_micro=140000000

応答の例

{
  "data": {
    "name": "batch campaigns",
    "start_time": "2017-06-30T00:00:00Z",
    "reasons_not_servable": [
      "PAUSED_BY_ADVERTISER",
      "INCOMPLETE"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": null,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": 140000000,
    "id": "8wku2",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-06-30T21:17:16Z",
    "updated_at": "2017-07-04T21:41:49Z",
    "deleted": false
  },
  "request": {
    "params": {
      "campaign_id": "8wku2",
      "total_budget_amount_local_micro": 140000000,
      "account_id": "18ce54d4x5t"
    }
  }
}

DELETE accounts/:account_id/campaigns/:campaign_id

現在のアカウントに属する、指定されたキャンペーンを削除します。

注: キャンペーンの削除は元に戻すことができず、その後にリソースを削除しようとするとHTTP 404が返されます。

リソースURL

https://ads-api.x.com/10/accounts/:account_id/campaigns/:campaign_id

パラメーター

名前 説明
account_id
必須

利用するアカウントのID。リソースのパス内に表示され、通常、GET accountsを除くすべての広告主APIリクエストに必須のパラメーターです。指定するアカウントは、認証済みユーザーに関連付けられている必要があります。

タイプ: 文字列

例: 18ce54d4x5t
campaign_id
必須

リクエスト内で操作するキャンペーンへの参照。

タイプ: 文字列

例: 8yn7m

リクエストの例

DELETE https://ads-api.x.com/10/accounts/18ce54d4x5t/campaigns/8yn7m

応答の例

{
  "data": {
    "name": "batch campaigns",
    "start_time": "2017-07-10T00:00:00Z",
    "reasons_not_servable": [
      "DELETED"
    ],
    "servable": false,
    "daily_budget_amount_local_micro": 140000000,
    "end_time": null,
    "funding_instrument_id": "lygyi",
    "standard_delivery": true,
    "total_budget_amount_local_micro": null,
    "id": "8yn7m",
    "entity_status": "PAUSED",
    "currency": "USD",
    "created_at": "2017-07-07T17:28:50Z",
    "updated_at": "2017-08-09T07:35:30Z",
    "deleted": true
  },
  "request": {
    "params": {
      "campaign_id": "8yn7m",
      "account_id": "18ce54d4x5t"
    }
  }
}