突變

Google Ads 指令碼支援 Google Ads API 提供的一般變異。您可以在 GoogleAdsService.mutate 中執行的大部分作業，也能在 Google Ads 指令碼中執行，包括建立及管理廣告活動。

由於這項功能可讓您存取 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});