AdGroupAudienceSelector

[アーティクル]
11/13/2024

広告グループの対象ユーザーのリストをフィルター処理および並べ替える方法が含まれます。セレクターの詳細については、「セレクター」を参照してください。

使用例:

    // Gets the iterator that iterates all ad group audiences
    // in the account.
    var iterator = AdsApp.adGroups().get();

    // Loops through all ad groups in the account.
    while (iterator.hasNext()) {
        var adGroup = iterator.next();

        // Gets the iterator that iterates all ad group audiences
        // in the ad group audience.
        var audienceIterator = adGroup.targeting().audiences()
            .withLimit(10)
            .withIds("123456789")
            .get();
    
        // Loops through all ad group audiences in the ad group audience.
        while (audienceIterator.hasNext()) {
            var audience = iterator.next();
        }
    }

メソッド

メソッド名	戻り値の型	説明
forDateRange(Object dateFrom, Object dateTo)	AdGroupAudienceSelector	パフォーマンスメトリックを選択するための開始日と終了日を適用します。
forDateRange(string dateRange)	AdGroupAudienceSelector	パフォーマンスメトリックを選択するための定義済みの日付範囲を適用します。
get	AdGroupAudienceIterator	広告グループの対象ユーザーの一覧を反復処理するために使用される反復子を取得します。
orderBy(string orderBy)	AdGroupAudienceSelector	選択した広告グループの対象ユーザーに指定した順序を適用します。
withCondition(string condition)	AdGroupAudienceSelector	広告グループの対象ユーザーにフィルター条件を適用します。
withIds(string[] ids)	AdGroupAudienceSelector	指定した ID を持つ広告グループの対象ユーザーを取得します。
withLimit(int limit)	AdGroupAudienceSelector	選択条件に一致する上位 n 個の広告グループの対象ユーザーを取得します。

forDateRange(Object dateFrom, Object dateTo)

パフォーマンスメトリックを選択するための開始日と終了日を適用します。

日付範囲は、次の場合にのみ指定します。

パフォーマンスメトリックフィールドを参照する条件または順序を適用します。
選択しているオブジェクトのパフォーマンスデータを取得する必要があります。たとえば、メソッドを呼び出す予定の getStats() 場合です。

日付パラメーターは、文字列またはオブジェクトを使用して指定できます。文字列を使用するには、YYYYMMDD という形式で日付を指定します。オブジェクトを使用する場合は、次のフィールドを含むオブジェクトを作成します。

year
month
日

例:

var date = {year: 2018, month: 5, day: 13};

月は 1 から始まります。1 は 1 月、12 日は 12 月です。

日付範囲は包括的です。複数の日付範囲を指定した場合は、最後の日付範囲のみが使用されます。

引数

名前	型	説明
dateFrom	オブジェクト	セレクターに含めるパフォーマンスデータを指定する日付範囲の開始日。フォームの文字列、YYYYMMDD、またはフォームのオブジェクト {year: 2020、month: 12、day: 31} を使用して日付を指定します。
dateTo	オブジェクト	セレクターに含めるパフォーマンスデータを指定する日付範囲の終了日。フォームの文字列、YYYYMMDD、またはフォームのオブジェクト {year: 2020、month: 12、day: 1} を使用して日付を指定します。

戻り値

型	説明
AdGroupAudienceSelector	日付範囲が適用されたセレクター。

forDateRange(String dateRange)

パフォーマンスメトリックを選択するための定義済みの日付範囲を適用します。

日付範囲は、次の場合にのみ指定します。

パフォーマンスメトリックフィールドを参照する条件または順序を適用します。
選択しているオブジェクトのパフォーマンスデータを取得する必要があります。たとえば、メソッドを呼び出す予定の getStats() 場合です。

複数の日付範囲を指定した場合は、最後の日付範囲のみが使用されます。

サポートされている日付範囲の値:

本日は
昨日
LAST_WEEK
LAST_BUSINESS_WEEK
LAST_7_DAYS
THIS_WEEK_SUN_TODAY
LAST_14_DAYS
LAST_30_DAYS
LAST_WEEK_SUN_SAT
THIS_MONTH
LAST_MONTH
ALL_TIME

引数

名前	型	説明
dateRange	String	セレクターに含めるパフォーマンスデータを指定する定義済みの日付範囲文字列。定義済みの日付範囲文字列では、大文字と小文字が区別されます。大文字と小文字を区別する値は、TODAY、YESTERDAY、LAST_WEEK、LAST_BUSINESS_WEEK、LAST_7_DAYS、THIS_WEEK_SUN_TODAY、LAST_14_DAYS、LAST_30_DAYS、LAST_WEEK_SUN_SAT、THIS_MONTH、LAST_MONTH、ALL_TIMEです。

戻り値

型	説明
AdGroupAudienceSelector	日付範囲が適用されたセレクター。

取得

広告グループの対象ユーザーの一覧を反復処理するために使用される反復子を取得します。

戻り値

型	説明
AdGroupAudienceIterator	選択した広告グループの対象ユーザーを反復処理するために使用される反復子。

orderBy(String orderBy)

選択した広告グループの対象ユーザーに指定した順序を適用します。

"columnName orderDirection" という形式で orderBy パラメーターを指定します。

columnName は、サポートされている列の 1 つです。
orderDirection は、結果を並べ替える順序です。結果を昇順に並べ替える場合は ASC に、結果を降順に並べ替える場合は DESC に設定します。既定値は ASC です。

たとえば、次の呼び出しでは、広告グループの対象ユーザーが AverageCpc の昇順で返されます。

selector = selector.orderBy("AverageCpc");

セレクターでは、1 つのフィールドによるエンティティの並べ替えのみがサポートされます。フィールド x、x 内のエンティティの一覧をフィールド y ごとに並べ替えすることはできません。チェーンまたは個別のセレクター呼び出しで複数 orderBy() の呼び出しを指定した場合、スクリプトは最後 orderBy() の呼び出しで指定されたフィールドを使用してエンティティの一覧を並べ替えます。

引数

名前	型	説明
Orderby	string	適用する順序。

戻り値

型	説明
AdGroupAudienceSelector	順序付けが適用されたセレクター。

withCondition(String condition)

広告グループの対象ユーザーにフィルター条件を適用します。

"columnName 演算子値" という形式で condition パラメーターを指定します。

columnName は、サポートされている列の 1 つです。 columName がパフォーマンスメトリック列名に設定されている場合は、forDateRange(String dateRange) または forDateRange(Object dateFrom, Object dateTo) を使用して日付範囲を指定する必要があります。
operator は、サポートされている演算子の 1 つです。

演算子

使用する演算子は、列の型によって異なります。演算子では大文字と小文字が区別されます。たとえば、starts_withの代わりに STARTS_WITH を使用します。

整数と長い値を含む列の演算子:

<
<=
>
>=
=
!=

二重値を含む列の演算子:

<
>

文字列値を含む列の演算子:

=
!=
STARTS_WITH
STARTS_WITH_IGNORE_CASE
CONTAINS
CONTAINS_IGNORE_CASE
DOES_NOT_CONTAIN
DOES_NOT_CONTAIN_IGNORE_CASE

列挙値を含む列の演算子:

=
!=
IN []
NOT_IN []

文字列の配列を含む列の演算子:

CONTAINS_ALL
CONTAINS_ANY
CONTAINS_NONE

サポートされる列

広告グループの対象ユーザーフィルター処理でサポートされている列。名前では大文字と小文字が区別されます。

指定できるパフォーマンスメトリック列を次に示します。

Column	型	例
AbsoluteTopImpressionRate	double	`withCondition("AbsoluteTopImpressionRate > 0.25")`
AverageCpc	double	`withCondition("AverageCpc < 2.75")`
AverageCpm	double	`withCondition("AverageCpm > 0.65")`
ClickConversionRate	double	`withCondition("ClickConversionRate > 0.25")`
クリック	long	`withCondition("Clicks >= 33")`
ConvertedClicks	long	`withCondition("ConvertedClicks >= 10")`
コスト	double	`withCondition("Cost > 3.25")` コストは、アカウントの通貨で行われます。
Ctr	double	`withCondition("Ctr > 0.05")` CTR は範囲 0...1 であるため、5% の CTR には 0.05 を使用します。
インプレッション	long	`withCondition("Impressions > 10")`
TopImpressionRate	double	`withCondition("TopImpressionRate > 0.25")`

指定できるエンティティプロパティを次に示します。

Column	型	例
AdGroupName	文字列	関連付けの広告グループの名前。 `withCondition("AdGroupName CONTAINS_IGNORE_CASE 'truck'")`
AdGroupStatus	列挙	関連付けの広告グループの状態。大文字と小文字を区別する値は次のとおりです。有効一時停止削除次の使用例は、親広告グループが一時停止されている広告グループの対象ユーザーのみを返します。 `withCondition("AdGroupStatus = PAUSED")`
AudienceId	long	関連付けられている対象ユーザーの ID。 `withCondition("AudienceId = 123456789")`
CampaignName	string	関連付けの広告グループを含むキャンペーンの名前。 `withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")`
CampaignStatus	列挙	関連付けの広告グループを含むキャンペーンの状態。大文字と小文字を区別する値は次のとおりです。有効一時停止削除次の使用例は、親キャンペーンが一時停止されている広告グループの対象ユーザーのみを返します。 `withCondition("CampaignStatus = PAUSED")`
状態	列挙	関連付けの状態。大文字と小文字を区別する値は次のとおりです。有効一時停止削除この例では、有効な広告グループの対象ユーザーのみを返します。 `withCondition("Status = ENABLED")`
UserListName	string	関連付けられている対象ユーザーの名前。 `withCondition("UserListName = 'foo'")`

引数

名前	型	説明
condition	string	セレクターに適用する条件。

戻り値

型	説明
AdGroupAudienceSelector	条件が適用されたセレクター。

withIds(string[] ids)

指定した ID を持つ広告グループの対象ユーザーを取得します。

セレクターに 1 つ以上の条件を適用できます。条件のチェーンは AND 演算と見なされます。たとえば、条件 A が true の場合にのみエンティティが選択され、条件 B が true です。たとえば、次の通話では、広告グループの対象ユーザー 33333 のみが選択されます。

var selector = AdsApp.adGroups()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);

引数

名前	型	説明
ids	string[]	広告グループの対象ユーザー ID の配列。制限については、「スクリプトの実行制限」を参照してください。

戻り値

型	説明
AdGroupAudienceSelector	ID が適用されたセレクター。

withLimit(int limit)

選択条件に一致する上位 n 個の広告グループの対象ユーザーを取得します。

引数

名前	型	説明
limit	int	返す広告グループの対象ユーザーの数。実際の数値が小さい場合があります。

戻り値

型	説明
AdGroupAudienceSelector	制限が適用されたセレクター。

次の方法で共有