突變

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 功能相同，如需臨時 ID 和其他注意事項的完整說明，請參閱 Google Ads API 最佳做法指南。請注意，本指南使用 snake_case 表示欄位名稱，Google Ads 指令碼說明文件使用的是 lowerCamelCase。Google Ads 指令碼支援這兩種情況，方便您直接從該指南複製程式碼。

如要在單一要求中進行多項作業，請將所有作業收集至陣列中，然後呼叫 AdsApp.mutateAll。mutateAll 呼叫使用運算陣列做為第一個引數，以及選項的第二個引數，包括：

  • apiVersion：如果要使用指令碼預設值以外的版本，可以指定自訂 API 版本 (例如 V16)。您隨時可以使用任何公開版本。
  • 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});