広告グループを管理するためのスクリプトの例
次のセクションでは、広告グループに対してさまざまなアクションを実行するスクリプトの例を示します。
広告グループを追加する
広告グループを追加するには、まず広告グループを追加するキャンペーンを取得します。
CampaignSelector オブジェクトを使用してキャンペーンを選択します。 メソッドを withIds 使用すると、 メソッドでキャンペーンの名前を渡すよりもパフォーマンスが withCondition 向上します。
次に、キャンペーンの newAdGroupBuilder メソッドを呼び出して、広告グループのプロパティを指定するために使用するビルダーを取得します。 必須のプロパティは、広告グループの名前 (メソッドを withName 参照) のみです。これはキャンペーン内で一意である必要があります。 クリック単価型 (CPC) の値を指定しない場合、既定ではアカウントの通貨の最小入札金額が設定されます。 言語は、キャンペーンで指定されていない場合にのみ指定する必要があります。それ以外の場合は、キャンペーンの言語値が継承されます。 既定では、広告グループの状態は一時停止されています。
ビルダー build のメソッドを呼び出すと、広告グループが非同期的に作成されます。スクリプトは、スクリプトが終了する前、またはビルド操作のいずれかのメソッドを呼び出す場合に、広告グループを追加します。 このプロセスの詳細については、「ビルダーとは」を参照してください。
function main() {
// The ID of the campaign to add the ad groups to.
// IDs in Scripts are string integers.
var campaignId = 'CAMPAIGN ID GOES HERE';
var campaign = getCampaign(campaignId);
// Ad groups to add.
var adGroups = [];
adGroups.push({
name : 'AD GROUP NAME GOES HERE',
cpc : 2.25,
language : 'English' // Required if the campaign doesn't specify a language
});
adGroups.push({
name : 'AD GROUP NAME GOES HERE',
cpc : 1.25,
language : 'English' // Required if the campaign doesn't specify a language
});
var operations = [];
if (campaign != null)
{
for (var adGroup of adGroups) {
var operation = addAdGroup(
campaign,
adGroup.name,
adGroup.cpc,
adGroup.language);
operations.push(operation);
}
}
else {
Logger.log("Unable to retrieve campaign, " + campaignId);
}
checkBuildStatus(operations, adGroups);
}
// Get the campaign using its ID.
function getCampaign(id) {
var iterator = AdsApp.campaigns()
.withIds([id])
.get();
// Return the campaign if it exists; otherwise, null.
if (iterator.hasNext()) {
return iterator.next();
}
else {
return null;
}
}
// Add the ad group to the specified campaign.
// Returns the builder's operation object, which you use to
// check the status of the add operation.
function addAdGroup(campaign, name, cpc, language) {
return campaign.newAdGroupBuilder()
.withName(name)
.withCpc(cpc)
.withLanguage(language)
.build();
}
// Check the ad group's build status.
function checkBuildStatus(operations, adGroups) {
for (var i = 0; i < operations.length; i++) {
if (!operations[i].isSuccessful()) {
for (var error of operations[i].getErrors()) {
Logger.log(`Failed to add, ${adGroups[i].name}. Error: ${error}`);
}
}
}
}
すべての広告グループを取得する
アカウント内のすべての広告グループを取得するには、まず AdsApp オブジェクトの adGroups メソッドを呼び出してセレクターを取得 します。 次に、セレクターの get メソッドを呼び出して、広告グループの一覧を反復処理するために使用する 反復子 を取得します。 この例ではフィルターが指定されていないため、セレクターはアカウント内のすべての広告グループを返します。 反復子内の広告グループの数を確認するには、反復子の totalNumEntities メソッドを呼び出します。
function main() {
// Gets all ad groups in the account.
var iterator = AdsApp.adGroups().get();
// Iterates through the list of ad groups and logs
// each ad group's name.
while (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
名前で広告グループを取得する
名前で広告グループを取得するには、まず AdsApp オブジェクトの adGroups メソッドを呼び出してセレクターを取得 します。 セレクターには、広告グループの一覧をフィルター処理するために使用するフィルター 方法が多数含まれています。 メソッドを withCondition 使用して、特定の広告グループ名の広告グループをフィルター処理します。 オペランドと演算子では大文字と小文字が区別されることに注意してください。
次に、セレクターの get メソッドを呼び出して 反復子を取得します。 キャンペーン内の広告グループ名は一意ですが、複数のキャンペーンで同じ名前の広告グループを持つことができます。 このため、名前のみでフィルター処理する場合、反復子に複数の広告グループが含まれる場合があります。
特定のキャンペーンから名前で広告グループを取得する場合は、キャンペーンの名前 (CampaignName = '<campaignnamegoeshere>') を指定するメソッドを含めますwithCondition。
function main() {
// The name of the ad group to get.
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad groups with the specified name.
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.get();
// Need a loop because multiple campaigns can have
// an ad group with the same name.
while (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
ID で広告グループを取得する
広告グループの ID にアクセスできる場合は、代わりに使用してください。 ID を使用してエンティティを取得すると、パフォーマンスが向上します。 フィルター メソッドを使用する withCondition 代わりに、 メソッドを使用します withIds 。 たとえば、「 withIds(['12345']) 」のように入力します。
function main() {
var adGroupId = '12345';
var iterator = AdsApp.adGroups()
.withIds([adGroupId])
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
特定のキャンペーンから名前で広告グループを取得する
function main() {
var adGroupName = 'AD GROUP NAME GOES HERE';
var campaignName = "CAMPAIGN NAME GOES HERE";
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
広告グループのパフォーマンス データを取得する
広告グループのパフォーマンス メトリックを取得するには、広告グループの getStats メソッドを 呼び出します。 広告グループを取得するときは、目的のメトリック データの日付範囲を指定する必要があります。 日付範囲は、LAST_MONTHや TODAY などの定義済みのリテラル、または開始日と終了日を使用して指定できます。 日付範囲を指定するには、広告グループを forDateRange 選択するときにいずれかの方法を使用します ( 「AdGroupSelector」を参照)。
アクセスできるメトリックの一覧については、 Stats オブジェクトを参照してください。
function main() {
var campaignName = 'CAMPAIGN NAME GOES HERE';
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad group. You need to specify the date range of the
// performance data you want to get.
var iterator = AdsApp.adGroups()
.forDateRange('LAST_WEEK')
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
// If the ad group is found, log some metrics.
if (iterator.hasNext()) {
var adGroup = iterator.next();
var metrics = adGroup.getStats(); // Gets the performance metrics.
}
}
広告グループを一時停止する
広告グループを追加すると、その状態は既定で [一時停止] になります。 広告グループを有効にするには、広告グループの enable メソッドを呼び出します。 広告グループの状態を Paused に変更するには、広告グループの pause メソッドを呼び出します。 広告グループの状態を確認するには、広告グループの isEnabled、、 isPausedおよび メソッドを isRemoved 呼び出します。
function main() {
var campaignName = 'CAMPAIGN NAME GOES HERE';
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad group.
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
adGroup.pause();
}
}