広告を管理するためのスクリプトの例

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

次のセクションでは、広告に対してさまざまなアクションを実行するスクリプトの例を示します。

注:

拡張テキスト広告を、2023 年 2 月 1 日までにレスポンシブ検索広告にアップグレードします。この日付を過ぎると、新しいテキスト広告を作成したり、既存の拡張テキスト広告を編集したりできなくなります。詳細については、「レスポンシブ検索広告について」を参照してください。
既存の拡張テキスト広告は引き続き配信され、そのパフォーマンスに関するレポートを表示できます。
拡張テキスト広告は引き続き一時停止、有効化、または削除できます。そうしないと、拡張テキスト広告を追加または更新しようとすると、エラーが発生 CampaignServiceAdTypeInvalid します。
この変更の詳細については、こちらをご覧ください。

広告を追加する

広告を追加するには、まず広告を追加する広告グループを取得します。 AdGroupSelector オブジェクトを使用して、広告グループを選択します。メソッドを使用すると、 withIds メソッドで広告グループの名前を渡すよりもパフォーマンスが withCondition 向上します。

次に、広告グループの newAd メソッドを呼び出して、広告のプロパティを指定するために使用するビルダーを取得します。他のエンティティ型とは異なり、メソッドは newAd 、作成する広告の種類のビルダーを取得するためのメソッドを含む AdBuilderSpace オブジェクトを返します。次の使用例は、展開されたテキスト広告を追加するため、メソッドを expandedTextAdBuilder 呼び出して拡張テキスト広告ビルダーを取得します。

拡張テキスト広告の場合は、次のプロパティを指定する必要があります。

説明
FinalUrl
HeadlinePart1
HeadlinePart2

これらのプロパティの組み合わせは、拡張テキスト広告を一意に定義します。その他のプロパティは省略可能です。

ビルダー build のメソッドを呼び出すと、広告が非同期的に作成されます。スクリプトは、スクリプトが終了する前、またはビルド操作のいずれかのメソッドを呼び出す場合に、ある時点で広告を追加します。このプロセスの詳細については、「ビルダーとは」を参照してください。

function main() {
    var adGroupId = "AD GROUP ID GOES HERE";
    var adGroup = getAdGroup(adGroupId);

    if (adGroup != null) {

        // Get an expanded text ad builder, specify the ad's 
        // properties, and add the ad to the build queue.
        var operation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("AD COPY GOES HERE")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("AD TITLE PART 1 GOES HERE")
            .withHeadlinePart2("AD TITLE PART 2 GOES HERE")
            .build();

        if (!operation.isSuccessful()) {
            for (var error of operation.getErrors()) {
                Logger.log(error);
            }
        }
    }
    else {
        Logger.log(`Failed to get ad group, ${adGroupId}.`);
    }
}

function getAdGroup(id) {
    var adGroups = AdsApp.adGroups()
        .withIds([id])
        .get();

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

必要なフィールドの組み合わせに同じ値を持つ以前に追加された広告が存在する場合、サービスは広告を追加せず、以前に追加した広告と ID を返します。ただし、同じ広告が同じビルドキューで処理された場合、2 番目の広告は CampaignServiceDuplicateAd で失敗します。たとえば、次の例の広告は同じであるため、そのうちの 1 つが失敗します。

    if (adGroup != null) {
        var adOperation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("ad copy")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("title part 1")
            .withHeadlinePart2("title part 2")
            .build();

        operations.push(adOperation);

        adOperation = adGroup.newAd().expandedTextAdBuilder()
            .withDescription("ad copy")
            .withFinalUrl("https://contoso.com")
            .withHeadlinePart1("title part 1")
            .withHeadlinePart2("title part 2")
            .build();

        operations.push(adOperation);
        
        for (var operation of operations) {
            if (!operation.isSuccessful()) {
                for (var error of operation.getErrors()) {
                    Logger.log(error);
                }
            }
        }
    }

広告を取得する

階層内の場所に応じて、広告を取得するためのオプションがいくつかあります。

広告グループから広告を取得する

AdGroup オブジェクトがある場合は、オブジェクトのadsメソッドを呼び出して、広告グループに属する広告の一覧を取得します。次の使用例は、グループ内のすべての広告を取得して印刷しますが、広告セレクターの方法を使用して広告の一覧をフィルター処理できます。

function main() {
    var adGroups = AdsApp.adGroups()
        .withIds(["AD GROUP ID GOES HERE"])
        .get();

    if (adGroups.hasNext()) {
        var adGroup = adGroups.next();

        var ads = adGroup.ads().get();
        
        while (ads.hasNext()) {
            var ad = ads.next();

            if (ad.isType().expandedTextAd()) {
                var expandedAd = ad.asType().expandedTextAd();
            }
        }
    } 
}

キャンペーンから広告を取得する

Campaign オブジェクトがある場合は、オブジェクトのadsメソッドを呼び出して、キャンペーン内の広告グループに属する広告の一覧を取得します。この例では、広告セレクターの withCondition メソッドを使用して、foo という名前の広告グループ内の広告リストをフィルター処理します。

function main() {
    var campaigns = AdsApp.campaigns()
        .withIds(["CAMPAIGN ID GOES HERE"])
        .get();

    while (campaigns.hasNext()) {
        var campaign = campaigns.next();

        var ads = campaign.ads()
            .withCondition("AdGroupName CONTAINS_IGNORE_CASE 'foo'")
            .get();
        
        while (ads.hasNext()) {
            var ad = ads.next();

            if (ad.isType().expandedTextAd()) {
                var expandedAd = ad.asType().expandedTextAd();
            }
        }
    } 
}

アカウント内のすべての広告を取得する

アカウント内のすべての広告を取得するには、AdsApp オブジェクトで ads メソッドを呼び出します。広告セレクターの方法を使用して、キャンペーン、広告グループ、または広告のパフォーマンスに基づいて広告の一覧をフィルター処理できます。この例では、アカウントからすべての広告を取得します。

function main() {
    var ads = AdsApp.ads().get();

    while (ads.hasNext()) {
        var ad = ads.next();

        if (ad.isType().expandedTextAd()) {
            var expandedAd = ad.asType().expandedTextAd();
        }
    }
}

広告を一時停止する

広告を一時停止するには、広告の pause メソッドを呼び出します。 pauseメソッドは基本 Ad オブジェクト上にあるため、最初に派生オブジェクトを取得する必要はありません。

広告を有効または削除する場合は、広告の enable または remove メソッドを呼び出します。広告が有効または一時停止されているかどうかを確認するには、メソッドまたは isPaused メソッドをisEnabled呼び出します。

特定の状態の広告を取得するには、広告セレクターの withCondition 方法を使用します。たとえば、「 withCondition("Status = PAUSED) 」のように入力します。

function main() {
    var ads = AdsApp.ads()
        .forDateRange("LAST_WEEK")
        .withCondition("AdGroupName CONTAINS_IGNORE_CASE 'foo'")
        .withCondition('Status = ENABLED')
        .withCondition('Clicks < 5')
        .get();
 
    while (ads.hasNext()) {
        var ad = ads.next();
        ad.pause();
    }
}

不承認の広告を受け取る

不承認の広告を取得する例については、「不承認の広告の検出」を参照してください。

Share via