広告管理のスクリプト例

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

注:

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

広告の追加

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

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

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

  • 説明
  • FinalUrl
  • HeadlinePart1
  • ヘッドラインパート2

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

ビルダーの 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 メソッドを呼び出すだけです。 広告が有効か一時停止かチェックするには、isEnabled メソッドまたは isPaused メソッドを呼び出します。

特定のステータスの広告を取得するには、広告セレクターの 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();
    }
}

不承認の広告を取得する

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

  • Last updated on