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

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

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

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

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

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

ただし、特定のエンティティまたはエンティティのサブセットが必要な場合はどうなりますか?

セレクターには、エンティティの一覧をフィルター処理するためのさまざまな方法が用意されています。セレクターのメソッドを使用して ID によって特定の withIds() エンティティを取得したり、エンティティを選択するための選択条件を指定したりすることもできます withCondition() 。負のキーワードリストを除くすべてのエンティティ型のセレクターは、エンティティの一覧をフィルター処理する機能を提供します。

ドット表記を使用して、複数のフィルターを一緒に文字列化します。複数のフィルターを指定した場合、これらは 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() メソッドを呼び出します。

builder オブジェクトには、指定できるオブジェクトのすべてのプロパティを設定するためのメソッドが含まれています。エンティティの作成に 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`);
        }
    }

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

エンティティ操作方法更新しますか?

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

    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;
    }    
}

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

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

次の手順

はじめに

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