結合リストレコード - 一括

[アーティクル]
10/04/2023

一括ファイルでダウンロードおよびアップロードできる結合リストを定義します。

結合リストは、複数の既存の対象ユーザーの組み合わせから作成された対象ユーザーです。

ヒント

対象ユーザーの概要と詳細については、対象ユーザー API のテクニカルガイドを参照してください。

アカウント内のすべての結合リスト レコードをダウンロードできます。これには、DownloadCampaignsByAccountIds または DownloadCampaignsByCampaignIds サービス要求に CombinedLists の DownloadEntity 値を含めることができます。さらに、ダウンロード要求には EntityData スコープを含める必要があります。ベストプラクティスを含む一括サービスの詳細については、「一括ダウンロードとアップロード」を参照してください。

次の一括 CSV の例では、新しい結合リストを追加します。

Type,Status,Id,Parent Id,Client Id,Modified Time,Name,Description,Scope,Audience,Combination Rule
Format Version,,,,,,6.0,,,,,,
Combined List,Active,-10,,ClientIdGoesHere,,,New combined list description,Customer,New Combined List,NOT(123IdGoesHere,234IdGoesHere)&AND(345IdGoesHere,456IdGoesHere)&OR(567IdGoesHere)

.NET、Java、または Python 用の Bing Ads SDK を使用している場合は、 BulkServiceManager を使用して BulkCombinedList オブジェクトをアップロードしてダウンロードする時間を節約できます。サービス操作を直接呼び出し、カスタムコードを記述して一括ファイル内の各フィールドを解析する代わりにします。

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkCombinedList
var bulkCombinedList = new BulkCombinedList
{
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",

    // Map properties in the Bulk file to the 
    // CombinedList object of the Campaign Management service.
    CombinedList = new CombinedList
    {
        // 'Audience Network Size' column header in the Bulk file
        AudienceNetworkSize = null,
        // 'Description' column header in the Bulk file
        Description = "New Combined List",
        // 'Id' column header in the Bulk file
        Id = combinedListIdKey,
        // 'Membership Duration' column header in the Bulk file
        MembershipDuration = 30,
        // 'Audience' column header in the Bulk file
        Name = "Combined List " + DateTime.UtcNow,
        // 'Parent Id' column header in the Bulk file
        ParentId = accountIdKey,
        // 'Combination Rule' column header in the Bulk file
        CombinationRules = new[]
        {
            // Each rule is delimited by a semicolon (;) in the Bulk file
            new CombinationRule
            {
                AudienceIds = new [] { 123, 234 },
                Operator = LogicalOperator.And
            },
            new CombinationRule
            {
                AudienceIds = new [] { 345, 456 },
                Operator = LogicalOperator.And
            },
        },
        // 'Scope' column header in the Bulk file
        Scope = EntityScope.Account,
        // 'Audience Search Size' column header in the Bulk file
        SearchSize = null,
        // 'Supported Campaign Types' column header in the Bulk file
        SupportedCampaignTypes = null,
    },

    // 'Status' column header in the Bulk file
    Status = Status.Active
};

uploadEntities.Add(bulkCombinedList);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();

結合リスト レコードの場合、一括ファイルスキーマでは、次の属性フィールドを使用できます。

Audience
対象ユーザーのネットワークサイズ
対象ユーザーの検索サイズ
クライアント ID
組み合わせルール
説明
Id
変更時刻
Parent Id
スコープ
状態
サポートされているキャンペーンの種類

Audience

結合されたリストの名前。

名前には最大 128 文字を使用することができます。

追加： 必須
更新： オプション。更新プログラムに値が設定されていない場合、この設定は変更されません。
削除： 読み取り専用

対象ユーザーのネットワークサイズ

対象ユーザーネットワーク内のこの対象ユーザーのアクティブメンバーであるユーザーの合計数。これにより、対象となる対象ユーザーの数を把握できます。

Microsoft Advertising が最適化に使用する前に、対象ユーザーは少なくとも 300 人である必要があります。

追加： 読み取り専用
更新： 読み取り専用
削除： 読み取り専用

対象ユーザーの検索サイズ

検索ネットワーク内のこの対象ユーザーのアクティブメンバーであるユーザーの合計数。これにより、ターゲットにできる検索ユーザーの数を把握できます。

Microsoft Advertising が最適化に使用する前に、対象ユーザーは少なくとも 300 人である必要があります。

対象ユーザーが作成されている間、このプロパティは最大 24 時間空になります(たとえば、リストのメンバーシップ期間、ルール、タグ識別子を追加または更新する場合)。

結合されたリストに関連付けられている UET タグの状態が [未確認] または [非アクティブ] の場合、このプロパティは空になります。これは、組み合わされたリストが、リストの作成に必要な顧客情報を Web サイトから受信できないためです。

追加： 読み取り専用
更新： 読み取り専用
削除： 読み取り専用

クライアント ID

一括アップロードファイル内のレコードを結果ファイル内のレコードに関連付けるために使用されます。このフィールドの値は、サーバーによって使用または格納されません。アップロードされたレコードから対応する結果レコードにコピーされます。最大 100 の長さの任意の有効な文字列を指定できます。

追加： オプション
更新： オプション
削除： 読み取り専用

組み合わせルール

組み合わせルールには、組み合わせリストに追加するユーザーを決定するために使用される条件が含まれます。

カスタムオーディエンス、顧客リスト、製品の対象ユーザー、類似ユーザー、リマーケティングリストを組み合わせることができます。他の組み合わせリストや市場内オーディエンスを組み合わせたリストに含めることはできません。

広告アカウントごとに最大 1,000 個の組み合わせリストを作成でき、顧客ごとに最大 5,000 個のリストを作成できます。各リストの組み合わせルールには、最大 100 セットの論理条件を含めることができます。また、各セットには最大 100 個の対象ユーザー ID を含めることができます。

以下で説明するいくつかの制限により、これらの論理演算子を使用して対象ユーザーを結合できます。

または:これには、これらのいずれかの対象ユーザーリストに含まれる顧客が含まれます。
AND: これには、これらの対象ユーザーリストの 1 つ 1 つに含まれる顧客のみが含まれます。
NOT: これにより、これらのいずれかの対象ユーザーリストに含まれる顧客が除外されます。

論理条件セットは、OR、AND、または NOT のいずれかで修飾された対象ユーザー ID のグループを指します。 Bulk API では、各セットはアンパサンド ('&') で区切られます。

たとえば、1 つの組み合わせルールに対して 10 セットあり、それぞれ対象ユーザー ID が 1 つあり、それぞれ NOT (1)&AND(2)&OR(3)&NOT(4)&AND(5)&OR(6)&NOT(7)&AND(8)&OR(9)&NOT(10)

1 つの組み合わせルールに対して 10 セットの例を次に示します。 2 つの対象ユーザー ID を持つそれぞれ: NOT(1,101)&AND(2,102)&OR(3,103)&NOT(4,104)&AND(5,105))&OR(6,106)&NOT(7,107)&AND(8,108)&OR(9,109)&NOT(10,110)

論理式の評価によって、結合リストに追加されるユーザーが決まります。複数の組み合わせは、常に AND 関数と組み合わされます。つまり、このカスタムの組み合わせ対象ユーザーリストに表示するには、顧客が各組み合わせのすべての条件を満たす必要があります。たとえば、組み合わせルールが NOT(123,234)&NOT(345,456)&AND(567,678)&OR(789,890)&OR(987,876)に設定されたとします。組み合わせリストには、対象ユーザー 567 と 678 の両方に a) が含まれており、b) が対象ユーザー 789 または 890 のいずれかに含まれており、c) は対象ユーザー 987 または 876 のいずれかに含まれます(d) 顧客が対象ユーザー 123、234、345、または 456 のいずれかである場合を除きます。

結合リストには、OR 演算子または AND 演算子を使用する対象ユーザーが少なくとも 1 人含まれている必要があります。結合されたリストでは、NOT 演算子のみを使用することはできません。その場合は、代わりに対象ユーザーの除外を使用する必要があります。

カスタム対象ユーザーと顧客リストを他の対象ユーザーの種類と組み合わせることはできません。

AND 演算子または NOT 演算子を使用して類似の対象ユーザーを結合することはできません。同様の対象ユーザーは、1 つの OR 条件でのみ使用できます。つまり、類似する対象ユーザーを含む対象ユーザーセットは 1 つだけであり、そのセットでは OR 演算子を使用する必要があります。

重複する対象ユーザーは許可されますが、AND 演算子と NOT 演算子の両方を使用して同じ対象ユーザー ID を組み合わせることはできません。

同じ一括アップロードでこの結合リストと共に新しい対象ユーザーを作成する場合、組み合わせルールには、他の新しい対象ユーザーの Id フィールドと等しい負の識別子を含めることができます。たとえば、新しいリマーケティングリストを作成し、組み合わせたリストに含める場合は、リマーケティングリストの Id 値を -1 に設定できます。同じ一括アップロードでは、組み合わせルール (NOT(123,234)&AND(345,456)&OR(-1,678)など) で -1 を使用して新しいリマーケティングリストを参照できます。詳細については、「一括ファイルスキーマ参照キー」を参照してください。

同じ一括アップロードでこの結合リストと共に新しい対象ユーザーを作成する場合、組み合わせルールには、他の新しい対象ユーザーの負の Id フィールドに負の参照キーを含めることができます。また、他の新しい 対象ユーザーの [対象ユーザー (名前)] フィールドに論理参照キーを使用することもできます。

負の参照キーを使用する例として、同じ一括アップロードには、ID が-1 に設定されている新しいリマーケティングリストが含まれます。次に、組み合わせルールで -1 を使用した新しいリマーケティングリスト ( NOT(123,234)&AND(345,456)&OR(-1,678)) を参照してください。
論理参照キーを使用する例として、同じ一括アップロードに新しいリマーケティングリストが含まれます。このリストには、[ 対象ユーザー名] が [ マイニューオーディエンス] に設定されています。次に、組み合わせルール (NOT(123,234)&AND(345,456)&OR('My New Audience',678) など、"マイオーディエンス" (単一引用符で囲まれた) を使用して新しいリマーケティングリストを参照します。

詳細については、「一括ファイルスキーマ参照キー」を参照してください。

追加： 必須
更新： オプション。更新プログラムに値が設定されていない場合、この設定は変更されません。
削除： 読み取り専用

説明

結合されたリストの説明。説明を使用して、この組み合わせリストで対象としている対象ユーザーを思い出すのに役立ちます。

説明には、最大 1,024 文字を含めることができます。

追加： オプション
更新： オプション。更新プログラムに値が設定されていない場合、この設定は変更されません。このフィールドを delete_value 文字列に設定すると、前の設定は削除されます。
削除： 読み取り専用

Id

結合されたリストのシステム生成識別子。

追加： 読み取り専用
更新： 読み取り専用と必須
削除： 読み取り専用と必須

変更時刻

エンティティが最後に更新された日付と時刻。値は、世界協定時刻 (UTC) です。

注:

日付と時刻の値は、クライアントではなく、サーバーでの日付と時刻を反映します。日付と時刻の形式については、「プリミティブ XML データ型」の dateTime エントリを参照してください。

追加： 読み取り専用
更新： 読み取り専用
削除： 読み取り専用

Parent Id

アカウントまたは顧客のシステム生成識別子。 [スコープ] が [アカウント] に設定されている場合、これはアカウント ID、それ以外の場合は顧客 ID です。

追加： オプション
更新： 読み取り専用。親 ID は変更できません。
削除： 読み取り専用

範囲

スコープは、この組み合わせリストを使用できるアカウントを定義します。スコープが [アカウント] に設定されている場合、結合されたリストは、指定した 1 つのアカウント (親 ID) 内のキャンペーンと広告グループにのみ関連付けることができます。スコープが [顧客] に設定されている場合、組み合わせた一覧は、顧客のすべてのアカウントのキャンペーンと広告グループに関連付けることができます。

追加： 必須
更新： 読み取り専用。スコープを変更することはできません。
削除： 読み取り専用

状態

結合されたリストの状態。

使用可能な値は [アクティブ] または [削除済み] です。

追加： オプション。既定値は [アクティブ] です。
更新： 読み取り専用
削除： 必須。 [状態] を [削除済み] に設定する必要があります。

サポートされているキャンペーンの種類

この組み合わせリストをサポートするキャンペーンタイプのセミコロン区切りリスト。

サポートされる値は、対象ユーザー、DynamicSearchAds、検索、ショッピングです。今後、新しいキャンペーンの種類が追加される可能性があるため、固定の値セットに依存しないようにしてください。

追加： 読み取り専用
更新： 読み取り専用
削除： 読み取り専用

次の方法で共有

結合リストレコード - 一括

Audience

対象ユーザーのネットワークサイズ

対象ユーザーの検索サイズ

クライアント ID

組み合わせルール

説明

Id

変更時刻

Parent Id

範囲

状態

サポートされているキャンペーンの種類

その他のリソース

次の方法で共有

結合リスト レコード - 一括

Audience

対象ユーザーのネットワーク サイズ

対象ユーザーの検索サイズ

クライアント ID

組み合わせルール

説明

Id

変更時刻

Parent Id

範囲

状態

サポートされているキャンペーンの種類

その他のリソース

結合リストレコード - 一括

対象ユーザーのネットワークサイズ