KeywordSelector

キーワードのリストをフィルタリングおよび並べ替えるためのメソッドが含まれています。 セレクターの詳細については、「 セレクター」を参照してください。

使用例:

    var iterator = AdsApp.keywords()
        .withCondition("AdGroupName = 'AD GROUP NAME GOES HERE'")
        .withCondition("CampaignName = 'CAMPAIGN NAME GOES HERE'")
        .get();

    while (iterator.hasNext()) {
        var keyword = iterator.next();
    }

メソッド

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

forDateRange(Object dateFrom, Object dateTo)

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

以下の場合にのみ日付範囲を指定します。

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

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

  • year
  • month
  • day

例:

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

月は 1 ベースで、1 は 1 月、12 は 12 月です。

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

引数

名前 型 説明
dateFrom オブジェクト セレクターに含めるパフォーマンス データを指定する日付範囲の開始日。
dateTo オブジェクト セレクターに含めるパフォーマンス データを指定する日付範囲の終了日。

戻り値

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

forDateRange(String dateRange)

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

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

  • TODAY
  • 昨日
  • 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

以下の場合にのみ日付範囲を指定します。

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

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

引数

名前 型 説明
dateRange 文字列 セレクターに含めるパフォーマンス データを指定する定義済みの日付範囲文字列。 定義済みの日付範囲の文字列では、大文字と小文字が区別されます。

戻り値

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

get

キーワードのリストを反復処理するために使用される 反復子 を取得します。

戻り値

型 説明
KeywordIterator 選択したキーワードを反復処理するために使用される反復子。

orderBy(string, orderBy)

選択したキーワードに、指定した順序を適用します。

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

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

たとえば、次の呼び出しは、AverageCpc の昇順の結果を返します。

selector = selector.orderBy("AverageCpc");

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

引数

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

戻り値

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

withCondition(String condition)

キーワードにフィルター条件を適用します。

条件パラメーターを "columnName operator value" の形式で指定します。

演算子

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

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

<
<=
>
>=
=
!=

double 型の値を含む列の演算子:

<
>

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

=
!=
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

キーワード (keyword) フィルタリングでサポートされている列。 列名は大文字と小文字を区別します。

指定可能なパフォーマンス メトリック列を次に示します。

列 型 例 Microsoft Advertising Web UI フィルター
AbsoluteTopImpressionRate double withCondition("AbsoluteTopImpressionRate > 0.25") Abs. Top Impr. Rate
AverageCpc double withCondition("AverageCpc < 2.75") 平均 CPC (クリック単価)
AverageCpm double withCondition("AverageCpm > 0.65") 平均 CPM (インプレッション単価)
ClickConversionRate double withCondition("ClickConversionRate > 0.25") コンバージョン率
クリック数 long withCondition("Clicks >= 33") クリック数
ConvertedClicks long withCondition("ConvertedClicks >= 10") Conv.
コスト double withCondition("Cost > 3.25")

コストはアカウントの通貨で計算されます。		 支出
Ctr double withCondition("Ctr > 0.05")

CTR は 0..1 の範囲なので、CTR が 5% の場合は 0.05 を使用します。		 CTR
インプレッション long withCondition("Impressions > 10") Impr.
TopImpressionRate double withCondition("TopImpressionRate > 0.25") トップ Impr. Rate

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

列 型 例 Microsoft Advertising Web UI フィルター
状態 列挙型 キーワード (keyword) のステータス。 大文字と小文字を区別できる値は次のとおりです。
  • 有効
  • 一時停止中
  • 削除済み
withCondition("Status = ENABLED")		 状態
CombinedApprovalStatus string キーワード (keyword) の承認状態。 大文字と小文字を区別できる値は次のとおりです。
  • APPROVED
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • 不承認
これらの値の詳細については、「 編集承認状態の値」を参照してください。

この例では、注意が必要なキーワードが返されます。

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
テキスト string キーワード (keyword) のテキスト。 キーワード (keyword) のテキストのみを含めます。 テキストに キーワード (keyword) のマッチング タイプを含めないでください。 たとえば、キーワード (keyword) が [books] などの完全一致キーワード (keyword) の場合は、[books] ではなく books を使用してください。

withCondition("Text STARTS_WITH 'flowers'")		 キーワード テキスト
KeywordMatchType 列挙型 キーワード (keyword)のマッチタイプ。 大文字と小文字を区別できる値は次のとおりです。
  • BROAD
  • EXACT
  • PHRASE
withCondition("KeywordMatchType = EXACT")		 照合する種類
MaxCpc double キーワード (keyword) の上限 CPC 入札額。 CPC はアカウントの通貨で表示されます。

withCondition("MaxCpc > 0.40")		 Bid
DestinationUrl string withCondition("DestinationUrl STARTS_WITH 'http://www.contoso.com'") リンク先 URL
FinalUrls string withCondition("FinalUrls CONTAINS 'http://www.contoso.com'")
QualityScore int withCondition("QualityScore > 5") Qual. score
FirstPageCpc double 広告がサイドバーに表示されたときにクリックされるたびに広告主に請求される平均金額。 たとえば、広告主が 300 回のクリックに対して合計 48.35 ドルを支払った場合、広告主の平均 CPC は 0.16 ドルです。 この情報は、広告がサイドバーに表示される可能性を高めるために、キーワード (keyword) の入札単価を引き上げるかどうかを決定するのに役立ちます。 CPC はアカウントの通貨で表示されます。

withCondition("FirstPageCpc > 6.00")		 見積もり 1 ページ目の入札単価
TopOfPageCpc double オーガニック検索結果の上に広告が表示されたときに、広告がクリックされるたびに広告主に請求される平均金額。 たとえば、広告主が 300 回のクリックに対して合計 48.35 ドルを支払った場合、広告主の平均 CPC は 0.16 ドルです。 この情報は、オーガニック検索結果上に広告が表示される可能性を高めるために、キーワード (keyword) の入札単価を引き上げるかどうかを決定するのに役立ちます。 CPC は当座預金口座の通貨です。

withCondition("TopOfPageCpc > 8.00")		 最適な位置
AdGroupName string キーワードを含む広告グループの名前。

withCondition("AdGroupName = 'foo'")
AdGroupStatus 列挙型 広告グループのステータス。 大文字と小文字を区別できる値は次のとおりです。
  • 有効
  • 一時停止中
  • 削除済み
withCondition("AdGroupStatus = ENABLED")
CampaignName string キーワードを含むキャンペーンの名前。

withCondition("CampaignName = 'bar'")
CampaignStatus 列挙型 キャンペーンの状態。 大文字と小文字を区別できる値は次のとおりです。
  • 有効
  • 一時停止中
  • 削除済み
withCondition("CampaignStatus = ENABLED")
LabelNames 文字列セット 大文字と小文字が区別される 1 つ以上のラベル名の一覧。 名前付きラベルに関連付けられているキーワードを取得するために使用します。

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
ID Long テストするキーワード (keyword)の ID。 たとえば、この列を使用して、指定した ID より大きな ID を持つキーワードをチェックできます。

withCondition('Id > 1234')

引数

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

戻り値

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

withIds(string[], ids)

指定した ID のキーワードを取得します。

1 つのセレクターに 1 つ以上の条件を適用できます。 条件のチェーンは、AND 演算と見なされます。 たとえば、条件 A が True かつ条件 B が True の場合にのみエンティティが選択されます。 たとえば、次の呼び出しでは、33333 キーワード (keyword)だけが選択されます。

AdsApp.keywords()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);

引数

名前 型 説明
ids string[] キーワード (keyword) ID の配列。 制限については、「 スクリプト実行制限」を参照してください。

戻り値

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

withLimit(int limit)

選択条件に一致する上位 n 個のキーワードを取得します。

引数

名前 型 説明
limit int 返されるキーワードの数。 実際の数は少ない場合があります。

戻り値

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

関連項目

  • 最終更新: