概要
はじめに
ユースケース
- クリエイティブ
- ターゲティング
- 入札タイプ
- 入札単位
A/B テスト
ユースケース
- クリエイティブ
- ターゲティング
- 入札タイプ
- 入札単位
属性
- テスト期間（start_time と end_time の fields で指定）
- 分割を行うレベル（entity_type field で指定）
- ユーザーグループが少なくとも 2（最大 30）。各グループは user_groups 配列内のオブジェクトとして表します
- 当該ユーザーグループに割り当てるユーザーの割合（size field で指定）
- 当該ユーザーグループのユーザープールを構成するキャンペーン ID／ラインアイテム ID（entity_ids 配列で指定）
使い方
作成
-
start_time と end_time の値は、次の条件を満たす必要があります
- （A/B テストの作成時点から見て）将来の時刻であること
- キャンペーン/ラインアイテムのフライト期間と重複していること
- 非アプリベースのキャンペーンは少なくとも 1 日、アプリベースのキャンペーンは少なくとも 5 日間の実施が必要です
- entity_type は CAMPAIGN または LINE_ITEM に設定できます
-
各ユーザーグループは user_groups 配列内のオブジェクトとして表されます
- 最低 2 つのユーザーグループが必要です
- 最大 30 のユーザーグループまで許可されます
-
各ユーザーグループのサイズは、1.00〜99.00 の数値を文字列で表して設定します
- 注意: サイズの値はオブジェクト全体で合計が 100.00 になるように 必ず してください
- キャンペーン ID は、各ユーザーグループの entity_ids 配列で指定します
- A/Bテスト用キャンペーンのすべてのラインアイテムをスプリットテストに含める必要があります。
- ラインアイテムレベルでは均等分割のみが許可されます。
- 1つのスプリットテストで許可されるユーザーグループのラインアイテム数は5以下でなければなりません。
- ユーザーグループあたりラインアイテムは1つのみです。
更新
- オブジェクトや要素を追加または削除する場合は、配列全体（およびその下位構造）を渡します。これは置換操作です
-
それ以外の場合は、キー名または ID を参照して既存のfieldsを変更（変更、追加、削除）します
- フィールドを削除するには、その値を null に設定します
- 渡されなかったフィールドは変更されません
リクエスト例
- 名前と説明なしで 3 番目のユーザーグループを追加
- 各ユーザーグループのユーザー割合を変更
- A/Bテストの説明を削除する
- 最初のユーザーグループに説明を追加する
- 2番目のユーザーグループにエンティティID（f2syz）を追加する
- 2番目のユーザーグループを削除する
- 各ユーザーグループのユーザー割合を変更する
API リファレンス
A/B テスト
GET accounts/:account_id/ab_tests
一部またはすべての A/B テストの詳細を取得します。リソースURL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
パラメータ
| Name | Description |
|---|---|
| account_id 必須 | 対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで基本的に必須です。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| ab_test_ids 任意 | 識別子のカンマ区切りリストを指定して、返却対象を希望する A/B テストのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: hr7l0 |
| count 任意 | 個別のリクエストごとに取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000 |
| cursor 任意 | 次ページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow |
| live_during 任意 | 指定した日付範囲の間に実施中だった、または実施予定の A/B テストに結果を絞り込みます。開始時刻と終了時刻が指定した日付範囲と一部または完全に重なる A/B テストを返します。 値は ISO 8601 形式のカンマ区切りの日付として指定してください。早い日付を先に指定します。 Type: string Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z |
| q 任意 | name によるリソースの絞り込みに使用する任意のクエリ。すべてを取得する場合はこのパラメータを省略します。Type: string Min, Max length: 1, 80 |
| sort_by 任意 | サポートされている属性で昇順または降順に並べ替えます。詳細は Sorting を参照してください。 Type: string Example: created_at-asc |
| status 任意 | 指定したステータスの A/B テストに結果を絞り込みます。 Type: enum Possible values: COMPLETED, LIVE, SCHEDULED |
| user_id 任意 | 指定したユーザー ID によって作成された A/B テストに結果を絞り込みます。 Note: username と同時には指定できません。Type: long Example: 756201191646691328 |
| username 任意 | 指定したユーザー名によって作成された A/B テストに結果を絞り込みます。先頭の「@」記号は含めないでください。 Note: user_id と同時には指定できません。Type: string Example: apimctestface |
| with_deleted 任意 | 削除済みの結果を含めます。 Type: boolean Default: false Possible values: true, false |
リクエスト例
GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests
応答例
POST accounts/:account_id/ab_tests
新規のA/Bテストを作成します。 すべてのパラメータはリクエスト本文で送信され、Content-Type は application/json を指定する必要があります。
リソースURL
https://ads-api.x.com/12/accounts/:account_id/ab_tests
パラメーター
| 名前 | 説明 |
|---|---|
| account_id 必須 | 対象のアカウント識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t |
| end_time 必須 | A/B テストの終了時刻（ISO 8601 形式）。 型: string 例: 2020-10-02T00:00:00Z |
| entity_type 必須 | ユーザーグループを分割する際に用いるエンティティの種類。 型: enum 可能な値: CAMPAIGN, LINE_ITEM |
| start_time 必須 | A/B テストの開始時刻（ISO 8601 形式）。 型: string 例: 2022-05-30T00:00:00Z |
| user_groups 必須 | ユーザーグループの定義。詳細は以下の表を参照。2〜30 のユーザーグループを指定できます。 型: array of objects |
| description 任意 | A/B テストの説明。最大長: 1,024 文字。 型: string 例: documentation example |
| name 任意 | A/B テストの名称。最大長: 255 文字。 型: string 例: first AB test |
ユーザーグループ
| 名前 | 説明 |
|---|---|
| entity_ids 必須 | エンティティ ID の配列。 注: エンティティは 1 つの A/B テストにのみ関連付けられます。 型: array 例: ["dxi0l", "e66bl"] |
| size 必須 | このユーザーグループに割り当てるユーザーの割合。小数点以下 2 桁までの数値を文字列で表します。例として 40% は 40、40.0、または 40.00 のいずれかで表します。 注: オブジェクト間の size の値は合計で必ず 100.00 になる必要があります。 型: array 最小値、最大値: 1.00, 99.00 |
| description 任意 | ユーザーグループの説明。最大長: 1,024 文字。 型: string 例: second AB test group |
| name 任意 | ユーザーグループの名前。最大長: 255 文字。 型: string 例: first group |
リクエスト例
POST https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests -d '{"end_time": "2022-05-30T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2022-05-25T01:00:00Z", "user_groups": [{"entity_ids": ["f2qcw", "f2tht"], "size": "50.00", "name": "first group"},{"entity_ids": ["f2rqi", "f2tws"], "size": "50.00", "name": "second group", "description": "second AB test group"}], "name": "first AB test", "description": "documentation example"}'
レスポンスの例
PUT accounts/:account_id/ab_tests/:ab_test_id
指定された A/B テストを更新します。 すべてのパラメータはリクエストボディで送信され、Content-Type は application/json を指定する必要があります。
このエンドポイントは、オブジェクト ID を含む部分的な JSON をサポートします。以下の原則が適用されます。
- オブジェクトや要素を追加または削除する場合は、配列全体（およびそのサブ構造）を渡してください。これは置換操作です
- 配列を再作成するイメージです
- それ以外の場合は、キー名または ID を参照して既存のフィールドを変更（変更、追加、削除）してください
- フィールドを削除するには、その値を
nullに設定します - 渡されなかったフィールドは変更されません
- フィールドを削除するには、その値を
status が SCHEDULED の間のみ更新できます。例外が 1 つあります。LIVE の間に A/B テストの end_time を更新することは可能です。
リソース URL
https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id
パラメーター
| Name | Description |
|---|---|
| account_id required | 使用するアカウントの識別子。リソースのパスに含まれ、GET accounts を除くすべての Advertiser API リクエストで原則必須です。指定したアカウントは、認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t |
| ab_test_id required | リクエストで操作対象の A/B テストを指す参照。 Type: string Example: hr7l0 |
| description optional | A/B テストの説明。最大長: 1,024 文字。 Note: A/B テストの status が SCHEDULED の間のみ更新できます。Type: string Example: documentation example |
| end_time optional | A/B テストの終了時刻（ISO 8601 形式）。 Note: A/B テストの status が SCHEDULED または LIVE の間のみ更新できます。Type: string Example: 2020-10-02T00:00:00Z |
| name optional | A/B テストの名前。最大長: 255 文字。 Note: A/B テストの status が SCHEDULED の間のみ更新できます。Type: string Example: first AB test |
| start_time optional | A/B テストの開始時刻（ISO 8601 形式）。 Note: A/B テストの status が SCHEDULED の間のみ更新できます。Type: string Example: 2022-05-30T00:00:00Z |
| user_groups required | ユーザーグループの定義。詳細は下表を参照してください。 Note: A/B テストの status が SCHEDULED の間のみ更新できます。Type: array of objects |
ユーザーグループ
| 名前 | 説明 |
|---|---|
| id 場合によっては必須 | リクエストで操作対象となるユーザーグループオブジェクトへの参照。 注: ユーザーグループオブジェクトの fields を変更（変更、追加、削除）する場合は必須です。 注: ユーザーグループオブジェクト全体を追加または削除する場合は ID を指定しないでください。 Type: string Example: p1bcx |
| description 任意 | ユーザーグループの説明。最大 1,024 文字。 注: フィールドに null を指定すると未設定（削除）になります。Type: string Example: second AB test group |
| entity_ids 任意 | エンティティ ID の配列。 注: これは置換操作です。以前に設定されていた値を上書きします。 注: エンティティは 1 つの A/B テストにのみ関連付けられます。 Type: array Example: ["dxi0l", "e66bl"] |
| name 任意 | ユーザーグループの名前。最大 255 文字。 注: フィールドに null を指定すると未設定（削除）になります。Type: string Example: first group |
| size 任意 | このユーザーグループに割り当てるユーザーの割合。小数点以下は最大 2 桁の数値を文字列として表現します。例: 40% は 40、40.0、または 40.00。 注: オブジェクト間の size の値は合計で必ず 100.00 になる必要があります。 Type: string Min, Max: 1.00, 99.00 |
リクエスト例
- A/B テストの説明を削除します
- 終了時刻を変更します
- 最初のユーザーグループに説明を追加します
- 各ユーザーグループのユーザー割合を変更します
- 2 番目のユーザーグループにエンティティ ID（
f2syz）を追加します
PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0 -d '{"description": null, "end_time": "2022-06-01T01:00:00Z", "user_groups": [{"id": "p1bcx", "description": "first AB test group", "size": "60.00"},{"id": "p1bcy", "size": "40.00", "entity_ids": ["f2rqi", "f2tws", "f2syz"]}]}'
レスポンスの例
DELETE accounts/:account_id/ab_tests/:ab_test_id
指定した A/B テストを削除します。 注意: A/B テストの削除は取り消せません。以後、このリソースの削除を試みると HTTP 404 が返されます。リソース URL
https://ads-api.x.com/12/accounts/:account_id/ab_tests/:ab_test_id
パラメータ
| 名前 | 説明 |
|---|---|
| ab_test_id 必須 | このリクエストで操作対象となる A/B テストを参照する識別子。 型: string 例: hr7l0 |
リクエスト例
DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests/hr7l0