オーディエンス

カスタムオーディエンス

概要

パートナーがカスタムオーディエンスを作成する方法はいくつかあります。

Audience API (CRM)
Web
Mobile
Flexible

類似カスタムオーディエンスをターゲティングから除外することはできません。さらに、同じ広告ラインアイテム (広告グループ) 内で、カスタムオーディエンスとカスタムオーディエンス類似を同時にターゲティングすることはできません。 オーディエンス管理 オーディエンスは、オーディエンスパートナーおよび Ads API パートナー経由で管理できます。API では、カスタムオーディエンスにアクセスして管理するための一連のエンドポイントを提供しています。カスタムオーディエンス情報については、次の 2 つのエンドポイントを提供しています。

オーディエンスのアップロードと管理方法の詳細については、Audience API ガイドを参照してください。 処理時間 一般的に、オーディエンスの変更は 6～8 時間ごとに実行されるバッチで処理されます。オーディエンスの変更が処理中であっても、更新対象となる既存のオーディエンス自体には影響しません。この時間枠内では、1 つのオーディエンスにつき、追加に関する更新は 1 回、削除に関する更新も 1 回を超えて実行しないことを推奨します。 ターゲティング オーディエンスは、過去 90 日以内に X が所有・運営するクライアント上でアクティブだったユーザーが少なくとも 100 人一致している場合にのみターゲティングできます。GET accounts/:account_id/custom_audiences/:custom_audience_id は、一致するユーザー数が少なすぎるためにオーディエンスをターゲティングできない場合、その旨を示します。 Audience API (CRM)

オーディエンスまたは API パートナーがハッシュ化された識別子のリストを提供し、X が照合を実行して、X 上でのメディアバイイングに利用可能なセグメントを生成します。パートナーはこれらのオーディエンスを Audience API を使って作成できます。 仕組み

Web X 上でのメディアバイイングに対してターゲティングするセグメントを特定するため、MPP オーディエンスパートナーとの連携時には標準的なクッキーマッチングプロセスを提供しています。加えて、広告主は X Web Event Tag を設定してウェブサイトのユーザーデータを収集し、対応するカスタムオーディエンスを作成できます。 セットアップ手順

仕組み

Mobile 詳細については、Custom Audiences from Mobile Apps に関するブログ記事を参照してください。 Flexible Flexible audiences により、広告主は既存のカスタムオーディエンス、または既存のカスタムオーディエンスのサブセットに基づいて、オーディエンスの組み合わせを作成および保存できます。カスタムオーディエンスのメンバーのサブセットは、インタラクションの直近度と頻度に基づいてターゲティングできます。 カスタムオーディエンスの利用制限があるユースケース 制限事項の詳細はこちら

Audiences FAQ

Q: 非常に大量のデータを送信しましたが、オーディエンスサイズが TOO_SMALL と表示されるのはなぜですか？ A: 現在、データはリアルタイムでオーディエンスに追加されていますが、オーディエンスサイズを算出する処理ジョブは一定時間経過後にのみ実行されます。数時間後には、UI 上に正しいオーディエンスサイズが表示されるはずです。 Q: オーディエンスデータの送信を完了し、24時間以上待ちましたが、まだそのオーディエンスをターゲティングできません。次に何をすればよいですか？ A: 以下の点を確認してください。

渡しているユーザー ID が正しく、形式に問題がないこと。
渡しているオーディエンス名が正しく、これまでのメンバーシップ更新時の名称と一致していること。
POST コマンドからのレスポンスを確認してください。
ID Sync pixel が正しく実装されていること、および ID Sync プロセスの説明どおり、該当サイトに十分な数のユーザーが訪問してユーザーのマッピングが行われていることを確認してください。メンバーシップ更新に含まれていてもマッピングされていないユーザーは、ターゲティング可能なユーザーには変換されません。

上記すべてに問題がなく、正常に動作している場合は、可能な限り詳細な情報を添えて X のプロダクト担当窓口にご連絡ください (望ましい情報の例として、Guide to Partner Inbounds を参照してください) 。 Q: エンドポイントは何回まで、どのような方法で呼び出せますか？ A: オーディエンスメンバーシップ全件を再送しないようにし、増分データのみを送信する形でシステムを呼び出すことを強く推奨します。本システムは、世界最大級のウェブサイトの増分データ更新を処理できるだけのスループットでテストされています。オーディエンスの初回アップロードは慎重にスロットリングを行う必要があり、完了までに相応の時間がかかることが想定されます。 Q: ターゲティングに利用できるオーディエンスの最小サイズはどれくらいですか？

ターゲティングに利用できるオーディエンスの最小サイズは 100 ユーザー (照合後) です。500 ユーザー未満しかマッチしなかったオーディエンスは、X Ads の UI 上ではターゲティングに利用できません。

Q: オーディエンスファイルの処理にはどのくらい時間がかかりますか？また、X のユーザーインターフェイスでオーディエンスファイルが利用可能になるまでにはどのくらいかかりますか？

通常、オーディエンスファイルの処理には 4〜6 時間かかりますが、処理時間はファイルサイズに依存します。ファイルの処理が完了すると、X Ads の UI 上でオーディエンスが利用可能になります。

Q: マッチ率はどのように計算されますか？

マッチ率 = 過去 90 日間のアクティブな X ユーザー数 / 提供されたユーザー数

Q: オーディエンスファイルが正しく機能しているかどうかをテストするにはどうすればよいですか？

テスト用のオーディエンスファイルを用意し、広告主ハンドルとして「keltonlynn」を使用してください。その後、そのファイルが正しく取り込まれ、X の UI に読み込まれることを X 側で検証できます。

Q: partner user identifier (p_user_id) とは何ですか？

これは、御社が各顧客を一意に識別するために使用している識別子です。

Q: standard ID とは何ですか？

これは、メールアドレス、デバイス ID、X の @handle、または ID のいずれかです。

Q: HMAC Key はどのように取得すればよいですか？

HMAC Key は暗号化されたメールで提供されます。お客様の公開 PGP キーを mpp-inquiry@x.com に送付していただければ、まずは動作確認のためのテストメールをお送りします。検証が完了したら、HMAC Key をお送りします。

Q: 付与された HMAC Key を使ってハッシュ処理が正しく行われたことは、どのように検証できますか？

X から、テスト用ファイル (サンプルのメールアドレス、デバイス ID などを含む) と、それに対応するハッシュ結果ファイルを提供します。これを用いて、お客様の処理結果を照合できます。

Q: full data match ファイルにサイズ制限はありますか？

いいえ、full data match ファイルのサイズに制限はありません。

Q: full data match ファイルの処理にはどのくらい時間がかかりますか？

ファイルが X によって受信されてから、処理が完了するまでにはおおよそ 1 日かかります。

CRM

本ドキュメントでは、Custom Audiences の CRM パートナー向けの連携仕様 (ファイル形式およびデータ交換プロセス) について説明します。概要 Company は、顧客に代わって、共通ユーザー識別子 (例: メールアドレス) のハッシュ化リスト、またはパートナーのユーザー ID のリストを X に送信し、ブラインドマッチングを実行してターゲティング用の X ユーザー ID のリストを生成します。ターゲティング用セグメントは、ads.x.com のキャンペーン設定においてファイル名で指定された、広告主固有の @handle で利用可能になります。 Company からのすべてのファイルは、X が Company に付与した専用アカウントを通じて、IronBox (www.golockbox.com) 上のセキュアなパッケージ経由で X に提供されます。X は IronBox へのアクセス権を付与します。IronBox API に関するドキュメントは https://secure.goironcloud.com/Docs/Help/ で参照できます。

パートナー ID マッチング要件

企業がユーザーを追跡するために独自の標準 ID システムを使用している場合 (つまり、メールアドレス、デバイス id、X ユーザー ID などの一般的なユーザー識別子ではない場合) 、以下のプロセスを推奨します。 1. フルデータマッチ 最初に、企業はすべてのユーザーレコードについて、X と共有する一意の共通ユーザー識別子を含む包括的なリストを 1 つのファイルで提供し、フルデータマッチを実行して、パートナー ID (p_user_id) と X ID (tw_id) のマッピングを X 側で保持します。これは適切なメンテナンスを行うため、2～3 か月ごとに定期的に実施されます。マッチングが完了すると、X はこのファイルに基づくベースラインのマッチ率をメールで企業と共有します。このファイルのフォーマットは次のとおりです: 命名規則: FullDataMatch.[CompanyName].txt ハッシュアルゴリズム: HMAC_SHA-256 フォーマット: 列 1: 共通識別子を HMAC でハッシュ化した値列 2: パートナーユーザー ID (ユーザーごとに一意、ファイル内では重複可) 列区切り文字 (CSV) : 共通ユーザー識別子のハッシュ値とパートナー ID の区切りにはカンマを使用値は行区切り

例: ユーザーレコード A のパートナーユーザー ID が 1 で、共通識別子が 1、2、3 の場合:


common user identifier 1	p_user_1
common user identifier 2	p_user_1
common user identifier 3	p_user_1

*共通ユーザー識別子については、以下の「ハッシュ化手順」セクションを参照してください 2. カスタムセグメントリスト 企業は、X 上でのターゲティング用に顧客向けカスタムオーディエンスを作成するため、p_user_id 形式のユーザーリストを提供します。

値は行区切り
p_user_id
- (上記 1. フルデータマッチのセクションで提供されたものと同一です。フルデータマッチで提供された値がハッシュ化されている場合、企業はオーディエンスファイルにも同じハッシュ化された値を提供します。提供された値がハッシュ化されていない場合、企業はハッシュ化されていない値を提供します。)

標準マッチング要件

企業が、すべての顧客ユーザー識別子のマッピングに標準 ID を使用していない場合には、次のプロセスを推奨します。 カスタムセグメントリスト 企業は、顧客に代わり、ハッシュ化された共通ユーザー識別子のリストを X に直接提供し、カスタムオーディエンスを作成します。このファイルの形式は次のとおりです。

行区切りの値
ハッシュ化された共通ユーザー識別子 (例：メールアドレス)
以下に記載のファイル命名規則に従うこと
メールアドレスについては、以下の「ハッシュ化の手順」に従うこと

カスタムセグメントリストのファイル命名規則と操作

ファイルの処理内容はファイル名によって決まり、利用可能な操作と一般的なファイル命名規則は次の形式です: audiencename_partnername.handle.operation.filetype

audiencename: カスタムオーディエンス (Custom Audience) の名前。この項目は、ads.x.com のキャンペーン設定 UI でオーディエンスを選択する際に表示される名前になります (例: brand_loyalty_card_holders) 。
partnername: 広告主に代わってデータを提供する会社名 (例: company_name) 。
handle: カスタムオーディエンスにアクセス権を持つ X アカウント (@handle) (例: @pepsi, @dietpepsi)
operation: new, add, remove, removeall, replace (詳細は下記)
: 各オーディエンスファイルのアップロードごとに一意となるようにするために使用される、標準的な Unix エポック時間 (秒単位)
filetype: ファイルは *.txt 形式である必要があります

オーディエンスの作成と更新

単一のファイルで新しいオーディエンスを作成します (例: loyalty_card_holders_partnername.pepsi.new.txt) Add - リスト内でマッチしたユーザーを既存のオーディエンスに追加します (例: loyalty_card_holders_partnername.pepsi.add..txt) Remove - リスト内でマッチしたユーザーを既存のオーディエンスから削除します (例: loyalty_card_holders_partnername.pepsi.remove..txt) Remove All - 定期的に更新される累積リストから得られたマッチしたユーザーを、その Client のすべてのオーディエンスから削除します (つまり、Client のオプトアウトリスト) 。例: partnername.pepsi.removeall.txt

これは、広告主からオプトアウトしたユーザーの包括的なリストとして使用できます。
X は、このファイルで提供された最新のリストのみを有効とし、マッチした既存および今後のすべてのオーディエンスに対して適用します。

これは、このファイルが提供され処理された時点での X ユーザーに対して適用されます。 Replace - 既存のオーディエンスを削除し、新しいオーディエンスリストで置き換えます。例: loyalty_card_holders_partnername.pepsi.replace..txt 全社オプトアウト - 会社は、会社のオプトアウトポリシーに従ってオプトアウトしたユーザーを削除するため、累積のオプトアウトファイルを提供します。 X は、この全社オプトアウトファイルで提供された最新のリストのみを有効とし、このファイルが提供され処理された時点でマッチした X ユーザーに対する既存および今後のすべてのオーディエンスに適用します。全社オプトアウトファイルの形式は次のとおりです。例: partnername.removeall.txt Delete - 現在のオーディエンス一覧から既存のオーディエンスを削除します (例: loyalty_card_holders_partnername.pepsi.delete.txt)

ハッシュ化手順

X は、一般的なユーザー識別子 (例: メールアドレス) をハッシュ化するための、base64 でエンコードされた本番用キーを PGP を用いて安全に共有します。Company は、そのキーを base64 デコードして 32 バイトのキーを生成し、ハッシュ化に使用します。 base64 エンコード済みキーの例: BrQvOg+dACBUmKjRiNxZgJLh6zydjS0ZOv80FelTNzM= base64 デコード済みキーの例: /:� TшY 正規化: Company は、ハッシュ化を行う前に、一般的なユーザー識別子に対して基本的な正規化処理を行います (Device ID については例外であり、「Device ID Normalization」セクションを参照してください) 。

E-mail 正規化

先頭と末尾のスペースを削除し、メールアドレス全体を小文字に変換します。例: 元の E-mail アドレス: testemail_Organisational_baseball+884@It92I6Ev2B.Com 正規化後: testemail_organisational_baseball+884@it92i6ev2b.com ハッシュ値: 74d9584eded0ad1e5572a1c1849f3716751d371d6117a6155dad5363f4b4fbec 注: エンコードされた HMAC 値およびキーの文字数は、入力値やエンコーディング方式によって変化する可能性があるため、固定ではありません。

デバイス ID の正規化

デバイス ID のハッシュ化についても、データパートナーに提供する共通のソルトと SHA-256 ハッシュアルゴリズムを使用するという同一の要件が適用されます。メールアドレスの場合と同様にスペースは削除しますが、IDFA/Android ID については小文字への正規化は行わず、IDFA/Android ID の元のフォーマットをそのまま使用してください。以下は、ハッシュ化前の iOS および Android のデバイス ID の生のフォーマット例です。 iOS IDFA: DD99CFF7-6186-4602-9DF2-ED3FD0B2D431 Android ID: b5bf2122961b3595 ハッシュ化された iOS IDFA: 134fb8cd95c7fd42e2793f469a447198ca5f990968db2dbadad70e723ed9750b ハッシュ化された Android ID: 130dddff1939f229476f50bc8adab8fcb7e3525b0e9604fe8effc15e68cee4a4

X ユーザー ID の正規化

X ID は、たとえそれが PII ではなくても、データのグルーピング (例：@handle のカスタマーリスト) が広告主にとって非公開であるため、引き続きハッシュ化されます。データパートナーに提供する共通のソルトと SHA-256 ハッシュアルゴリズムを用いて X ID をハッシュ化する、という同じ要件が適用されます。X ID と @username の両方からは、スペースをすべて取り除く必要がありますが、User ID については正規化は不要です。正規化のため、@username は小文字に変換してください。また、@ 記号は username の一部として含めないでください。生の ID の形式は次のとおりです:

User ID: 27674040
@username: testusername

ハッシュ化された User ID: bf6b57d4e861e83bea8bbed2b800b251a64c95468ee6e8cb07c3368c9ed45e85 ハッシュ化された @username: 12201ae78ad1afa907c7112d17f498154ffb0bf9ea523f5390e072a06d7d9812

ID Sync 連携

p_id を用いてデータを送信するパートナーは、広告主またはパートナーのユーザー ID と X ユーザー ID をマッピングするために、ID Sync プロセスを実行する必要があります。これにより、広告主は自社のユーザーセグメントを X 上で直接ターゲティングできるようになります。パートナーは、メンバーシップ更新情報を送信する際に、パラメータ user_identifier_type の値を TALIST_PARTNER_USER_ID または TAWEB_PARTNER_USER_ID のいずれかに設定する必要があります。

Web のみ: 以下のとおり、広告主のサイトにピクセルを設置することで実行できます。
リスト: CRM ページで説明しているいずれかの方法を使用して実行できます。

Pixel URL


ベース URL
https://analytics.x.com/i/adsct

ピクセルパラメーター


パラメーター	説明
`p_id`	X によって割り当てられたパートナーの ID
`p_user_id`	パートナーシステム内でのユーザーの ID

ID Sync Pixel:

パートナー id の例として 111、p_user_id の例として abc を使用した場合、構成されるピクセルは次のようになります。

    <pre class="brush: xml">
    <img height="1" width="1" src="https://analytics.x.com/i/adsct?p_id=111&p_user_id=abc" style="display:none" />
    </pre>

オプトアウトファイルの構成と送信 パートナーは、ターゲット広告配信からのオプトアウトを選択したと、パートナーの知る限りで把握しているユーザーのリストを X に提供する必要があります。オプトアウトファイルの形式は次のとおりです。


Column Number	Column Name	Column Type	Description
1	Partner ID	string	「partner id」とは、各パートナーを一意に識別するために X からパートナーに付与される ID です。
2	The user’s id in the partner system	string	`p_user_id` は、パートナーによってユーザーを識別するために使用される一意の ID です。これらのオプトアウトユーザーを含むファイルは、TON upload エンドポイントを使用してアップロードし、アップロードしたデータのパスを、こちらの Global Opt Out エンドポイント PUT accounts/:account_id/custom_audiences/global_opt_out に送信する必要があります。

メンバーシップ更新の送信 エンドポイントのドキュメントで指定されているとおり、POST custom_audience_memberships エンドポイント経由でユーザーを送信する際には、Cookie ベースのマッチングを有効にするために customer ID を渡す必要があります。p_id を含むデータを送信するパートナーは、user_identifier_type を TALIST_PARTNER_USER_ID または TAWEB_PARTNER_USER_ID に必ず設定する必要があります。その他の手順は、Real-Time Audience API Integration Guide に記載されている内容と同じです。

カスタムオーディエンスのユーザーデータ

このドキュメントでは、[Custom Audience]/x-ads-api/audiences のユーザーデータの形式について説明します。 データの正規化 デバイス ID:

IDFA - 小文字かつダッシュ区切りにする。例: 4b61639e-47cc-4056-a16a-c8217e029462
AdID - 端末上の元の形式が必須であり、大文字化せずダッシュ付きの形式にする。例: 2f5f5391-3e45-4d02-b645-4575a08f86e
Android id - 端末上の元の形式が必須であり、大文字化せず、ダッシュやスペースを含めない。例: af3802a465767e36

メールアドレス:

小文字にし、前後のスペースを削除する。例: support@x.com

X ユーザー名:

先頭に @ を付けず、小文字にし、前後のスペースを削除する。例: jack

X ユーザー ID:

標準的な整数。例: 143567

データのハッシュ化 各行のデータは、ソルトを使わずに SHA256 でハッシュ化する必要があります。さらに、最終的な出力ハッシュは小文字でなければなりません。例: 49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d とし、49E0BE2AECCFB51A8DEE4C945C8A70A9AC500CF6F5CB08112575F74DB9B1470D ではないこと。

# hasing user @AdsAPI using python
import hashlib
hashlib.sha256("adsapi".encode()).hexdigest()

#output
49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d

追加のハッシュ化用コードサンプルは github.com/xdevplatform/ads-platform-tools にあります。

カスタムオーディエンス: Web

情報パートナーは、広告主に代わってターゲティングするための ID (p_user_ids) のリストを送信します。これは、p_user_ids と X ユーザー ID の間にマッピングを構築する ID Sync プロセスによって実行されます。このマッピングは、その後ターゲティングに使用できる X ユーザー ID のリストを生成するために使用されます。これらのカスタムオーディエンスは、ads.x.com の Custom Audiences Web キャンペーン設定におけるラベルで指定される、広告主固有の @handle 上で利用可能になります。 X は、パートナーのタグおよびサイトに埋め込むことで、ID (p_user_ids) を X ユーザー ID にマッチさせるために使用できるセキュアピクセルを提供します。ID Sync プロセスが完了すると、パートナーによってターゲティングファイルが作成され、HTTPS エンドポイントを通じて X が取得できるようにされます。これらのターゲティングファイルは、X によって定期的に取り込まれ、その後 X の UI で利用可能になります。 X セキュアピクセル X セキュアピクセルは次のとおりです。 https://analytics.x.com/i/adsct?p_user_id=xyz&p_id=123 p_user_id - xyz は、パートナーによって提供されるパートナーユーザー ID を表します p_id - 123 は、パートナーに対して一意の ID (X によって提供) を表します パートナー HTTPS エンドポイント & ターゲティングユーザーファイル パートナーは、ターゲティングファイルを定期的に取り込むために使用できる HTTPS エンドポイントと認証情報 (ユーザー名/パスワード) を X に提供する必要があります。HTTPS エンドポイントの例は次のようになります:

https://<partnerdomain>/twitter/partner_targeting_%Y-%M-%D.tsv.gz

%Y - 年を表すフォーマットコード (YYYY) %M - 月を表すフォーマットコード (MM) %D - 日を表すフォーマットコード (DD) 送信されるデータは次のファイルで構成されます。

Partner Targeting User File
Targeting Conversion File

すべてのファイルは TSV 形式であり、各行の個々のフィールドはタブ文字で区切られます。正当なフィールド値の中にタブ文字が含まれることは決してありません。 許可対象の X IP 範囲: Partner Endpoint へのアクセスを許可できる IP 範囲は次のとおりです。

199.16.156.0/22
199.59.148.0/22

Partner Targeting User File:

Column Number	Column Name	Column Type	Description
1	partner id	string	「partner id」は、各 Partner を一意に識別するために X が Partner に付与する ID です。
2	advertiser id	string	「advertiser id」は、広告主の @handle です。
3	p_user_id	string	「p_user_id」は、Partner がユーザーを識別するために使用する一意の ID です。
3	confidence score	integer	「confidence score」は任意項目です。confidence score としては 0〜100 の使用を推奨します。利用ケースがリターゲティングの場合、confidence score が「100」は直接リターゲティングされたユーザーを意味します。0〜99 のスコアは、類似オーディエンスに対する信頼度レベルに対応します。
4	segment label	string	「segment label」は任意項目です。Partner は「segment label」を使用して、たとえば商品カテゴリなどを指定できます。この「segment label」は ads.x.com の UI における Custom Audiences の人間が判読可能な名前となるため、その使用を推奨します。

Notes: 新しい Partner Targeting File を受信するたびに、特に別途合意がない限り、それは Partner がターゲティングを推奨するユーザーの完全なリストであり、増分データではないものと想定します。Partner Targeting File の配信頻度については、各 Partner と合意します。期待されるタイミングで Partner Targeting File を受信できなかった場合は、あらかじめ定義した有効期限内であれば、前回のバージョンを使用します。

Audience API との連携

概要

Audience API は Ads API の v4 の一部として提供されており、これにより従来の Audiences エンドポイントがいくつかの点で改善されています。この新しいエンドポイントは新しい Audience 処理バックエンドによって支えられており、安定性、堅牢性、信頼性の面で複数の改善が行われています。本ガイドの目的は、Audience API と従来の Audience アップロードおよび管理プロセスとの違いを明らかにすることです。リファレンスドキュメントは Audience API のリファレンスドキュメントページにあります。注記: すべての Audience ユーザーデータは、アップロード前に SHA-256 でハッシュ化されている必要があります。詳細および受け入れ可能なユーザー識別子の種類 (type) とデータ正規化については、user data ページを参照してください。 Audience 機能の変更点 v4 時点で、カスタムオーディエンスに対して以下の変更が導入されており、非推奨となっているエンドポイントは Ads API v3 のサンセット後は利用できなくなります。

非推奨 TON Upload:
- GET accounts/:account_id/custom_audience_changes
- GET accounts/:account_id/custom_audience_changes/:custom_audience_change_id
- POST accounts/:account_id/custom_audience_changes
- PUT accounts/:account_id/custom_audiences/global_opt_out
非推奨 Real Time Audiences:
- POST custom_audience_memberships
カスタムオーディエンス:
- すべての Custom Audience エンドポイントのリクエストおよびレスポンスから list_type パラメータが削除されます。このパラメータは以前、Audience のユーザー識別子の種類 (例: email、X User ID など) を特定するために使用されていましたが、現在の Audience では同一の Audience に対して複数のユーザー識別子を受け付けることができるようになったため、この値は不要になりました。
全般:
- Audience のルックバック期間は、直近 30 日間から、直近 90 日間にアクティブなユーザーに対して照合するように更新されました
- ターゲティング可能なオーディエンスとするために必要なマッチ済みユーザー数の最小値は、500 ユーザーから 100 ユーザーに引き下げられました

前提条件

Ads API へのアクセス
Audience エンドポイントへのアクセスには、allowlist への追加が必要です。このフォームに入力し、2018-08-01 より前に初回の同意を行っている場合は、新しい X Ads Products and Services Agreement に改めて同意してください

Audience アップロードプロセス 以下の表は、旧来の Audience 作成フローと新しい Audience 作成フローとの主な違いを示したもので、詳細はこの後のセクションで説明します。

Step in Process	Audience API	(Deprecated) TON Upload
Create a shell Audience	[POST custom_audience endpoint]/x-ads-api/audiences を使用して作成できます	[POST custom_audience endpoint]/x-ads-api/audiences を使用して作成できます
Add a new user	Audience endpoint で `operation_type` に `Update` を指定して使用します	POST custom_audience_changes エンドポイントで `operation` に `ADD` を指定して使用します
Remove a user	Audience endpoint で `operation_type` に `Delete` を指定して使用します	POST custom_audience_changes エンドポイントで `operation` に `REMOVE` を指定して使用します
Opting-Out Users	Audience endpoint で `operation_type` に `Delete` を指定し、ユーザーが含まれる `custom_audience_id` を指定して使用します	Global opt-out endpoint を使用します

注記 TON Upload 経路で更新またはオプトアウトされるすべての Audience には、TON Upload エンドポイント経由でアップロードされた対応するリストが存在し、custom_audience_changes エンドポイントを使用して Audience に関連付けられている必要があります。 レート制限 Audience API エンドポイントには、アカウントごとに 1 分あたり 1,500 回のレート制限があります。単一のペイロードで送信できるユーザー数に制限はありません。ペイロードに対する制約は次のとおりです。

操作の合計数: 2,500 operations
最大ペイロードサイズ: 5,000,000 bytes

Audience ユーザー管理 新しい Audience を作成するには、次の手順を実行します。

新しいカスタムオーディエンスを作成する

[x-ads-api/audiences エンドポイントの POST custom_audience] を使用して、新しいカスタムオーディエンスの「シェル」を作成し、対応するカスタムオーディエンスの id を取得します。これは、オーディエンスを一から作成する場合に必要な手順です。既存のオーディエンスを更新する場合は、次のセクションに進んでください。

オーディエンスにユーザーを追加する

Custom Audience の id を使用して、POST accounts/:account_id/custom_audiences/:custom_audience_id/users エンドポイントに、次のようなサンプルペイロードでリクエストを送信します。 POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # すべての値はハッシュ化する必要があります。ハッシュ化されていない値は説明目的でこの例に使用されています
    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "handle": [
                "x",
                "adsapi"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

ユーザーを Audience に追加するには、operation_type として Update を使用します。新しい Audience インターフェースでは、1人のユーザーに対して複数のユーザーキーを渡すことができます。JSON オブジェクト配列内の各オブジェクトが、それぞれ1人のユーザーに対応します。上記のペイロード例を使用した場合、このリクエストでは2人のユーザーが Audience に追加され、1人は email と handle を持ち、もう1人は email と twitter_id を持ちます。

オーディエンスからユーザーを削除する

ユーザーを追加する場合と同様の手順で、以下のようにユーザーをオーディエンスから削除できます。 POST https://ads-api.x.com/11/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    # すべての値はハッシュ化する必要があります。ハッシュ化されていない値は説明目的でこの例に使用されています
    [
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "abc@x.com"
              ],
              "twitter_id": [
                "783214",
                "1225933934"
              ]
            },
            {
              "email": [
                "edf@x.com"
              ],
              "twitter_id": [
                "121291606",
                "17874544"
              ]
            }
          ]
        }
      }
    ]

operation_type は Delete に設定する必要があり、ユーザーはそのオーディエンスに追加されたときに使用された任意のキーで照合されます。たとえば、あるユーザーが email と twitter_id を用いてオーディエンスに追加された場合、その同じユーザーはこれらのキーのいずれか、つまり email または twitter_id、あるいは両方を使って削除できます。さらに、同一のリクエスト内で Audience にユーザーを追加および削除することも可能です。このエンドポイントは、1つのリクエストで複数の operation_type をサポートします。

オプトアウトしたユーザー

グローバルなオプトアウトエンドポイントが非推奨となったことに伴い、パートナーは、いずれかの Audience からオプトアウトしたユーザーを Delete する必要があります。これを実現する方法はいくつかあります。

各ユーザーがどの Audience に属しているかを管理し、それぞれの Audience から個別にユーザーを削除する。
Ads アカウントに関連付けられている すべての Audience からユーザーを削除する。

一般的なベストプラクティス

このエンドポイントは、処理に時間がかかるスパイク的なキューを避け、全体として当社システムへの不要な負荷を軽減するために、可能な限りリアルタイムに近いバッチで呼び出すことを強く推奨します。これにより、ユーザーがキャンペーンターゲティングに利用可能になるタイミングも早くなります。
正常に完了した API 呼び出しは、リクエストで受信した user オブジェクトの数に対応する success_count と total_count を返します。
このエンドポイントはアトミックな性質を持ちます。つまり、リクエスト全体が成功するか、何らかの errors が発生した場合にはリクエスト全体が失敗します。エラー応答が返された場合は、API 利用者はエラーを修正し、ペイロード全体を含めてリクエストを再試行することを推奨します。
失敗した場合、パートナーはリトライに指数バックオフアプローチを使用することが推奨されます。たとえば、1 回目の失敗時にはすぐに再試行し、2 回目の失敗後は 1 分後に再試行し、3 回連続で失敗した場合は 5 分後に再試行する、といった形です。

APIリファレンス

キーワードインサイト

GET insights/keywords/search

キーワードのグループを指定すると、そのキーワードに紐づくツイート数と、関連する 30 個のキーワードのセットを取得します。ツイート数は入力したキーワードのみに対応し、関連キーワードは含みません。指定できる時間範囲 (end_time - start_time) は最大 7 日間です。結果は 1 つの geo (国) ごとにスコープされる点に注意してください。 Resource URL https://ads-api.x.com/12/insights/keywords/search Parameters

Name	Description
granularity required	`start_time` と `end_time` で指定された時間範囲に対して返されるデータの粒度を指定します。たとえば `HOUR` に設定した場合、`start_time` と `end_time` の間の各時間ごとに 1 つのデータポイントが返されます。 Type: enum Possible values: `DAY`, `HOUR`
keywords required	検索を絞り込むためのコンマ区切りのキーワード文字列です。すべてのキーワードは互いに OR 条件で結合されます。 Note: 使用できるキーワード (`keywords` と `negative_keywords` の合計) は最大 10 個です。 Type: string Example: `developers`
start_time required	取得されるデータを、`start_time` と `end_time` の間の時間範囲で収集されたデータにスコープします。ISO 8601 形式で指定します。 Type: string Example: `2017-07-10T00:00:00Z`
end_time optional	取得されるデータを、`start_time` と `end_time` の間の時間範囲で収集されたデータにスコープします。ISO 8601 形式で指定します。 Note: 省略した場合は現在時刻が既定値として使用されます。 Type: string Example: `2017-07-11T00:00:00Z`
location optional	アカウントのユーザーがどこに所在するかという観点で結果を絞り込むために、GET targeting_criteria/locations エンドポイントから取得できるターゲティング値を指定します。現時点では国レベルのロケーションのみがサポートされています。 Type: string Example: `0ce8b9a7b2742f7e`
negative_keywords optional	除外するキーワードのコンマ区切り文字列です。すべての除外キーワードは互いに OR 条件で結合されます。 Note: 使用できるキーワード (`keywords` と `negative_keywords` の合計) は最大 10 個です。 Type: string Example: `rain`

Example Request

GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01

レスポンス例*

    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }

テイラードオーディエンス権限

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

指定されたテイラードオーディエンスに関連付けられている一部またはすべての権限の詳細を取得します。 Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
tailored_audience_id required	リクエスト内で操作対象となるテイラードオーディエンスへの参照です。 Type: string Example: `1nmth`
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細については Pagination を参照してください。 Type: string Example: `8x7v00oow`
granted_account_ids optional	カンマ区切りの識別子リストを指定して、レスポンスを目的のアカウントのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: `18ce54aymz3`
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細については Sorting を参照してください。 Type: string Example: `created_at-asc`
tailored_audience_permission_ids optional	カンマ区切りの識別子リストを指定して、レスポンスを目的のテイラードオーディエンス権限のみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: `ri`
with_total_count optional	`total_count` レスポンス属性を含めます。 Note: このパラメーターと `cursor` は排他的です。 Note: `total_count` を含むリクエストは、レート制限がより低くなり、現在は 15 分あたり 200 件に設定されています。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "tailored_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

指定されたオーディエンスを、指定したアカウントと共有できるようにする新しい権限オブジェクトを作成します。 Note: テイラードオーディエンスの権限を作成または変更するには、そのオーディエンスが、権限を変更しようとしているアカウントに所有されている必要があります。特定のオーディエンスのレスポンスに含まれる is_owner レスポンス属性を確認することで、テイラードオーディエンスの所有者を判別できます。 Note: オーディエンスを共有できるのは、同一ビジネス内の広告アカウント間、またはオーディエンスを所有している広告アカウントが SHARE_AUDIENCE_OUTSIDE_BUSINESS アカウント機能を有している場合のみです。 Resource URL https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則として必須パラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
granted_account_id required	テイラードオーディエンスに対する権限を付与したい相手のアカウントです。 Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id` がテイラードオーディエンスに対して持つアクセスレベルです。 Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
tailored_audience_id required	このリクエストで操作対象となるテイラードオーディエンスを参照するための識別子です。 Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "tailored_audience_id": "2906h"
        }
      },
      "data": {
        "tailored_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

指定された Tailored Audience の共有権限を取り消します。注記: Tailored Audience の権限を作成または変更するには、そのオーディエンスが権限を変更しようとしているアカウントに所有されている必要があります。特定のオーディエンスに対するレスポンス内の is_owner レスポンス属性を確認することで、Tailored Audience の所有権を確認できます。権限が取り消されると、付与されたアカウント (granted_account_id) が今後のキャンペーンでそのオーディエンスをターゲットにできないことを当社として保証します。既存のキャンペーンは共有されたオーディエンスを使って引き続き配信されます。キャンペーンは停止されず、オーディエンスもキャンペーンから削除されません。オーディエンス共有権限が取り消された後に、このキャンペーンをコピーすることはできません。 Resource URL

https://ads-api.x.com/5/accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

Parameters

Name	Description
account_id required	対象アカウントの識別子。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストにおいて、一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに紐づいている必要があります。 Type: string Example: `18ce54d4x5t`
tailored_audience_id required	リクエスト内で操作対象となる Tailored Audience への参照。 Type: string Example: `1nmth`
tailored_audience_permission_id required	リクエスト内で操作対象となる Tailored Audience の権限への参照。 Type: string Example: `ri`

Example Request DELETE https://ads-api.x.com/5/accounts/18ce54d4x5t/tailored_audiences/1nmth/permissions/ri Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "tailored_audience_permission_id": "ri",
          "tailored_audience_id": "1nmth"
        }
      },
      "data": {
        "tailored_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

ターゲットオーディエンス

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

指定した custom_audience_id をターゲットにしているアクティブまたはすべてのラインアイテムおよびキャンペーンのリストを取得します。

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くほとんどの Advertiser API リクエストで必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるカスタムオーディエンスへの参照です。 Type: string Example: `2906h`
with_active optional	`false` の場合、`servable=false` 状態のラインアイテムも含めます。 Type: boolean Default: `true` Possible values: `true`, `false`
cursor optional	次の結果ページを取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: `8x7v00oow`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/targeted Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "2906h",
        }
      },
      "next_cursor": null,
      "data": [
        {
          "campaign_id": "59hod",
          "campaign_name": "test-campaign",
          "line_items": [
            {
              "id": "5gzog",
              "name": "test-line-item",
              "servable": true
            }
          ]
        },
        {
          "campaign_id": "arja7",
          "campaign_name": "Untitled campaign",
          "line_items": [
            {
              "id": "bjw1q",
              "name": null,
              "servable": true
            }
          ]
        }
      ]
    }

カスタムオーディエンスのユーザー

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

このエンドポイントを使用すると、パートナーは指定された custom_audience_id からユーザーを追加・更新・削除できます。このエンドポイントは、1ユーザーにつき複数種類のユーザー識別子も受け付けます。リクエストの users フィールドで提供されるデータは、partner_user_id を除きすべて SHA256 を用いてハッシュ化し、正規化する必要があります。 バッチリクエスト

現在の最大バッチサイズはこのエンドポイントに対して 2500 です。バッチサイズは、リクエストごとの操作数 (Update/Delete) によって決まります。たとえば、1つの配列内に 2500 を超える操作オブジェクト ({"operation_type": "Update/Delete", [..] }) が含まれている場合はエラーになります。
このエンドポイントが受け付けるリクエスト POST ボディサイズの最大値は 5,000,000 バイトです。
このエンドポイントのレート制限は、1 分間ウィンドウあたり 1500 回です。
すべてのパラメータはリクエストボディで送信され、Content-Type として application/json が必要です。
バッチリクエストはグループとしてまとめて失敗または成功し、エラーと成功の両方の API レスポンスで、最初のリクエストのアイテム順序が保持されます。

バッチレスポンス Ads API によって返されるレスポンスには、success_count と total_count の 2 つのフィールドが含まれます。これらの値は常に同じでなければならず、バックエンドによって処理されたリクエスト内のレコード数を表します。リクエストボディで送信されたレコード数が success_count および total_count と一致しない状況はエラー状態として扱う必要があり、再試行が必要となります。 バッチエラー

リクエストレベルのエラー (例: 最大バッチサイズ超過) は、レスポンスの errors オブジェクト内に表示されます。
アイテムレベルのエラー (例: 必須パラメータの欠如) は、レスポンスの operation_errors オブジェクト内に表示されます。
operation_errors 内のエラーのインデックスは、入力アイテム内のインデックスを指し、そのアイテムに対応するエラーメッセージが含まれます。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/users

パラメーター

Name	Description
operation_type required	`users` グループごとに実行される操作の種類。 Type: enum Possible values: `Update`, `Delete`
params required	`users` 配列、および `effective_at` と `expires_at` タイムスタンプを含む JSON オブジェクト。 Type: JSON
users required	個々のユーザーのすべてのパラメーターを含む JSON オブジェクトの配列。 Type: JSON
effective_at optional	カスタムオーディエンスの関連付けが有効になる UTC 時刻。ISO 8601 で表現します。デフォルトは現在の日時です。 Type: string Example: `2017-07-05T07:00:00Z`
expires_at optional	カスタムオーディエンスの関連付けが失効する UTC 時刻。指定する時刻は `effective_at` の値より後である必要があります。ISO 8601 で表現します。デフォルトはリクエストのタイムスタンプから 13 か月後です。 Type: string Example: `2017-07-05T07:00:00Z`

users オブジェクトに対するマルチキーアプローチに基づき、このオブジェクトの各要素は以下のとおり定義されます。

Name	Description
email optional	ユーザーのメールアドレス。 Type: Array[String]
device_id optional	IDFA/AdID/Android ID。 Type: Array[String]
handle optional	ユーザーの @handle。 Type: Array[String]
twitter_id optional	ユーザーの X の ID。 Type: Array[String]
phone_number optional	ユーザーの電話番号。 Type: Array[String]
partner_user_id optional	パートナーのシステムにおけるユーザーの ID。 Type: Array[String]

リクエスト例

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/users

    [
      {
        "operation_type": "Update",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "7352f353c460e74c7ae226952d04f8aa307b12329c5512ec8cb6f1a0f8f9b2cb",
                "49e0be2aeccfb51a8dee4c945c8a70a9ac500cf6f5cb08112575f74db9b1470d"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "34d56c7159a7eea941f359653029410f813f65a1d2d13ecc5ccbdd5a8cb755cf",
                "00e7b76c9739dec57f4c4a20ec021a20ffcf26bd00f519b17ea00f0ed6048f85"
              ]
            }
          ]
        }
      },
      {
        "operation_type": "Delete",
        "params": {
          "effective_at": "2018-05-15T00:00:00Z",
          "expires_at": "2019-01-01T07:00:00Z",
          "users": [
            {
              "device_id": [
                "8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92"
              ],
              "email": [
                "4798b8bbdcf6f2a52e527f46a3d7a7c9aefb541afda03af79c74809ecc6376f3"
              ],
              "handle": [
                "461222f5dd690a20651c3d19848015cb0369db3f8e937571ffb775de70750847"
              ],
              "twitter_id": [
                "c623c7e163984493b46c547088542e95d0aaa529bc52bbecce3ff91eb6b7843b"
              ]
            },
            {
              "email": [
                "5bf13d5ad4200407c5bc8b9bb578e425d05ef936fd488e3799a9d0806669223c"
              ],
              "twitter_id": [
                "858cdc7f313f84a3f3c48e9a6323307c1ef1bb7439b8e3623e140454b0fd8fa5",
                "bb074e154657b91d99bd1bb3757409149670e8ae7a0fe9136fae29a26a7881c8"
              ]
            }
          ]
        }
      }
    ]

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "success_count": 4,
        "total_count": 4
      }
    }

カスタムオーディエンスの権限

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

指定されたカスタムオーディエンスに関連付けられている一部またはすべての権限の詳細を取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作の対象とするカスタムオーディエンスを指定します。 Type: string Example: `1nmth`
count optional	各リクエストで取得を試みるレコード数を指定します。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: `8x7v00oow`
granted_account_ids optional	コンマ区切りの識別子リストを指定することで、レスポンスを目的のアカウントのみに限定します。最大 200 個の ID を指定できます。 Type: string Example: `18ce54aymz3`
sort_by optional	サポートされている属性で、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: `created_at-asc`
custom_audience_permission_ids optional	コンマ区切りの識別子リストを指定することで、レスポンスを目的のカスタムオーディエンス権限のみに限定します。最大 200 個の ID を指定できます。 Type: string Example: `ri`
with_total_count optional	`total_count` レスポンス属性を含めます。 Note: このパラメータと `cursor` は排他的です。 Note: `total_count` を含むリクエストには、現在 15 分あたり 200 件に設定されている、より低いレート制限が適用されます。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_id": "1nmth"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "custom_audience_id": "1nmth",
          "permission_level": "READ_ONLY",
          "id": "ri",
          "created_at": "2017-06-08T23:17:59Z",
          "granted_account_id": "18ce54aymz3",
          "updated_at": "2017-06-08T23:17:59Z",
          "deleted": false
        }
      ]
    }

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

指定したオーディエンスを、特定のアカウントと共有できるようにする新しい permission オブジェクトを作成します。 Note: カスタムオーディエンスの permission を作成または変更するには、そのオーディエンスが、permission を変更しようとしているアカウントに所有されている必要があります。特定のオーディエンスのレスポンス内に含まれる is_owner レスポンス属性を確認することで、カスタムオーディエンスの所有権をチェックできます。 Note: オーディエンスは、同一ビジネス配下の広告アカウント間、またはオーディエンスを所有している広告アカウントに SHARE_AUDIENCE_OUTSIDE_BUSINESS アカウント機能が付与されている場合にのみ共有できます。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
granted_account_id required	カスタムオーディエンスに対する permission を付与したいアカウントです。 Type: string Example: `18ce54aymz3`
permission_level required	`granted_account_id` がカスタムオーディエンスに対して持つべきアクセス権の種類です。 Type: enum Possible values: `READ_ONLY`, `READ_WRITE`
custom_audience_id required	リクエスト内で操作対象となるカスタムオーディエンスへの参照です。 Type: string Example: `2906h`

Example Request

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h/permissions?granted_account_id=18ce54aymz3&permission_level=READ_ONLY

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "granted_account_id": "18ce54aymz3",
          "permission_level": "READ_ONLY",
          "custom_audience_id": "2906h"
        }
      },
      "data": {
        "custom_audience_id": "2906h",
        "permission_level": "READ_ONLY",
        "id": "14m",
        "created_at": "2017-09-12T23:49:34Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-09-12T23:49:34Z",
        "deleted": false
      }
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

指定されたカスタムオーディエンスの共有権限を取り消します。 Note: カスタムオーディエンスの権限を作成または変更するには、そのオーディエンスが権限の変更を行おうとしているアカウントによって所有されている必要があります。特定のオーディエンスのレスポンスに含まれる is_owner レスポンス属性を確認することで、そのカスタムオーディエンスの所有権を確認できます。権限が取り消されると、付与されていたアカウント (granted_account_id) は今後のキャンペーンでそのオーディエンスをターゲットにできなくなることが保証されます。既存のキャンペーンは共有オーディエンスを利用して引き続き配信されます。キャンペーンは停止されず、オーディエンスもキャンペーンから削除されません。オーディエンス共有権限が取り消された後は、そのキャンペーンをコピーすることはできません。 Resource URL

https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパスの一部として現れ、GET accounts を除くすべての Advertiser API リクエストで、一般的に必須パラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるカスタムオーディエンスを参照します。 Type: string Example: `1nmth`
custom_audience_permission_id required	リクエストで操作対象となるカスタムオーディエンス権限を参照します。 Type: string Example: `ri`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/1nmth/permissions/ri Example Response

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "custom_audience_permission_id": "ri",
          "custom_audience_id": "1nmth"
        }
      },
      "data": {
        "custom_audience_id": "1nmth",
        "permission_level": "READ_ONLY",
        "id": "ri",
        "created_at": "2017-06-08T23:17:59Z",
        "granted_account_id": "18ce54aymz3",
        "updated_at": "2017-08-30T18:29:35Z",
        "deleted": true
      }
    }

カスタムオーディエンス

GET accounts/:account_id/custom_audiences

現在のアカウントに関連付けられている一部またはすべてのカスタムオーディエンスの詳細を取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
count optional	1 回のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: `200` Min, Max: `1`, `1000`
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: `8x7v00oow`
permission_scope optional	自分が所有するリスト、または自分と共有されているリストのいずれかのみが返されるようにレスポンスをフィルタリングできます。デフォルトでは、このパラメータを指定しない場合、自分が所有しているオーディエンスのみが返されます。 Type: enum Default: `OWNER` Possible values: `OWNER`, `SHARED`
q optional	`name` によってリソースの範囲を絞り込むための任意のクエリです。 Note: 大文字と小文字を区別しない前方一致で検索を行います。 Type: string Min, Max length: `1`, `255`
sort_by optional	サポートされている属性で昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: `created_at-asc`
custom_audience_ids optional	カンマ区切りの識別子リストを指定することで、レスポンスを目的のカスタムオーディエンスのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: `1nmth`
with_deleted optional	削除済みの結果をリクエストに含めます。 Type: boolean Default: `false` Possible values: `true`, `false`
with_total_count optional	`total_count` レスポンス属性を含めます。 Note: このパラメータと `cursor` は同時には指定できません。 Note: `total_count` を含むリクエストはレート制限がより厳しくなり、現在は 15 分あたり 200 回に設定されています。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?custom_audience_ids=1nmth Example Response

    {
      "request": {
        "params": {
          "custom_audience_ids": [
            "1nmth"
          ],
          "account_id": "18ce54d4x5t"
        }
      },
      "next_cursor": null,
      "data": [
        {
          "targetable": true,
          "name": "twurl-using-subshell-for-file",
          "targetable_types": [
            "CRM",
            "EXCLUDED_CRM"
          ],
          "audience_type": "CRM",
          "description": null,
          "permission_level": "READ_WRITE",
          "owner_account_id": "18ce54d4x5t",
          "id": "1nmth",
          "reasons_not_targetable": [],
          "created_at": "2017-01-08T08:19:58Z",
          "updated_at": "2017-01-08T16:21:13Z",
          "partner_source": "OTHER",
          "deleted": false,
          "audience_size": 1470
        }
      ]
    }

GET accounts/:account_id/custom_audiences/:custom_audience_id

現在のアカウントに関連付けられている特定のカスタムオーディエンスを取得します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	利用対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くほとんどの Advertiser API リクエストで必須パラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となるカスタムオーディエンスを指す参照値です。 Type: string Example: `2906h`
with_deleted optional	削除済みの結果もレスポンスに含めるかどうかを指定します。 Type: boolean Default: `false` Possible values: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      },
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": 140321
      }
    }

POST accounts/:account_id/custom_audiences

現在のアカウントに関連付けられた、新しいプレースホルダーのカスタムオーディエンスを作成します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	対象アカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで、通常必須となるパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
name required	このオーディエンスの表示名です。一意の name の値を使用する必要があります。これを満たさない場合はエラーになります。 Type: string Example: `ads api users`
description optional	このオーディエンスの説明です。 Type: string Example: `Collection of all users of the Ads API`

Example Request POST https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences?name=developers Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers"
        }
      }
    }

PUT accounts/:account_id/custom_audiences/:custom_audience_id

現在のアカウントに関連付けられている特定の Custom Audience を更新します。 リソース URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id パラメータ

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須となるパラメータです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作対象となる Custom Audience への参照です。 Type: string Example: `2906h`
name optional	このオーディエンスの表示名です。一意の name 値を使用する必要があります。そうしない場合はエラーになります。 Type: string Example: `ads api users`
description optional	このオーディエンスの説明です。 Type: string Example: `Collection of all users of the Ads API`

リクエスト例 PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h?name=developers_changed レスポンス例

    {
      "data": {
        "targetable": false,
        "name": "developers_changed",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "is_owner": true,
        "id": "2906h",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-22T23:34:26Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "name": "developers_changed"
        }
      }
    }

POST batch/accounts/:account_id/custom_audiences

Custom Audiences を一括作成できます。オーディエンスに関する情報は、Custom Audiences Overview ページを参照してください。注: このバッチエンドポイントは現在 クローズドベータ版 で、一部の広告主のみが利用できます。このベータ期間中は、モバイルカスタムオーディエンスに基づく Flexible Audiences のみ作成できます。 バッチリクエスト

現在の最大バッチサイズは 10 です。
すべてのパラメータはリクエストボディで送信され、Content-Type として application/json を指定する必要があります。
バッチリクエストはグループとしてまとめて失敗または成功し、エラーおよび成功のいずれの API レスポンスでも、初回リクエストのアイテム順序が保持されます。

バッチレスポンス バッチ API のレスポンスは順序付きのアイテムコレクションを返します。それ以外の点では、対応する単一アイテムエンドポイントと構造は同一です。 バッチエラー

リクエストレベルのエラー (例: 最大バッチサイズ超過) は、レスポンス内の errors オブジェクトに表示されます。
アイテムレベルのエラー (例: 必須パラメータの欠落) は、レスポンス内の operation_errors オブジェクトに表示されます。

Flexible Audiences

Flexible Audiences は一度作成すると変更できません。
Custom Audiences は、Flexible Audiences を作成するために、ブールロジックを組み合わせたツリー構造として渡されます。
Flexible Audience を作成する際に使用できる Custom Audiences のリーフノードは最大 10 個です。

Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/custom_audiences Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
audience_type required	作成するオーディエンスの種類です。 Type: enum Possible values: `FLEXIBLE`, `MOBILE_AUDIENCE`
child_segments required	ターゲットにしたいカスタムオーディエンスのメンバーの部分集合を定義するオブジェクトを格納する配列です。各オブジェクトには、`custom_audience_id`、`frequency`、`frequency_comparator`、`lookback_window`、`negate` に加え、場合によっては追加の `child_segments` を含める必要があります。 Type: array
name required	オーディエンスの表示名です。一意の name 値を使用する必要があります。そうしないとエラーになります。 Type: string Example: `my_flexible_audience_name`
operation_type required	各項目に対して実行される操作の種類です。 Type: enum Possible values: `Create`, `Update`, `Delete`
boolean_operator sometimes required	親 (包含している) オブジェクト内の子セグメント間の論理関係です。親オブジェクトの child_segments が空でない場合に必須です。 Type: enum Possible values: `AND`, `OR`
lookback_window sometimes required	ユーザーが特定のアクションを実行し、指定されたカスタムオーディエンスの条件を満たした期間 (日数の範囲) を指定する整数値です。 Type: int Possible values: `1`, `7`, `14`, `30`
segments sometimes required	ターゲットにしたいカスタムオーディエンスのメンバーの部分集合を定義する、`boolean_operator` と `child_segments` を含むオブジェクトです。 Type: object
custom_audience_id sometimes required	子セグメントとして使用するカスタムオーディエンスの id です。 Type: string Example: `tyfo`
frequency optional	ユーザーが特定のアクションを実行し、指定されたカスタムオーディエンスの条件を満たした頻度を、ルックバックウィンドウ内で指定する整数値です。 Type: int Default value: `1`
frequency_comparator optional	リクエストで渡される `frequency` に対する比較演算子です。 Note: 以下の値において、`GTE` は「以上」、`LT` は「未満」などを表します。 Type: string Possible values: `NUM_GTE`, `NUM_GT`, `NUM_EQ`, `NUM_LTE`, `NUM_LT` Default value: `NUM_GTE`
negate optional	セグメントを否定し、そのセグメントを組み合わせから除外します。 Type: boolean Default value: `true` Possible values: `true`, `false`

リクエスト例 POST https://ads-api.x.com/12/batch/accounts/18ce54d4x5t/custom_audiences

    [
      {
        "operation_type":"Create",
        "params":{
          "name":"my_flexible_audience_name",
          "audience_type":"FLEXIBLE",
          "segments":{
            "boolean_operator":"AND",
            "child_segments":[
              {
                "custom_audience_id":"TYIF",
                "frequency":1,
                "frequency_comparator":"NUM_GT",
                "lookback_window":30,
                "negate":true,
                "child_segments":[

                ]
              },
              {
                "boolean_operator":"OR",
                "child_segments":[
                  {
                    "custom_audience_id":"TXR1",
                    "lookback_window":30,
                    "child_segments":[

                    ]
                  },
                  {
                    "custom_audience_id":"TYFO",
                    "frequency":1,
                    "frequency_comparator":"NUM_GT",
                    "lookback_window":30,
                    "negate":true,
                    "child_segments":[

                    ]
                  }
                ]
              }
            ]
          }
        }
      }
    ]

レスポンス例

    {
      "data": {
        "targetable": false,
        "name": "my_flexible_audience_name",
        "targetable_types": [
          "FLEXIBLE",
          "EXCLUDED_FLEXIBLE"
        ],
        "audience_type": "FLEXIBLE",
        "id": "13ld7",
        "reasons_not_targetable": [
          "PROCESSING",
          "TOO_SMALL"
        ],
        "metadata": [
          {
            "custom_audience_id": "13ld7",
            "account_id": "qsx3w2",
            "name": "my_flexible_audience_name",
            "audience_source": "FLEXIBLE_AUDIENCE",
            "upload_status": "UPLOADED",
            "segments": {
              "boolean_operator": "AND",
              "frequency": 1,
              "frequency_comparator": "NUM_GTE",
              "negate": false,
              "child_segments": [
                {
                  "custom_audience_id": "tyif",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [
                    {
                      "custom_audience_id": "txr1",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GTE",
                      "negate": false,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "tyfo",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            }
          }
        ],
        "created_at": "2015-11-10T21:26:43Z",
        "updated_at": "2015-11-11T01:11:47Z",
        "partner_source": "OTHER",
        "deleted": false,
        "audience_size": null
      },
      "request": [
        {
          "params": {
            "name": "my_flexible_audience_name",
            "audience_type": "FLEXIBLE",
            "segments": {
              "boolean_operator": "AND",
              "child_segments": [
                {
                  "custom_audience_id": "TYIF",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GT",
                  "negate": true,
                  "child_segments": [

                  ]
                },
                {
                  "boolean_operator": "OR",
                  "child_segments": [
                    {
                      "custom_audience_id": "TXR1",
                      "lookback_window": 30,
                      "child_segments": [

                      ]
                    },
                    {
                      "custom_audience_id": "TYFO",
                      "lookback_window": 30,
                      "frequency": 1,
                      "frequency_comparator": "NUM_GT",
                      "negate": true,
                      "child_segments": [

                      ]
                    }
                  ]
                }
              ]
            },
            "account_id": "qsx3w2"
          },
          "operation_type": "Create"
        }
      ]
    }

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

現在のアカウントに属する、指定された Custom Audience を削除します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/custom_audiences/:custom_audience_id Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須となるパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
custom_audience_id required	リクエストで操作の対象となる Custom Audience を指します。 Type: string Example: `2906h`

Example Request DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/custom_audiences/2906h Example Response

    {
      "data": {
        "targetable": false,
        "name": "developers",
        "targetable_types": [
          "CRM",
          "EXCLUDED_CRM"
        ],
        "audience_type": "CRM",
        "description": null,
        "permission_level": "READ_WRITE",
        "owner_account_id": "18ce54d4x5t",
        "id": "2906h",
        "reasons_not_targetable": [
          "TOO_SMALL"
        ],
        "created_at": "2017-08-22T23:34:26Z",
        "updated_at": "2017-08-30T18:09:00Z",
        "partner_source": "OTHER",
        "deleted": true,
        "audience_size": null
      },
      "request": {
        "params": {
          "custom_audience_id": "2906h",
          "account_id": "18ce54d4x5t"
        }
      }
    }

接触禁止リスト

GET accounts/:account_id/do_not_reach_lists

現在のアカウントに関連付けられている一部またはすべての Do Not Reach リストの詳細を取得します。 Note: 1 つの account_id には、Do Not Reach リストを最大 1 つしか関連付けられません Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	対象となるアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで通常は必須パラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。型: string 例: `18ce54d4x5t`
with_deleted optional	削除済みの結果をレスポンスに含めるかどうかを指定します。型: boolean デフォルト: `false` 取りうる値: `true`, `false`

Example Request GET https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists Example Response

    {
      "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

現在のアカウントに関連付けられた新しい Do Not Reach リストを作成します。注: account_id ごとに作成できる Do Not Reach リストは最大 1 つです Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists Parameters

Name	Description
account_id required	対象のアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメータです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
description optional	このリストの説明です。 Type: string Example: `A list of users to exclude`

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

    {
      "request": {
        "params": {
          "description": "除外するユーザーのリスト",
          "account_id": "18ce54bgxky"
        }
      },
      "data": {
        "targetable": false,
        "name": "Do Not Reach リスト",
        "description": "除外するユーザーのリスト",
        "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 に対してユーザーを追加・更新・削除できます。このエンドポイントでは、有効なユーザー識別子としてメールアドレスのみを受け付けます。リクエストの emails フィールドで提供されるすべてのデータは、SHA256 でハッシュ化し、正規化されていなければなりません。 注意事項

1 つの account_id が持てる Do Not Reach List は最大 1 つです
このリストに追加されるユーザーには、現在のタイムスタンプから 13 か月未満となる expires_at タイムスタンプを必ず設定する必要があります
Do Not Reach List API は effective_at タイムスタンプを受け付けず、現在のタイムスタンプをデフォルトとして使用します
Do Not Reach List は、そのアカウント内のいずれかまたはすべてのカスタムオーディエンスからユーザーを削除するものではなく、そのアカウントで配信されるすべてのキャンペーンに対する除外ターゲティングとして機能します

バッチリクエスト

現在の最大バッチサイズはこのエンドポイントに対して 2500 です。バッチサイズは、リクエストごとの操作数 (Update / Delete) によって決まります。たとえば、1 つの配列内に 2500 を超える操作オブジェクト ({"operation_type": "Update/Delete", [..] }) が含まれているとエラーになります。
このエンドポイントが受け付けるリクエスト POST ボディの最大サイズは 5,000,000 バイトです。
このエンドポイントのレート制限は、1 分あたり 1500 件です。
すべてのパラメータはリクエストボディで送信され、Content-Type は application/json である必要があります。
バッチリクエストはグループとして一括で成功または失敗し、エラーと成功の両方について、すべての API レスポンスは初回リクエストのアイテム順序を保持します。

バッチレスポンス Ads API から返されるレスポンスには、success_count と total_count の 2 つのフィールドが含まれます。これらの値は常に等しくなければならず、バックエンドによって処理された、リクエスト内のレコード数を表します。リクエストボディで送信されたレコード数が success_count および total_count と等しくない場合は、再試行が必要なエラー状態として扱う必要があります。 バッチエラー

リクエストレベルのエラー (例: 最大バッチサイズ超過) は、レスポンスの errors オブジェクトに表示されます。
アイテムレベルのエラー (例: 必須パラメータの欠如) は、レスポンスの operation_errors オブジェクトに表示されます。
operation_errors 内のエラーのインデックスは、入力アイテム内のインデックスに対応しており、それぞれに対応するエラーメッセージが含まれます。

Resource URL https://ads-api.x.com/12/batch/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id/users Parameters

Name	Description
account_id required	対象とするアカウントの識別子です。リソースのパス内に現れ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータとなります。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: `18ce54d4x5t`
do_not_reach_list_id required	リクエストで操作対象となる Do Not Reach List を参照します。 Type: string Example: `2906h`
operation_type required	実行される `users` グループごとの操作種別です。 Type: enum Possible values: `Update`, `Delete`
params required	`emails` 配列および `expires_at` タイムスタンプを含む JSON オブジェクトです。 Type: JSON
users required	各ユーザーに関するすべての params を含む JSON オブジェクトの配列です。 Type: JSON
expires_at optional	ユーザー関連付けが失効する UTC 時刻です。指定された時間は、現在のタイムスタンプより後でなければなりません。ISO 8601 形式で表現します。デフォルトは、現在のタイムスタンプから 13 か月後です。 Type: string Example: `2017-07-05T07:00:00Z`

users オブジェクトに対するマルチキー方式に基づき、このオブジェクトの各要素については以下で説明します。

Name	Description
email optional	ユーザーのメールアドレス。 Type: Array[String]
phone_number optional	ユーザーの電話番号。 Type: Array[String]

リクエスト例

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

    [
      {
        "operation_type": "Update",
        "params": {
          "expires_at": "2023-01-22T00:00:00Z",
          "users": [
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABC"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9A"
              ]
            },
            {
              "email": [
                "FEAD76F6ADF99FFFB997AA4E3C8AD38FF531BC4C956DBD03CD0163F744D8AABA"
              ],
              "phone_number": [
                "CCABF1B62A202E0FE28BC6C014983C89A65451DD4482BD66A0ADB65366F38A9E"
              ]
            }
          ]
        }
      }
    ]

レスポンス例

    {
      "data": [
        {
          "success_count": 2,
          "total_count": 2
        }
      ],
      "request": [
        {
          "params": {
            "do_not_reach_list_id": "4ofrq",
            "expires_at": "2023-01-22T00:00:00Z",
            "account_id": "18ce54bgxky"
          },
          "operation_type": "Update"
        }
      ]
    }

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

現在のアカウントに属している、指定された「Do Not Reach」リストを削除します。 Resource URL https://ads-api.x.com/12/accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id Parameters なし Example Request DELETE https://ads-api.x.com/12/accounts/18ce54bgxky/do_not_reach_lists/4ofrp Example Response

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

X Ads API

基本

リソース

計測

​カスタムオーディエンス

​概要

​Audiences FAQ

​CRM

​パートナー ID マッチング要件

​標準マッチング要件

​カスタムセグメントリストのファイル命名規則と操作

​オーディエンスの作成と更新

​ハッシュ化手順

​E-mail 正規化

​デバイス ID の正規化

​X ユーザー ID の正規化

​ID Sync 連携

​Pixel URL

​ピクセルパラメーター

​ID Sync Pixel:

​カスタムオーディエンスのユーザーデータ

​カスタムオーディエンス: Web

​Audience API との連携

​概要

​新しいカスタムオーディエンスを作成する

​オーディエンスにユーザーを追加する

​オーディエンスからユーザーを削除する

​オプトアウトしたユーザー

​APIリファレンス

​キーワードインサイト

​GET insights/keywords/search

​テイラードオーディエンス権限

​GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

​DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

​ターゲットオーディエンス

​GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

​カスタムオーディエンスのユーザー

​POST accounts/:account_id/custom_audiences/:custom_audience_id/users

​リソース URL

​パラメーター

​リクエスト例

​レスポンス例

​カスタムオーディエンスの権限

​GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

​カスタムオーディエンス

​GET accounts/:account_id/custom_audiences

​GET accounts/:account_id/custom_audiences/:custom_audience_id

​POST accounts/:account_id/custom_audiences

​PUT accounts/:account_id/custom_audiences/:custom_audience_id

​POST batch/accounts/:account_id/custom_audiences

​DELETE accounts/:account_id/custom_audiences/:custom_audience_id

​接触禁止リスト

​GET accounts/:account_id/do_not_reach_lists

​POST accounts/:account_id/do_not_reach_lists

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

​DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id

カスタムオーディエンス

概要

Audiences FAQ

CRM

パートナー ID マッチング要件

標準マッチング要件

カスタムセグメントリストのファイル命名規則と操作

オーディエンスの作成と更新

ハッシュ化手順

E-mail 正規化

デバイス ID の正規化

X ユーザー ID の正規化

ID Sync 連携

Pixel URL

ピクセルパラメーター

ID Sync Pixel:

カスタムオーディエンスのユーザーデータ

カスタムオーディエンス: Web

Audience API との連携

概要

新しいカスタムオーディエンスを作成する

オーディエンスにユーザーを追加する

オーディエンスからユーザーを削除する

オプトアウトしたユーザー

APIリファレンス

キーワードインサイト

GET insights/keywords/search

テイラードオーディエンス権限

GET accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

POST accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions

DELETE accounts/:account_id/tailored_audiences/:tailored_audience_id/permissions/:tailored_audience_permission_id

ターゲットオーディエンス

GET accounts/:account_id/custom_audiences/:custom_audience_id/targeted

カスタムオーディエンスのユーザー

POST accounts/:account_id/custom_audiences/:custom_audience_id/users

リソース URL

パラメーター

リクエスト例

レスポンス例

カスタムオーディエンスの権限

GET accounts/:account_id/custom_audiences/:custom_audience_id/permissions

POST accounts/:account_id/custom_audiences/:custom_audience_id/permissions

DELETE accounts/:account_id/custom_audiences/:custom_audience_id/permissions/:custom_audience_permission_id

カスタムオーディエンス

GET accounts/:account_id/custom_audiences

GET accounts/:account_id/custom_audiences/:custom_audience_id

POST accounts/:account_id/custom_audiences

PUT accounts/:account_id/custom_audiences/:custom_audience_id

POST batch/accounts/:account_id/custom_audiences

DELETE accounts/:account_id/custom_audiences/:custom_audience_id

接触禁止リスト

GET accounts/:account_id/do_not_reach_lists

POST accounts/:account_id/do_not_reach_lists

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

DELETE accounts/:account_id/do_not_reach_lists/:do_not_reach_list_id