Google Ads 指令碼支援 Google Ads API 中提供的通用變動。您可以在 Google Ads 腳本中執行大部分可透過 GoogleAdsService.mutate
執行的作業,包括建立及管理廣告活動。
由於這項功能可存取 Google Ads API 的大部分內容,因此請務必先瞭解 Google Ads API 的基本慣例,再使用這項功能。許多環節都可以略過,例如開發人員權杖和授權,因為這些都由 Google Ads 指令碼為您處理,但您必須建立有效的變動要求。
以下是 Google Ads API REST 介面的基本資源,建議您先熟悉這些資源,再繼續閱讀本指南:
基本範例
如要示範這項功能,請參考這個基本範例,瞭解如何建立廣告活動預算:
const budgetResult = AdsApp.mutate({
campaignBudgetOperation: {
create: {
amountMicros: 10000000,
explicitlyShared: false
}
}
});
呼叫 AdsApp.mutate
時,會採用代表單一 MutateOperation
的 JSON 物件。在這個物件中,您可以指定要執行的作業類型,在本例中為 campaignBudgetOperation
。然後指定 create
、remove
,或同時指定 update
和 updateMask
。create
和 update
中的特定欄位取決於您操作的資源類型。
建構作業
您可以使用幾種策略來建立有效的作業。以廣告活動預算為例,您可以查閱廣告活動預算的 REST 參考文件,查看所有有效欄位的清單,然後填寫適當的欄位,或在指令碼中編寫自訂 JavaScript 程式碼,建構適當的物件。
或者,您也可以使用廣告活動預算的「試試看」功能,動態建構作業,藉此選取要加入的欄位,動態建構要求主體。接著,您可以從產生的結果中擷取作業內容,並在指定作業類型後,將其新增至 mutate
呼叫。
作業類型
建立
在作業中指定 create
,並傳遞要建立的資源物件表示法。
如需 create
作業的範例,請參閱上文。
移除
在作業中指定 remove
,並傳入要移除的資源資源名稱,例如:
AdsApp.mutate({
adGroupOperation: {
remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
}
});
如果您不知道實體的資源名稱,可以使用 Adsapp.search
要求擷取。
更新
在作業中指定 update
,並傳遞指定資源名稱的物件,讓系統判斷要更新的物件。此外,請填寫要更新值的任何欄位,並指定 updateMask
,指出您打算在這項要求中變更哪些欄位。請勿在更新遮罩中加入資源名稱。
update
作業範例:
const campaignResult = AdsApp.mutate({
campaignOperation: {
update: {
resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
status: "PAUSED",
name: "[Paused] My campaign"
},
updateMask: "name,status"
}
});
處理結果
無論作業類型為何,傳回值都是 MutateResult
。變動後,您可以使用傳回的資源名稱查詢資源的目前狀態,並檢查作業是否成功,或發生了哪些錯誤 (如有)。
以下範例顯示檢查結果並將部分資訊列印到記錄的基本流程:
const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
console.log("Errors encountered:");
for (const error of result.getErrorMessages()) {
console.log(error);
}
}
多項作業
Google Ads 指令碼也支援使用 AdsApp.mutateAll
方法,在單一要求中變動多項作業。您可以建立相互依附的實體,例如在單一要求中建立完整的廣告活動階層。您可以選擇讓整組作業成為不可分割的作業,這樣一來,如果任何作業失敗,系統就不會執行任何作業。
回傳值是 MutateResult
物件陣列,每個物件對應您提供的其中一項作業,且順序與初始作業相同。
這項功能與 Google Ads API 功能相同,因此請參閱 Google Ads API 最佳做法指南,瞭解臨時 ID 和其他注意事項的完整說明。請注意,該指南使用 snake_case
代表欄位名稱,而 Google Ads 指令碼說明文件則使用 lowerCamelCase
。Google Ads 腳本接受這兩種情況,因此您可以直接從該指南複製程式碼。
如要在單一要求中執行多項作業,請將所有作業收集到陣列中,然後呼叫 AdsApp.mutateAll
。mutateAll
呼叫會將作業陣列做為第一個引數,並將選項的選用第二個引數 (包括下列項目) 做為引數:
apiVersion
:如要使用指令碼預設版本以外的版本,可以指定自訂 API 版本,例如V20
。當時可使用任何公開版本。partialFailure
:這個欄位預設為true
。如果設為true
,系統會執行有效作業,並針對失敗的作業傳回錯誤。如果設為false
,則如果任何作業失敗,系統就不會執行任何作業,有效讓這組作業成為不可分割的作業。
以下範例包含多項作業,可在原子要求中建立廣告活動預算、廣告活動和廣告群組。
const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
campaignBudgetOperation: {
create: {
resourceName: budgetId,
amountMicros: 10000000,
explicitlyShared: false
}
}
});
operations.push({
campaignOperation: {
create: {
resourceName: campaignId,
name: 'New Campaign ' + new Date(),
advertisingChannelType: 'SEARCH',
manualCpc: {},
campaignBudget: budgetId,
advertisingChannelType: 'DISPLAY',
networkSettings: {
targetContentNetwork: true
}
}
}
});
operations.push({
adGroupOperation: {
create: {
campaign: campaignId,
name: 'New AdGroup ' + new Date(),
optimizedTargetingEnabled: true
}
}
});
const results = AdsApp.mutateAll(
operations, {partialFailure: false});