Audiences

テイラードオーディエンス（廃止）

Postmanで実行 ❯

注: このページのエンドポイントは廃止されています。v8では引き続き利用できますが、v9では利用できません。

GET accounts/:account_id/tailored_audiences

現在のアカウントに関連付けられている一部またはすべてのテイラードオーディエンスの詳細を取得します。

リソースURL

https://ads-api.x.com/8/accounts/:account_id/tailored_audiences

パラメーター

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t
count
任意

個別のリクエストごとに試行および取得するレコード数を指定します。

タイプ: 整数

デフォルト: 200
最小、最大: 1、1000
cursor
任意

結果の次のページを取得するためのカーソルを指定します。詳細については、「ページネーション」を参照してください。

タイプ: 文字列

例: 8x7v00oow
permission_scope
任意

自分が所有するリスト、または自分と共有されているリストに応答をフィルタリングできます。デフォルトでは、このパラメーターを指定しないと、自分が所有するオーディエンスのみが表示されます。

タイプ: 列挙

デフォルト: OWNER
使用可能な値: OWNER、SHARED
q
任意

リソースをnameごとに範囲設定する任意のクエリ。

注: プレフィックスの一致は大文字と小文字を区別します。

タイプ: 文字列

最小および最長の長さ: 1、255
sort_by
任意

サポートされている属性で昇順または降順に並べ替えます。詳細については、「並べ替え」を参照してください。

タイプ: 文字列

例: created_at-asc
tailored_audience_ids
任意

カンマ区切りのIDリストを指定して、応答の範囲を目的のテイラードオーディエンスのみに設定します。最大200件のIDを指定できます。

タイプ: 文字列

例: 1nmth
with_deleted
任意

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

タイプ: ブール値

デフォルト: false
使用可能な値: true、false
with_total_count
任意

total_count応答属性を含めます。

注: このパラメーターとcursorとは相互に排他的です。

注: total_countを含むリクエストの場合、レート制限が低くなります。現在15分あたり200に設定されています。

タイプ: ブール値

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

リクエストの例

GET https://ads-api.x.com/8/accounts/18ce54d4x5t/tailored_audiences?tailored_audience_ids=1nmth

応答の例

{
  "request": {
    "params": {
      "tailored_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/tailored_audiences/:tailored_audience_id

現在のアカウントに関連付けられている特定のテイラードオーディエンスの詳細を取得します。

リソースURL

https://ads-api.x.com/8/accounts/:account_id/tailored_audiences/:tailored_audience_id

パラメーター

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t
tailored_audience_id
必須

リクエストで操作するテイラードオーディエンスへの参照。

タイプ: 文字列

例: 2906h
with_deleted
任意

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

タイプ: ブール値

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

リクエストの例

GET https://ads-api.x.com/8/accounts/18ce54d4x5t/tailored_audiences/2906h

応答の例

{
  "request": {
    "params": {
      "tailored_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/tailored_audiences

現在のアカウントに関連付けられているテイラードオーディエンスの新しいプレースホルダーを作成します。

リソースURL

https://ads-api.x.com/8/accounts/:account_id/tailored_audiences

パラメーター

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t
name
必須

このオーディエンスの表示名。

タイプ: 文字列

例: ads api users
description
任意

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

タイプ: 文字列

例: Collection of all users of the Ads API

リクエストの例

POST https://ads-api.x.com/8/accounts/18ce54d4x5t/tailored_audiences?name=developers

応答の例

{
  "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/tailored_audiences/:tailored_audience_id

現在のアカウントに関連付けられている特定のテイラードオーディエンスを更新します。

リソースURL

https://ads-api.x.com/8/accounts/:account_id/tailored_audiences/:tailored_audience_id

パラメーター

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t
tailored_audience_id
必須

リクエストで操作するテイラードオーディエンスへの参照

タイプ: 文字列

例: 2906h
name
任意

このオーディエンスの表示名。

タイプ: 文字列

例: ads api users
description
任意

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

タイプ: 文字列

例: Collection of all users of the Ads API

リクエストの例

PUT https://ads-api.x.com/8/accounts/18ce54d4x5t/tailored_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/tailored_audiences

テイラードオーディエンスを一括で作成できます。オーディエンスの詳細については、「テイラードオーディエンスの概要」ページを参照してください。

注:このバッチエンドポイントは、現在クローズドベータ版であり、一部の広告主のみが利用できます。このベータ期間中は、モバイルテイラードオーディエンスに基づいたフレキシブルオーディエンスのみを作成できます。

バッチリクエスト

  • 現在のバッチの最大サイズは10です。
  • すべてのパラメーターはリクエストボディで送信され、application/jsonのContent-Typeが必須です。
  • バッチリクエストはグループ単位で失敗または成功となります。エラーの場合も、成功の場合も、API応答には、最初のリクエストの項目の順序が保持されます。

バッチ応答

バッチAPIの応答は、項目のコレクションを順番どおりに返します。その点を除くと、バッチAPIの構造は、対応する単一項目のエンドポイントと同じです。

バッチエラー

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

フレキシブルオーディエンス

Postmanで実行 ❯
  • フレキシブルオーディエンスは、一度作成すると変更できません。
  • テイラードオーディエンスが、ブール論理の組み合わせを持つツリー構造に渡され、フレキシブルオーディエンスが作成されます
  • フレキシブルオーディエンスの作成には、最大10個のテイラードオーディエンスのリーフノードを使用できます。

リソースURL

https://ads-api.x.com/8/batch/accounts/:account_id/tailored_audiences

パラメーター

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t
audience_type
必須

作成するオーディエンスのタイプ。

タイプ: 列挙

使用可能な値: FLEXIBLE、MOBILE_AUDIENCE
child_segments
必須

ターゲティングするテイラードオーディエンスのメンバーのサブセットを定義するオブジェクトを含む配列。各オブジェクトには、tailored_audience_id、frequency、frequency_comparator、lookback_window、negate、場合によっては追加のchild_segmentsが含まれます。

タイプ: 配列
name
必須

オーディエンスの表示名。

タイプ: 文字列

例: my_flexible_audience_name
operation_type
必須

実行中の、項目ごとの操作タイプ。

タイプ: 列挙

使用可能な値: Create、Update、Delete
boolean_operator
必須の場合あり

その親（含まれる）オブジェクト内での子セグメント間の論理関係。親オブジェクトのchild_segmentsが空でない場合は、必須になります。

タイプ: 列挙

使用可能な値: AND、OR
lookback_window
必須の場合あり

ユーザーが特定のアクションを実行し、特定のテイラードオーディエンスの対象となった日数の範囲を指定する整数値。

タイプ: 整数

使用可能な値: 1、7、14、30
segments
必須の場合あり

ターゲティングするテイラードオーディエンスのメンバーのサブセットを定義するboolean_operatorとchild_segmentsを含むオブジェクト。

タイプ: オブジェクト
tailored_audience_id
必須の場合あり

子セグメントとして使用するテイラードオーディエンスのID。

タイプ: 文字列

例: tyfo
frequency
任意

ルックバック期間においてユーザーが特定のアクションを実行し、特定のテイラードオーディエンスの対象となったフリークエンシーを指定する整数値。

タイプ: 整数

デフォルト値: 1
frequency_comparator
任意

リクエストで渡されるfrequencyとの比較演算子。

注: たとえば、次の値では、GTEは「以上」、LTは「未満」を表します。

タイプ: 文字列

使用可能な値: NUM_GTE、NUM_GT、NUM_EQ、NUM_LTE、NUM_LT デフォルト値: NUM_GTE
negate
任意

セグメントを否定し、組み合わせから除外されます。

タイプ: ブール値

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

リクエストの例

POST https://ads-api.x.com/8/batch/accounts/18ce54d4x5t/tailored_audiences

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

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

                ]
              },
              {  
                "tailored_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": [
      {
        "tailored_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": [
            {
              "tailored_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": [
                {
                  "tailored_audience_id": "txr1",
                  "lookback_window": 30,
                  "frequency": 1,
                  "frequency_comparator": "NUM_GTE",
                  "negate": false,
                  "child_segments": [

                  ]
                },
                {
                  "tailored_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": [
            {
              "tailored_audience_id": "TYIF",
              "lookback_window": 30,
              "frequency": 1,
              "frequency_comparator": "NUM_GT",
              "negate": true,
              "child_segments": [

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

                  ]
                },
                {
                  "tailored_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/tailored_audiences/:tailored_audience_id

現在のアカウントに属する、指定したテイラードオーディエンスを削除します。

リソースURL

https://ads-api.x.com/8/accounts/:account_id/tailored_audiences/:tailored_audience_id

パラメーター

名前 説明
account_id
必須

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

タイプ: 文字列

例: 18ce54d4x5t
tailored_audience_id
必須

リクエストで操作するテイラードオーディエンスへの参照。

タイプ: 文字列

例: 2906h

リクエストの例

DELETE https://ads-api.x.com/8/accounts/18ce54d4x5t/tailored_audiences/2906h

応答の例

{
  "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": {
      "tailored_audience_id": "2906h",
      "account_id": "18ce54d4x5t"
    }
  }
}