變更

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 版本，例如 V26。您可以選擇當時的任何公開版本。
  • 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});