此页面由 Cloud Translation API 翻译。

Mutate

Google Ads 脚本支持 Google Ads API 中提供的通用 mutate 操作。可通过 GoogleAdsService.mutate 执行的大多数操作也可以在 Google Ads 脚本中执行，包括创建和管理广告系列。

此功能允许访问 Google Ads API 的这么大一部分，因此对 Google Ads API 规范有基本的了解才能使用该功能。很多方面（如开发者令牌和授权）可以跳过，因为这些方面由 Google Ads 脚本为您处理，但您必须构建有效的 mutate 请求。

在继续本指南之前，您应该先熟悉以下关于 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 版本，例如 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});