Method: customers.googleAds.mutate

创建、更新或移除资源。此方法支持涉及多种资源的原子事务。例如，您可以自动创建广告系列和广告系列预算，或者以原子方式执行多达数千次更改。

该方法本质上是一系列 mutate 方法的封装容器。与直接调用这些方法相比，它提供的唯一功能包括：

  • 原子化事务
  • 临时资源名称（如下所述）
  • 略微减少进行一系列 mutate 调用时的延迟时间

注意：其中仅包含支持原子事务的资源，因此此方法无法替换对单个服务的所有调用。

原子化交易优势

原子性大大简化了错误处理。如果您进行了一系列更改，但有一项更改失败，则可能会导致帐号出现不一致的情况。如果采用原子性，您要么直接到达所选状态，要么请求失败，然后您可以重试。

临时资源名称

临时资源名称是一种特殊类型的资源名称，用于创建资源并在同一请求中引用该资源。例如，如果创建广告系列预算时，其 resourceName 等于 customers/123/campaignBudgets/-1，那么该资源名称可以在同一请求的 Campaign.budget 字段中重复使用。这样一来，这两个资源就能以原子方式创建并链接。

如需创建临时资源名称，请在服务器通常分配的名称部分输入一个负数。

注意：

  • 必须使用临时名称创建资源，然后才能重复使用该名称。例如，如果将 mutate 顺序反转，之前的 CampaignBudget+Campaign 示例将会失败。
  • 系统不会记住多个请求的临时名称。
  • 请求中的临时名称没有数量限制。
  • 每个临时名称都必须使用唯一的负数，即使资源类型不同也是如此。

延迟时间

请务必按资源类型对 mutate 进行分组，否则请求可能会超时和失败。延迟时间大致等于对各个 mutate 方法的一系列调用，其中资源类型的每次更改都是一次新的调用。例如，更改 10 个广告系列、10 个广告组和 2 次来电就相当于更改 1 个广告系列、1 个广告组、1 个广告系列和 1 个广告组的转化操作，就相当于更改 4 次来电。

。AdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

HTTP 请求

POST https://googleads.googleapis.com/v16/customers/{customerId}/googleAds:mutate

网址采用 gRPC 转码语法。

路径参数

参数
customerId

string

必需。要修改其资源的客户的 ID。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
字段
mutateOperations[]

object (MutateOperation)

必需。对各个资源执行的操作列表。
partialFailure

boolean

如果为 true，将执行成功的操作，而无效操作将返回错误。如果为 false，当且仅当所有操作均有效时，所有操作都将在一个事务中执行。默认值为 false。
validateOnly

boolean

如果为 true，则会验证该请求，但不会执行该请求。系统只会返回错误，不会返回结果。
responseContentType

enum (ResponseContentType)

响应内容类型设置。确定在完成变更后应该返回可变资源还是仅返回资源名称。仅当该资源具有适当的响应字段时，系统才会返回该可变资源。例如：MutateCampaignResult.campaign。

响应正文

GoogleAdsService.Mutate 的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
字段
partialFailureError

object (Status)

与部分失败模式下的操作失败相关的错误。仅当 partialFailure = true 且所有错误发生在操作内部时，才返回 partialFailure。如果操作之外发生任何错误（例如身份验证错误），我们会返回 RPC 级错误。
mutateOperationResponses[]

object (MutateOperationResponse)

转变的所有响应。

授权范围

需要以下 OAuth 作用域：

  • https://www.googleapis.com/auth/adwords

有关详情，请参阅 OAuth 2.0 概览。