キーワードを管理するためのスクリプト例

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

キーワードの追加

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

次に、広告グループの newKeywordBuilder メソッドを呼び出して、キーワード (keyword)のプロパティの指定に使用するビルダーを取得します。指定する必要がある唯一のプロパティは、キーワード (keyword)のテキストです (withText メソッドを参照してください)。テキストには一致の種類を含める必要があります (フレーズ一致の種類の場合は引用符、完全一致の種類の場合は角かっこ、広範な一致の種類の場合は何もありません)。

CPC 値を指定しない場合は、デフォルトで広告グループの CPC 値が使用されます。デフォルトでは、キーワード (keyword) のステータスは [有効] です。

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

function main() {
    // The ID of the ad group to add the keywords to.
    // IDs in Scripts are string integers.
    var adGroupId = 'AD GROUP ID GOES HERE';  
    var adGroup = getAdGroup(adGroupId);

    // Keywords to add. Update as appropriate.
    var keywords = [];
    keywords.push({
        text : "keyword 1",
        cpc : 1.25,
        finalUrl : 'http://www.example.com'
    });
    keywords.push({
        text : "keyword 2",
        cpc : 1.5,
        finalUrl : 'http://www.example.com'
    });

    var operations = [];

    if (adGroup != null)
    {
        for (var keyword of keywords) {
            var operation = addKeyword(
                adGroup, 
                keyword.text, 
                keyword.cpc, 
                keyword.finalUrl);
            operations.push(operation);
        }
    }
    else {
        Logger.log("Unable to retrieve ad group, " + adGroupId);
    }

    checkBuildStatus(operations, keywords);
}

// Get the ad group using its ID.
function getAdGroup(id) {
    var iterator = AdsApp.adGroups()
        .withIds([id])
        .get();

    // Return the ad group if it exists; otherwise, null.
    if (iterator.hasNext()) {
        return iterator.next();
    }
    else {
        return null;
    }
}

// Add the keyword to the specified ad group.
function addKeyword(adGroup, text, cpc, finalUrl) {

    return adGroup.newKeywordBuilder()
        .withText(text)
        .withCpc(cpc)
        .withFinalUrl(finalUrl)
        .build();
}

// Check the keyword's build status.
function checkBuildStatus(operations, keywords) {

    for (var i = 0; i < operations.length; i++) {
        if (!operations[i].isSuccessful()) {
            for (var error of operations[i].getErrors()) {
                Logger.log(`Failed to add, ${keywords[i].text}. Error: ${error}`);
            }
        }
    }
}

キーワード (keyword) を一時停止する

キーワード (keyword)を追加すると、そのステータスはデフォルトで有効になります。キーワード (keyword)を一時停止するには、キーワード (keyword)の pause メソッドを呼び出します。キーワード (keyword)のステータスを確認するには、キーワードの isEnabled メソッドと isPaused メソッドを呼び出します。

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';
    var keywordText = 'KEYWORD TEXT GOES HERE';

    var iterator = AdsApp.keywords()
        .withCondition(`Text = '${keywordText}'`)
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

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

広告グループ内のすべてのキーワードを取得する

広告グループ内のすべてのキーワードを取得するには、まず AdsApp オブジェクトの keywords メソッドを呼び出してセレクターを取得します。広告グループとキャンペーンを指定するには、 withCondition メソッドを使用します。次に、セレクターの get メソッドを呼び出して、キーワードのリストを反復処理するために使用する反復子を取得します。反復子内のキーワードの数を確認するには、反復子の totalNumEntities メソッドを呼び出します。

キーワード (keyword) ID にアクセスできる場合は、代わりに使用します。 ID を使用してエンティティを取得すると、パフォーマンスが向上します。 withCondition フィルターメソッドを使用する代わりに、withIds メソッドを使用します。たとえば、「 withIds(['12345']) 」のように入力します。 ID を使用して取得できるエンティティの数には制限があります。

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';

    var iterator = AdsApp.keywords()
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();
        
    while (iterator.hasNext()) {
        var keyword = iterator.next();
    }
}

アカウント内のすべてのキーワードを取得する

スクリプトがアカウントに対して返すことができるキーワードの数には制限があります。制限は未定義であり、変更される可能性があります。次の例は、アカウントのキーワードが多すぎる場合の処理方法を示しています。この例では、最初にアカウントレベルですべてのキーワードを取得しようとします。 "エンティティが多すぎます" というエラーが原因で失敗した場合は、通常、キャンペーンレベルのエンティティが少ないため、キャンペーンごとにキーワードを取得するために複数の呼び出しが試行されます。

yield キーワード (keyword) の使用の詳細については、「大規模なエンティティセットを取得するときに yield キーワード (keyword) を使用する」を参照してください。

function* getEntities() {
    const applyConditions = _ => _
        .withCondition('CampaignStatus = ENABLED')
        .withCondition('AdGroupStatus = ENABLED')
        .withCondition('Status = ENABLED')
        .withCondition("CombinedApprovalStatus = DISAPPROVED");

    try {
        // Get the account's keywords. 
        const keywords = applyConditions(AdsApp.keywords()).get();

        while (keywords.hasNext()) {
            yield keywords.next();
        }
    } catch (e) {
        if (!e.message.startsWith('There are too many entities')) {
            throw e;
        }

        // If there are too many keywords at the account level,
        // get keywords by campaigns under the account.
        const campaigns = AdsApp.campaigns().get();

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

            const keywords = applyConditions(campaign.keywords()).get();

            while (keywords.hasNext()) {
                yield keywords.next();
            }
        }
    }
}

キーワード (keyword) のパフォーマンスデータを取得する

キーワード (keyword) のパフォーマンスメトリックを取得するには、キーワード (keyword) の getStats メソッドを呼び出します。キーワード (keyword) を取得する場合は、必要なメトリックデータの日付範囲を指定する必要があります。日付範囲は、LAST_MONTH や TODAY などの定義済みリテラル、または開始日と終了日を使用して指定できます。日付範囲を指定するには、キーワード (keyword)を選択するときにforDateRange方法のいずれかを使用します (「キーワードセレクター」を参照)。

アクセスできるメトリックのリストについては、 Stats オブジェクトを参照してください。

function main() {
    var campaignName = 'CAMPAIGN NAME GOES HERE';
    var adGroupName = 'AD GROUP NAME GOES HERE';
    var keywordText = 'KEYWORD TEXT GOES HERE';

    // Get the keyword. You need to specify the date range of the
    // performance data you want to get.
    var iterator = AdsApp.keywords()
        .forDateRange('LAST_WEEK')
        .withCondition(`Text = '${keywordText}'`)
        .withCondition(`AdGroupName = '${adGroupName}'`)
        .withCondition(`CampaignName = '${campaignName}'`)
        .get();

    // If the keyword is found, log some metrics.
    if (iterator.hasNext()) {
        var keyword = iterator.next();
        var metrics = keyword.getStats(); // Gets the performance metrics.
    }
}

キーワード (keyword) の入札単価を更新します。

キーワード (keyword) の入札価格を更新する方法の例については、「Google サービスの呼び出し」を参照してください。

フィードバック

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

Last updated on 2026-09-11