此页面由 Cloud Translation API 翻译。

Mutate

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 的调用接受一个 JSON 对象，该对象表示单个 MutateOperation。在此对象中，您可以指定要执行的操作类型（在本例中为 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 版本，例如 V18。您可以使用当时的任何公开版本。
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});