ABテスト

​

概要

​

はじめに

A/B テストを用いると、広告主は X 上でリーチしているユーザーをセグメント化し、キャンペーンパフォーマンスを最適化する最良の方法を把握するとともに、マーケティング戦略の立案に役立つインサイトを得ることができます。

これらのセグメント (ユーザーグループのスプリットと呼びます) は、ランダムに割り当てられ、相互に排他的です。ランダム化により、結果に影響を与える要因は均等に分配されます。言い換えると、グループ間やそれぞれの想定される行動に本質的な違いはありません。このため、あるユーザーグループにのみ特定のバリエーションを適用し、他のグループには適用しない場合、キャンペーンパフォーマンスの差はそのバリエーションに起因すると考えることができます。

一度に多くのバリエーションをテストすることも可能ですが、1 回のテストにつき 1 つのバリエーションのみを検証することを強く推奨します。これにより、観測されたキャンペーンパフォーマンスの差を生じさせた要因を切り分けて特定できます。

バリエーションはキャンペーンレベルで設定されます。たとえば、広告主が新しいクリエイティブの有効性をテストしたい場合は、クリエイティブ以外は同一で、クリエイティブだけが異なる 2 つのキャンペーンを作成する必要があります。将来的には、ラインアイテムレベルでのバリエーション設定にも対応する予定です。

​

ユースケース

A/Bテストは主に、(1) X上で何が最も効果的かを把握して投資の最適化を図りたいパフォーマンス重視の広告主向けの「最適化」ユースケースと、(2) 得られた知見を活用してマーケティング戦略の立案に役立てたいブランド広告主向けの「学習」ユースケースを支援するために利用されます。 

このAPIは、以下を含むあらゆるキャンペーン変数に対するA/Bテストをサポートします：

• クリエイティブ 

• ターゲティング 

• 入札タイプ

• 入札単位

​

A/B Testing

A/B Testing を使用すると、広告主は X 上でリーチしているユーザーをセグメント化し、キャンペーンパフォーマンスをどのように最適化すべきかを把握し、マーケティング戦略の立案に役立つ示唆を得ることができます。

これらのセグメント (ユーザーグループ分割と呼ばれます) は、ランダム化されており相互に排他的です。ランダム化により、結果に影響を与える要因は均等に分配されます。言い換えると、グループ間やそれぞれの想定される行動に本質的な差はありません。そのため、あるユーザーグループにのみ 1 つのバリエーションを適用し、他のグループには適用しなかった場合、キャンペーンパフォーマンスの差はそのバリエーションが原因で生じたものと判断できます。

一度に複数のバリエーションをテストすることも可能ですが、1 回のテストでは 1 つのバリエーションのみに絞ることを強く推奨します。これにより、観測されたキャンペーンパフォーマンスの差を生み出した因果要因を切り分けることができます。

バリエーションはキャンペーンレベルまたは広告グループレベルのいずれかで設定されます。広告グループは Ads API の line item を通じて設定されます。広告グループレベルのバリエーションの例として、広告主が新しいクリエイティブの効果検証を行いたい場合、クリエイティブ以外は同一の 2 つの広告グループを含む 1 つのキャンペーンを作成する必要があります。

​

ユースケース

A/B テストは主に、次の 2 つのユースケースを支援するために使用されます。(1) X 上で何が最も効果的かを把握し、自身の投資を最適化したいパフォーマンス広告主向けのパフォーマンス最適化ユースケースと、(2) 得られた知見をマーケティング戦略の策定に活用したいブランド広告主向けの学習ユースケースです。 

この API は、以下を含むあらゆるキャンペーン変数に対する A/B テストをサポートします。

• クリエイティブ

• ターゲティング

• 入札タイプ

• 入札単位

​

属性

A/B テストはネストされた構造として表現されます。A/B テスト自体のトップレベルのフィールドと、ユーザーグループオブジェクトの配列があり、それぞれにその内容を記述する一連のフィールドがあります。

大まかには、すべての A/B テストには次の情報を含める必要があります。

• テスト期間 (start_time フィールドと end_time フィールドで表現)

• スプリットを行うレベル (entity_type フィールドで表現)

• 少なくとも 2 個 (最大 30 個) のユーザーグループ (それぞれ user_groups 配列内のオブジェクトとして表現)

各ユーザーグループには、必ず 次の情報を含める必要があります。

• 指定されたユーザーグループに割り当てるユーザーの割合 (size フィールドで表現)

• 指定されたユーザーグループのユーザープールを構成するキャンペーン ID およびラインアイテム ID (entity_ids 配列で表現)

任意で、A/B テストおよびユーザーグループに対して name と description の値を設定できます。検証ルールやその他の制約に関する情報は、以下を参照してください。

ID や作成日時などのその他のメタデータも含まれますが、これらは X によって自動的に設定されます。

キャンペーンレベルの A/B テストエンティティの例を以下に示します。

{
  "created_at": "2020-12-01T00:00:00Z",
  "created_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  },
  "deleted": false,
  "description": "documentation example",
  "end_time": "2020-12-05T01:00:00Z",
  "entity_type": "CAMPAIGN",
  "id": "hr7l0",
  "name": "first AB test",
  "start_time": "2020-12-01T01:00:00Z",
  "status": "SCHEDULED",
  "user_groups": [
    {
      "id": "p1bcx",
      "name": "first group",
      "description": null,
      "size": "50.0",
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ]
    },
    {
      "id": "p1bcy",
      "name": "second group",
      "description": "second AB test group",
      "size": 50,
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ]
    }
  ],
  "updated_at": "2020-12-01T00:00:00Z",
  "updated_by": {
    "user_id": "756201191646691328",
    "username": "apimctestface"
  }
}

ラインアイテム単位のA/Bテストエンティティの例を以下に示します。

{
   "created_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "name":"Test2e",
   "start_time":"2022-08-15T00:00:00Z",
   "updated_by":{
      "user_id":"756201191646691328",
      "username":"apimctestface"
   },
   "description":"My Second AB test",
   "entity_type":"LINE_ITEM",
   "end_time":"2022-08-30T00:00:00Z",
   "id":"1ul",
   "user_groups":[
      {
         "name":"first group",
         "size":"50.0",
         "description":"first group description",
         "entity_ids":[
            "ij9dh"
         ],
         "id":"4xe"
      },
      {
         "name":"second group",
         "size":"50.0",
         "description":"second group description",
         "entity_ids":[
            "ihng8"
         ],
         "id":"4xf"
      }
   ],
   "status":"SCHEDULED",
   "created_at":"2022-08-11T00:10:50Z",
   "updated_at":"2022-08-11T00:10:50Z",
   "deleted":false
}

​

使用方法

以下のサブセクションでは、A/B テストを作成および更新する方法について説明します。取得および削除は、他のすべての Ads API エンドポイントと同様に動作します。

​

作成

POST accounts/:account_id/ab_tests エンドポイントを使用して A/B テストを作成します。このエンドポイントは JSON の POST ボディのみを受け付けます。Content-Type は application/json に設定する必要があります。

広告主が 2 つ以上のキャンペーンを設定した後に、A/B テストを作成できます。上記のとおり、A/B テストには必ずテスト期間、分割レベル、そして少なくとも 2 つのユーザーグループを含める 必要があります。各ユーザーグループでは、そのグループに割り当てるユーザーの割合と、そのユーザープールを構成するキャンペーン ID を指定する必要があります。これらについては以下で詳しく説明します。

テスト期間:

• 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 つ以上のユーザーグループに対して name と description を設定します。

次のリクエストは、キャンペーンレベルの A/B テストを作成します。このテストは 4 日間継続し、各グループに 50% のユーザーを割り当てた 2 つのユーザーグループを持ちます。最初のユーザーグループはキャンペーン f2qcw と f2tht に基づき、2 番目のユーザーグループはキャンペーン f2rqi と f2tws に基づきます。このリクエストでは、エンティティの一部に name と description も追加しています。

twurl -X POST -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests” -d ’{“end_time”: “2020-12-05T01:00:00Z”, “entity_type” : “CAMPAIGN”, “start_time”: “2020-12-01T01: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”}’

twurl -X POST -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests" -d '{"end_time": "2020-12-05T01:00:00Z", "entity_type" : "CAMPAIGN", "start_time": "2020-12-01T01: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"}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "end_time": "2020-12-05T01:00:00Z",
      "entity_type": "CAMPAIGN",
      "start_time": "2020-12-01T01:00:00Z",
      "user_groups": [
        {
          "entity_ids": [
            "f2qcw",
            "f2tht"
          ],
          "size": "50.0",
          "name": "first group"
        },
        {
          "entity_ids": [
            "f2rqi",
            "f2tws"
          ],
          "size": "50.0",
          "name": "second group",
          "description": "second AB test group"
        }
      ],
      "name": "first AB test",
      "description": "documentation example"
    }
  },
  "data": {
    "created_at": "2020-12-01T00:00:00Z",
    "created_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    },
    "deleted": false,
    "description": "documentation example",
    "end_time": "2020-12-05T01:00:00Z",
    "entity_type": "CAMPAIGN",
    "id": "hr7l0",
    "name": "first AB test",
    "start_time": "2020-12-01T01:00:00Z",
    "status": "SCHEDULED",
    "user_groups": [
      {
        "id": "p1bcx",
        "name": "first group",
        "description": null,
        "size": "50.0",
        "entity_ids": [
          "f2qcw",
          "f2tht"
        ]
      },
      {
        "id": "p1bcy",
        "name": "second group",
        "description": "second AB test group",
        "size": "50.0",
        "entity_ids": [
          "f2rqi",
          "f2tws"
        ]
      }
    ],
    "updated_at": "2020-12-01T00:00:00Z",
    "updated_by": {
      "user_id": "756201191646691328",
      "username": "apimctestface"
    }
  }
}

ラインアイテムレベルでの A/B テストの場合

キャンペーンレベルとラインアイテムレベルでの A/B テストの主な違いは、entity_type です。ラインアイテムレベルでの A/B テストでは、entity_type を LINE_ITEM に設定する必要があります。これは、以下の、既に作成済みの A/B テストに対して行うすべてのアクションに適用されます。 

要件:

1. A/B テスト対象キャンペーンのすべてのラインアイテムをスプリットテストに含める必要があります。
2. ラインアイテムレベルでは、分割比率が均等な場合のみ許可されます。
3. 1 つのスプリットテスト内で設定できるユーザーグループ用ラインアイテムの数は、5 以下でなければなりません。 
4. 各ユーザーグループにつき 1 つのラインアイテムのみ許可されます。

​

更新

PUT accounts/:account_id/ab_tests/:ab_test_id エンドポイントを使用して A/B テストを更新します。このエンドポイントでは、リクエスト内で JSON ブロブを送信する必要があります。Content-Type は application/json に設定する必要があります。

他の更新用エンドポイントと同様に、PUT accounts/:account_id/ab_tests/:ab_test_id エンドポイントでは、URL 内で A/B テスト ID を指定する必要があります。一般的に、A/B テストは status が SCHEDULED の場合にのみ更新できます。例外が 1 つあり、LIVE の間でも A/B テストの end_time を更新することは可能です。

このエンドポイントは、オブジェクト ID を含む部分的な JSON をサポートします。次の原則が適用されます。

• オブジェクトや要素を追加または削除するには、配列全体 (およびそのサブ構造) を渡します。これは 置換 操作です。

• それ以外の場合は、キー名または ID を参照して、既存の フィールド を変更 (変更、追加、削除) します。

  • フィールドを削除するには、その値を null に設定します。

  • 渡されなかったフィールドは変更されません。

たとえば、先ほど作成した A/B テストに 3 番目のユーザーグループを追加するには、既存の 2 つのユーザーグループオブジェクトに加えて、新たに追加したいものを含めた user_groups 配列を送信する必要があります。これは user_groups 配列を 再作成 するようなものと考えてください。最初からこの方法で作成しているかのようにデータを渡します (ユーザーグループオブジェクトの ID は渡さないでください) 。更新リクエスト内の user_groups 配列は次のように表現できます。

[
  {
    "entity_ids": [
      "f2qcw",
      "f2tht"
    ],
    "size": "30.0",
    "name": "first group"
  },
  {
    "entity_ids": [
      "f2rqi",
      "f2tws"
    ],
    "size": "30.0",
    "name": "second group",
    "description": "second AB test group"
  },
  {
    "entity_ids": [
      "i1vwr",
      "i1xre"
    ],
    "size": "40.0"
  }
]

オブジェクト間の size の値を合計すると、引き続き 100.00 になっている点に注意してください。もし最初の 2 つのオブジェクト (以前はそれぞれ 50.00 に設定されていた) の値を更新していなかった場合、このリクエストは失敗していたでしょう。

代わりに、最初のユーザーグループに description を追加するだけでよい場合、更新リクエスト内の user_groups 配列は次のようになります。

[
  {
    "id": "p1bcx",
    "description": "updated using a PUT request"
  }
]

ユーザーグループオブジェクトを ID で参照し、更新したいフィールドだけを含めます。

​

リクエスト例

このセクションでは、追加の更新リクエスト例を示します。これらは連続して呼び出されるものと考えてください。JSON ブロブは可読性のために整形されています。レスポンスは省略しています。

次の変更を行うためのリクエストは、次のようになります。 (これは上で使用した例と同じです。)

1. 名前と説明のない 3 つ目のユーザーグループを追加する

2. 各ユーザーグループに属するユーザーの割合を変更する

twurl -X PUT -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests/hr7l0” -d ’

twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "user_groups": [
    {
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ],
      "size": "30.00",
      "name": "first group"
    },
    {
      "entity_ids": [
        "f2rqi",
        "f2tws"
      ],
      "size": "30.00",
      "name": "second group",
      "description": "second AB test group"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "40.00"
    }
  ]
}'

次の変更を行う場合、リクエストは次のようになります。

1. A/B テストの説明を削除する

2. 最初のユーザーグループに説明を追加する

3. 2 番目のユーザーグループにエンティティ ID (f2syz) を追加する

twurl -X PUT -H ads-api.x.com “/8/accounts/18ce54d4x5t/ab_tests/hr7l0” -d ’

twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "description": null,
  "user_groups": [
    {
      "id": "p1bcx",
      "description": "first AB test group"
    },
    {
      "id": "p1bcy",
      "entity_ids": [
        "f2rqi",
        "f2tws",
        "f2syz"
      ]
    }
  ]
}'

3 つ目の変更では、新しいエンティティ ID に加えて、既存の 2 つのエンティティ ID も渡す必要があります。3 番目のユーザーグループには変更が加えられていないことに注意してください。

次の変更を行うには、リクエストは次のようになります。

1. 2 番目のユーザーグループを削除する

2. 各ユーザーグループ内のユーザーの割合を変更する

twurl -X PUT -H ads-api.x.com "/8/accounts/18ce54d4x5t/ab_tests/hr7l0" -d '
{
  "user_groups": [
    {
      "entity_ids": [
        "f2qcw",
        "f2tht"
      ],
      "size": "55.00",
      "name": "first group"
    },
    {
      "entity_ids": [
        "i1vwr",
        "i1xre"
      ],
      "size": "45.00"
    }
  ]
}'

​

APIリファレンス

​

ABテスト

​

GET accounts/:account_id/ab_tests

一部またはすべてのA/Bテストの詳細を取得します。

リソース URL

https://ads-api.x.com/12/accounts/:account_id/ab_tests

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで一般的に必須パラメータです。指定したアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
ab_test_ids optional	カンマ区切りの識別子のリストを指定することで、応答を目的の A/B テストのみに絞り込みます。最大 200 個の ID を指定できます。 Type: string Example: hr7l0
count optional	1 回のリクエストで取得を試みるレコード数を指定します。 Type: int Default: 200 Min, Max: 1, 1000
cursor optional	次のページの結果を取得するためのカーソルを指定します。詳細は Pagination を参照してください。 Type: string Example: 8x7v00oow
live_during optional	指定された日付範囲の間に実行中であった、または実行予定である A/B テストに応答を絞り込みます。開始時刻と終了時刻が、指定された日付範囲と一部または完全に重なる A/B テストを返します。 値はカンマ区切りの日付で指定し、ISO 8601 形式で表現します。より早い日付を先に指定してください。 Type: string Example: 2020-11-01T08:00:00Z,2020-12-01T08:00:00Z
q optional	name でリソースを絞り込むための任意のクエリです。すべてを取得する場合はこのパラメータを省略します。 Type: string Min, Max length: 1, 80
sort_by optional	サポートされている属性で、昇順または降順にソートします。詳細は Sorting を参照してください。 Type: string Example: created_at-asc
status optional	目的のステータスを持つ A/B テストのみに応答を絞り込みます。 Type: enum Possible values: COMPLETED, LIVE, SCHEDULED
user_id optional	指定したユーザー ID によって作成された A/B テストに応答を絞り込みます。 Note: username と同時には指定できません。 Type: long Example: `756201191646691328.
username optional	指定したユーザー名によって作成された A/B テストに応答を絞り込みます。先頭の「@」記号は含めないでください。 Note: user_idと同時には指定できません。 Type: string Example:`apimctestface.
with_deleted optional	削除済みの結果も含めて取得します。 Type: boolean Default: false Possible values: true, false

リクエスト例

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/ab_tests

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t"
        }
      },
      "data": [
        {
          "created_at": "2022-05-25T00:00:00Z",
          "created_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          },
          "deleted": false,
          "description": "documentation example",
          "end_time": "2022-05-30T01:00:00Z",
          "entities": [
            {
              "id": "p1bcx",
              "account_id": "18ce54d4x5t"
            },
            {
              "id": "p1bcy",
              "account_id": "18ce54d4x5t"
            }
          ],
          "entity_type": "CAMPAIGN",
          "id": "hr7l0",
          "name": "first AB test",
          "start_time": "2022-05-25T01:00:00Z",
          "status": "SCHEDULED",
          "user_groups": [
            {
              "id": "p1bcx",
              "name": "first group",
              "description": null,
              "size": "50.0",
              "entity_ids": [
                "f2qcw",
                "f2tht"
              ]
            },
            {
              "id": "p1bcy",
              "name": "second group",
              "description": "second AB test group",
              "size": "50.0",
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ]
            }
          ],
          "updated_at": "2022-05-25T00:00:00Z",
          "updated_by": {
            "user_id": "756201191646691328",
            "username": "apimctestface"
          }
        }
      ],
      "next_cursor": null
    }

​

POST accounts/:account_id/ab_tests

新規の A/B テストを作成します。

すべてのパラメータはリクエストボディで送信し、Content-Type ヘッダーには application/json を指定する必要があります。

リソースURL

https://ads-api.x.com/12/accounts/:account_id/ab_tests

Parameters

Name	Description
account_id required	利用するアカウントの識別子です。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストにおいて、通常必須パラメーターです。指定されたアカウントは認証済みユーザーに関連付けられている必要があります。 Type: string Example: 18ce54d4x5t
end_time required	A/B テストが終了する時刻を、ISO 8601 形式で指定します。 Type: string Example: 2020-10-02T00:00:00Z
entity_type required	ユーザーグループを分割する際に使用されるエンティティの種類です。 Type: enum Possible values: CAMPAIGN, LINE_ITEM
start_time required	A/B テストが開始する時刻を、ISO 8601 形式で指定します。 Type: string Example: 2022-05-30T00:00:00Z
user_groups required	ユーザーグループについて説明します。詳細は下の表を参照してください。2～30 個のユーザーグループを指定できます。 Type: array of objects
description optional	A/B テストの説明です。最大長: 1,024 文字。 Type: string Example: documentation example
name optional	A/B テストの名前です。最大長: 255 文字。 Type: string Example: first AB test

​

ユーザーグループ

Name	Description
entity_ids required	エンティティ ID の配列です。 注: 各エンティティは 1 つの A/B テストにのみ関連付けることができます。 型: array 例: ["dxi0l", "e66bl"]
size required	このユーザーグループに割り当てるユーザーの割合です。数値を文字列として表し、小数点以下は最大 2 桁までです。たとえば 40% は 40、40.0、40.00 のいずれかで表します。 注: 各 オブジェクト の size の値の合計は必ず 100.00 になる必要があります。 型: array 最小値、最大値: 1.00, 99.00
description optional	ユーザーグループの説明です。最大文字数: 1,024 文字。 型: string 例: second AB test group
name optional	ユーザーグループの名前です。最大文字数: 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"}'

​

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "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.0",
              "name": "first group"
            },
            {
              "entity_ids": [
                "f2rqi",
                "f2tws"
              ],
              "size": "50.0",
              "name": "second group",
              "description": "second AB test group"
            }
          ],
          "name": "first AB test",
          "description": "documentation example"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": "documentation example",
        "end_time": "2022-05-30T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "first AB test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "first group",
            "description": null,
            "size": "50.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "second group",
            "description": "second AB test group",
            "size": "50.0",
            "entity_ids": [
              "f2rqi",
              "f2tws"
            ]
          }
        ],
        "updated_at": "2022-05-25T00:00:00Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }

​

PUT accounts/:account_id/ab_tests/:ab_test_id

指定した A/B Test を更新します。

すべてのパラメータはリクエストボディで送信され、Content-Type として application/json が必須です。

このエンドポイントは、オブジェクト id を含む部分的な JSON をサポートします。次の原則が適用されます。

• オブジェクトや要素を追加または削除する場合は、配列全体 (およびそのサブ構造) を渡します。これは 置換 操作です
  • 配列を再作成するイメージで考えてください
• それ以外の場合は、キー名または id を参照して既存のフィールドを (追加・変更・削除などで) 編集します
  • フィールドを削除するには、その値を null に設定します
  • 渡されていないフィールドは変更されません

通常、A/B Test を更新できるのは status が SCHEDULED の間のみです。例外として、status が LIVE の間でも A/B Test の end_time は更新できます。

リソース URL

https://ads-api.x.com/12/accounts/18ce54d4x5t/:ab_test_id

パラメーター

Name	Description
account_id 必須	対象となるアカウントの識別子。リソースのパス内に含まれ、GET accounts を除くすべての Advertiser API リクエストで通常必須のパラメーターです。指定されたアカウントは、認証済みユーザーに関連付けられている必要があります。 型: string 例: 18ce54d4x5t
ab_test_id 必須	このリクエストで操作の対象とする A/B Test への参照。 型: string 例: hr7l0
description 任意	A/B Test の説明。最大長は 1,024 文字です。 注記: A/B Test の status が SCHEDULED の間のみ更新できます。 型: string 例: documentation example
end_time 任意	A/B Test の終了時刻。ISO 8601 形式で指定します。 注記: A/B Test の status が SCHEDULED または LIVE の間のみ更新できます。 型: string 例: 2020-10-02T00:00:00Z
name 任意	A/B Test の名前。最大長は 255 文字です。 注記: A/B Test の status が SCHEDULED の間のみ更新できます。 型: string 例: first AB test
start_time 任意	A/B Test の開始時刻。ISO 8601 形式で指定します。 注記: A/B Test の status が SCHEDULED の間のみ更新できます。 型: string 例: 2022-05-30T00:00:00Z
user_groups 必須	ユーザーグループを表します。詳細は以下の表を参照してください。 注記: A/B Test の status が SCHEDULED の間のみ更新できます。 型: array of objects

​

ユーザーグループ

Name	Description
id sometimes required	リクエスト内で操作対象となるユーザーグループオブジェクトを参照するための値。 Note: ユーザーグループオブジェクトのフィールドを変更 (更新、追加、削除) する場合に必須です。 Note: ユーザーグループオブジェクト全体を追加または削除する際には ID を指定しないでください。 Type: string Example: p1bcx
description optional	ユーザーグループの説明。最大長: 1,024 文字。 Note: フィールドに null 値を指定することで、未設定 (削除) できます。 Type: string Example: second AB test group
entity_ids optional	エンティティ ID の配列。 Note: これは置換操作です。以前に設定されていた内容はすべて上書きされます。 Note: エンティティは 1 つの A/B テストにのみ関連付けることができます。 Type: array Example: ["dxi0l", "e66bl"]
name optional	ユーザーグループの名前。最大長: 255 文字。 Note: フィールドに null 値を指定することで、未設定 (削除) できます。 Type: string Example: first group
size optional	このユーザーグループに割り当てるユーザーの割合。小数点以下 2 桁までの数値を文字列として表現します。たとえば 40% は 40、40.0、40.00 のいずれかで表します。 Note: オブジェクト 全体の size の値は合計で必ず 100.00 にならなければなりません。 Type: string Min, Max: 1.00, 99.00

リクエスト例

このリクエストでは、次の変更を行います。

1. A/B テストの説明を削除します
2. 終了時刻を変更します
3. 最初のユーザーグループに説明を追加します
4. 各ユーザーグループのユーザー割合を変更します
5. 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"]}]}'

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0",
          "description": null,
          "end_time": "2022-06-01T01:00:00Z",
          "user_groups": [
            {
              "id": "p1bcx",
              "description": "first AB test group",
              "size": "60.0"
            },
            {
              "id": "p1bcy",
              "size": "40.0",
              "entity_ids": [
                "f2rqi",
                "f2tws",
                "f2syz"
              ]
            }
          ]
        }
      },
      "data": {
        "created_at": "2020-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": false,
        "description": null,
        "end_time": "2022-06-01T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "first AB test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "first group",
            "description": "first AB test group",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "second group",
            "description": "second AB test group",
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-05-25T00:17:23Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }

​

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

​

レスポンス例

    {
      "request": {
        "params": {
          "account_id": "18ce54d4x5t",
          "ab_test_id": "hr7l0"
        }
      },
      "data": {
        "created_at": "2022-05-25T00:00:00Z",
        "created_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        },
        "deleted": true,
        "description": null,
        "end_time": "2022-06-01T01:00:00Z",
        "entities": [
          {
            "id": "p1bcx",
            "account_id": "18ce54d4x5t"
          },
          {
            "id": "p1bcy",
            "account_id": "18ce54d4x5t"
          }
        ],
        "entity_type": "CAMPAIGN",
        "id": "hr7l0",
        "name": "first AB test",
        "start_time": "2022-05-25T01:00:00Z",
        "status": "SCHEDULED",
        "user_groups": [
          {
            "id": "p1bcx",
            "name": "first group",
            "description": "first AB test group",
            "size": "60.0",
            "entity_ids": [
              "f2qcw",
              "f2tht"
            ]
          },
          {
            "id": "p1bcy",
            "name": "second group",
            "description": "second AB test group",
            "size": "40.0",
            "entity_ids": [
              "f2rqi",
              "f2tws",
              "f2syz"
            ]
          }
        ],
        "updated_at": "2022-06-02T00:18:31Z",
        "updated_by": {
          "user_id": "756201191646691328",
          "username": "apimctestface"
        }
      }
    }