リーチ禁止リスト

GET accounts/:account_id/do_not_reach_lists¶

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

注: account_id1件につき作成できるリーチ禁止リストは1つのみです。

リソースURL¶

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

パラメータ¶

リクエストの例¶

GET https://ads-api.x.com/10/accounts/18ce54bgxky/do_not_reach_lists

応答の例¶

{
  "request": {
    "params": {
      "account_id": "18ce54bgxky"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "targetable": false,
      "name": "Do Not Reach List",
      "description": "test DNRL",
      "id": "4kzrq",
      "reasons_not_targetable": [
        "TOO_SMALL"
      ],
      "created_at": "2021-10-28T22:09:29Z",
      "list_size": null,
      "updated_at": "2021-11-04T03:33:06Z",
      "deleted": false
    }
  ]
}

POST accounts/:account_id/do_not_reach_lists¶

現在のアカウントに関連付けられている新規のリーチ禁止リストを作成します。

注: account_id1件につき作成できるリーチ禁止リストは1つのみです。

リソースURL¶

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

パラメータ¶

リクエストの例¶

POST https://ads-api.x.com/10/accounts/18ce54bgxky/do_not_reach_lists?description=A list of users to exclude

応答の例¶

{
  "request": {
    "params": {
      "description": "A list of users to exclude",
      "account_id": "18ce54bgxky"
    }
  },
  "data": {
    "targetable": false,
    "name": "Do Not Reach List",
    "description": "A list of users to exclude",
    "id": "4ofrq",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2022-02-08T23:02:48Z",
    "list_size": null,
    "updated_at": "2022-02-08T23:02:48Z",
    "deleted": false
  }
}

POST batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users¶

このエンドポイントにより、指定したdo_not_reach_list_idでユーザーを追加、更新、削除できます。このエンドポイントは、有効なユーザーIDタイプとしてメールのみを受け入れます。

リクエストのemailsフィールドで提供されるすべてのデータは、SHA256を使用してハッシュ化し、正規化する必要があります。

注

• account_id1件につき作成できるリーチ禁止リストは1つのみです。
• このリストに追加されたユーザーは、expires_atタイムスタンプを現在のタイムスタンプから13か月未満に設定する必要があります
• リーチ禁止リストAPIではeffective_atタイムスタンプを使用できず、現在のタイムスタンプに初期設定されています
• リーチ禁止リストによってアカウントのいずれかまたはすべてのカスタムオーディエンスのユーザーが削除されることはありませんが、アカウントで実行されるすべてのキャンペーンでターゲティングから除外されます。

バッチリクエスト

• このエンドポイントの現在の最大バッチサイズは、2500です。バッチサイズは、リクエストあたりの操作数（Update/Delete）によって決まります。たとえば、1つの配列に2,500を超える操作オブジェクト（{"operation_type": "Update/Delete", [..] }）があると、エラーになります。
• このエンドポイントが受け入れることができるリクエストPOSTボディの最大サイズは5,000,000バイトです。
• このエンドポイントのレート制限は、1分あたり1,500です
• すべてのパラメータはリクエストボディで送信され、application/jsonのContent-Typeが必須です。
• バッチリクエストはグループ単位で失敗または成功となります。エラーの場合も、成功の場合も、API応答には、最初のリクエストの項目の順序が保持されます。

バッチ応答

広告APIから返される応答には、success_countとtotal_countの2つのフィールドがあります。これらの値は常に等しくなる必要があります。これらは、バックエンドで処理されたリクエスト内のレコード数のカウントです。リクエストボディで送信されたレコード数がsuccess_countとtotal_countに等しくない場合は、エラー状態として処理し、再試行が必要になります。

バッチエラー

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

リソースURL¶

https://ads-api.x.com/10/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users

パラメータ¶

リクエストの例¶

POST https://ads-api.x.com/10/batch/accounts/18ce54bgxky/do_not_reach_lists/4kzro/users

[
  {
    "operation_type": "Update",
    "params": {
      "effective_at": "2021-10-21T07:27:00Z",
      "expires_at": "2021-12-22T00:00:00Z",
      "emails": [
        "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC",
        "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
      ]
    }
  }
]

応答の例¶

{
  "data": [
    {
      "success_count": 2,
      "total_count": 2
    }
  ],
  "request": [
    {
      "params": {
        "do_not_reach_list_id": "4kzrq",
        "emails": [
          "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC",
          "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
        ],
        "account_id": "18ce54bgxky"
      },
      "operation_type": "Update"
    }
  ]
}

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id¶

現在のアカウントに属する、指定したリーチ禁止リストを削除します。

リソースURL¶

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

パラメータ¶

なし

リクエストの例¶

DELETE https://ads-api.x.com/10/accounts/18ce54bgxky/do_not_reach_lists/4ofrp

応答の例¶

{
  "request": {
    "params": {
      "do_not_reach_list_id": "4ofrp",
      "account_id": "18ce54bgxky"
    }
  },
  "data": {
    "targetable": false,
    "name": "Do Not Reach List",
    "description": null,
    "id": "4ofrp",
    "reasons_not_targetable": [
      "PROCESSING",
      "TOO_SMALL"
    ],
    "created_at": "2022-02-08T23:02:07Z",
    "list_size": null,
    "updated_at": "2022-02-08T23:02:21Z",
    "deleted": true
  }
}