突變

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。然後指定 createremove,或同時指定 updateupdateMaskcreateupdate 中的特定欄位取決於您操作的資源類型。

建構作業

您可以使用幾種策略來建立有效的作業。以廣告活動預算為例,您可以查閱廣告活動預算的 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.mutateAllmutateAll 呼叫會將作業陣列做為第一個引數,並將選項的選用第二個引數 (包括下列項目) 做為引數:

  • 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});