シングルアカウントアクセス

1 つのユーザーアカウントにアクセスする場合は、すべてが AdsApp オブジェクトから始まります。

アカウント内のエンティティにアクセスする操作方法

AdsApp を使用して、アカウント内のすべてのエンティティにアクセスします。オブジェクトには、エンティティの種類 (キャンペーン、広告グループ、キーワードなど) ごとにセレクターメソッドが含まれます。セレクターメソッドは、そのエンティティ型のすべてのエンティティを返します。たとえば、アカウント内のすべての広告グループを取得するには、 adGroups() メソッドを呼び出します。

    var iterator = AdsApp.adGroups().get();

しかし、特定のエンティティまたはエンティティのサブセットが必要な場合はどうすればよいでしょうか?

セレクターは、エンティティのリストをフィルター処理するさまざまな方法を提供します。セレクターの withIds() メソッドを使用して、ID で特定のエンティティを取得するか、 withCondition() を使用してエンティティを選択するための選択条件を指定できます。除外キーワード (keyword) リストを除くすべてのエンティティ型のセレクターは、エンティティのリストをフィルター処理する機能を提供します。

ドット表記を使用して、複数のフィルターをまとめます。複数のフィルターを指定した場合、それらは AND 演算として扱われ、すべての条件に一致するエンティティのみがセレクターによって返されます。

キャンペーン内のすべての広告グループを取得するには、 withCondition() メソッドを使用してキャンペーンの名前を指定します。

    var campaignName = 'My Campaign';
    var iterator = AdsApp.adGroups()
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

エンティティのリストをフィルター処理するために使用できる条件と演算子の一覧については、セレクターの withCondition() 方法を参照してください。たとえば、広告グループの条件の一覧については、広告グループセレクターの withCondition メソッドを参照してください。

ID で広告グループを取得するには、 withIds() メソッドを使用して取得する広告グループを指定します。

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

または、広告グループを名前で取得できます。

    var campaignName = 'My Campaign';
    var adGroupName = 'My AdGroup';
    var iterator = AdsApp.adGroups()
        .withCondition(`CampaignName = '${campaignName}'`)
        .withCondition(`Name = '${adGroupName}'`)
        .get();

セレクターの詳細については、「セレクターとは」を参照してください。

セレクターを使用して、フィルター処理されたエンティティリストを反復処理する操作方法

そうではありません。セレクターは取得するエンティティを定義するだけです。実際にエンティティを取得するには、イテレータを使用します。反復子を取得するには、セレクターの get() メソッドを呼び出します。

    var ids = ["123456789"];
    var iterator = AdsApp.adGroups()
        .withIds(ids)
        .get();

単純な while ループを使用して、エンティティのリストを反復処理します。

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        
        // Do something with the entity
    }

イテレータの詳細については、「イテレータとは」を参照してください。

エンティティのパフォーマンスデータを取得する操作方法

ほとんどのエンティティでは、パフォーマンスデータを要求できます (使用可能な場合)。ただし、セレクターを指定するときに、最初にパフォーマンスデータの日付範囲をスクリプトに指定する必要があります。日付範囲を指定するには、YESTERDAY や LAST_MONTH などの定義済みリテラルを使用するか、開始日と終了日を使用します。詳細については、 forDateRange(string dateRange) および forDateRange(Object dateFrom, Object dateTo) を参照してください。

    var campaignName = 'My Campaign';
    var adGroupName = 'My AdGroup';
    var iterator = AdsApp.adGroups()
        .forDateRange('LAST_30_DAYS')
        .withCondition(`CampaignName = '${campaignName}'`)
        .withCondition(`Name = '${adGroupName}'`)
        .get();

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        var stats = adGroup.getStats();
    }

また、セレクターの withCondition() 方法でパフォーマンスデータ列を指定する場合も、日付範囲を指定する必要があります。たとえば、CTR が .22% を超える広告グループのみを表示する場合は、期間を指定する必要があります。

    var startDate = {year: 2018, month: 6, day: 3};
    var endDate = {year: 2018, month: 6, day: 13};

    var iterator = AdsApp.adGroups()
        .forDateRange(startDate, endDate)
        .withCondition("Ctr > 0.22")
        .get();

エンティティを追加する操作方法

エンティティを追加するには、ビルダーオブジェクトを使用します。ビルダーオブジェクトを取得するには、子を追加する親オブジェクトで new* メソッドを呼び出します。たとえば、キャンペーンに広告グループを追加するには、キャンペーンの newAdGroupBuilder() メソッドを呼び出します。

ビルダーオブジェクトには、指定が許可されているオブジェクトのすべてのプロパティを設定するためのメソッドが含まれています。また、エンティティの作成に使用する build() メソッドも含まれます。次に、広告グループを作成する方法を示します。 (キャンペーンオブジェクトを取得する方法の詳細については、「名前でキャンペーンを取得する」を参照してください。)

        var adGroupName = "My ad group";
        var endDate = {year: 2018, month: 6, day: 13};
        var customParameters = {key1: 'value1', key2: 'value2', key3: 'value3'};

        var adGroupOperation = campaign.newAdGroupBuilder()
            .withName(adGroupName)
            .withStatus('ENABLED')
            .withLanguage('English')
            .withBiddingStrategy('MANUAL_CPC')
            .withCpc(1.2)
            .withCustomParameters(customParameters)
            .withEndDate(endDate)
            .build();

build メソッドは操作オブジェクトを返します。これチェックを使用して、スクリプトによってエンティティが正常に作成されたかどうかを確認できます。一般的な呼び出しパターンを次に示します。新しいエンティティのプロパティにアクセスする場合にのみ、 getResult メソッドを呼び出します。

    if (adGroupOperation.isSuccessful()) {
        var adGroup = adGroupOperation.getResult();

    }
    else {
        for (var error of adGroupOperation.getErrors()) {
            Logger.log(`${error}\n`);
        }
    }

操作メソッドを呼び出す際のビルダーとパフォーマンスに関する考慮事項の詳細については、「ビルダーとは」を参照してください。

エンティティを更新する操作方法

ビルダーオブジェクトを使用してエンティティを追加した後、エンティティのメソッドを使用してそのプロパティを更新します。次の例では、広告グループの CPC 入札額を更新しています。

    var ids = ["123456789"];
    var adGroups = AdsApp.adGroups()
        .withIds(ids)
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();
        adGroup.bidding().setCpc(2.5);
    }

しかし、更新プログラムが機能したかどうかは、どうすればわかりますか?

無効な値を持つプロパティを更新しようとすると、スクリプトは変更ログにエラーを書き込みますが、例外をスローしないため、スクリプトは引き続き実行されます。プロパティに新しい値が含まれているかどうかをチェックするために、プロパティを更新した後にプロパティを取得しないでください。これを行うと、パフォーマンスに悪影響を及ぼします。

function main() {
    var id = "123456789";
    var bidAmount = -2.5;  
    var keyword = getKeyword(id); 

    if (keyword != null) {
        keyword.bidding().setCpc(bidAmount);  // Bid is not set because bid amount is not valid
    }

}

function getKeyword(id) {
    var keywords = AdsApp.keywords()
        .withIds([id])
        .get();

    if (keywords.hasNext()) {
        return keywords.next();
    }
    else {
        return null;
    }    
}

ログファイルへの書き込み

スクリプトには、トレース情報とデバッグ情報を書き込むためのログファイルが用意されています。詳細については、「変更ログとテキストログ」を参照してください。

次の手順

はじめに

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-11