突變

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