リーチ禁止リスト

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

パラメータ

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t

with_deleted
任意

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

タイプ: ブール値

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

リクエストの例

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

パラメータ

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t

description
任意

このオーディエンスの説明。

タイプ: 文字列

例: A list of users to exclude

リクエストの例

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/jsonContent-Typeが必須です。
  • バッチリクエストはグループ単位で失敗または成功となります。エラーの場合も、成功の場合も、API応答には、最初のリクエストの項目の順序が保持されます。

バッチ応答

広告APIから返される応答には、success_counttotal_countの2つのフィールドがあります。これらの値は常に等しくなる必要があります。これらは、バックエンドで処理されたリクエスト内のレコード数のカウントです。リクエストボディで送信されたレコード数がsuccess_counttotal_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

パラメータ

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t

do_not_reach_list_id
必須

リクエスト内で操作するリーチ禁止リストへの参照

タイプ: 文字列

例: 2906h

operation_type
必須

実行中の、usersごとのグループ操作タイプ。

タイプ: 列挙

使用可能な値: UpdateDelete

params
必須

emails配列とexpires_atタイムスタンプを含むJSONオブジェクト。

タイプ: JSON

emails
必須

個々のユーザーに対応するハッシュ化されたメールアドレスの配列。

タイプ: JSON

例: ["FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC", "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"]

expires_at
任意

ユーザーの関連付けが期限切れになるUTC時間。指定する時間は、現在のタイムスタンプの値より後である必要があります。ISO 8601で表します。初期設定では、現在のタイムスタンプから13か月に設定されています。

タイプ: 文字列

例: 2017-07-05T07:00:00Z

リクエストの例

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
  }
}