Method: customers.googleAds.mutate

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

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

  • 原子化事务
  • 临时资源名称（详见下文）
  • 与发出一系列更改调用相比，延迟时间略有缩短

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

原子化事务的优势

原子性可让错误处理变得更加容易。如果您要进行一系列更改，其中一个更改失败，则可能会导致您的账号处于不一致的状态。使用原子性时，您要么直接达到所选状态，要么请求失败，您可以重试。

临时资源名称

临时资源名称是一种特殊类型的资源名称，用于在同一请求中创建资源并引用该资源。例如，如果创建的广告系列预算的 resourceName 等于 customers/123/campaignBudgets/-1，则可以在同一请求的 Campaign.budget 字段中重复使用该资源名称。这样，两个资源会原子化地创建和关联。

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

注意：

  • 必须使用临时名称创建资源，然后才能重复使用该名称。例如，如果将上述 CampaignBudget+Campaign 示例中的更改顺序颠倒过来，则该示例将会失败。
  • 系统无法跨请求记住临时名称。
  • 一个请求中的临时名称个数没有限制。
  • 每个临时名称都必须使用具有唯一性的负数，即使资源类型不同也是如此。

延迟时间

请务必按资源类型对更改进行分组，否则请求可能会超时并失败。延迟时间大致等于对各个更改方法的一系列调用，其中资源类型的每次更改都代表一次新调用。例如，先更改 10 个广告系列，然后再更改 10 个广告组，相当于 2 次调用；而先更改 1 个广告系列、1 个广告组，然后再更改 1 个广告系列、1 个广告组，相当于 4 次调用。

抛出的错误列表：AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError KeywordPlanAdGroupKeywordError KeywordPlanCampaignError KeywordPlanError LabelError ListOperationError MediaUploadError MutateError NewResourceCreationError NullError OperationAccessDeniedError PolicyFindingError PolicyViolationError QuotaError RangeError RequestError LillardResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

HTTP 请求

POST https://googleads.googleapis.com/v19/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 且所有错误均发生在操作中时才返回。如果操作之外发生任何错误（例如身份验证错误），我们会返回 RPC 级错误。
mutateOperationResponses[]

object (MutateOperationResponse)

对更改的所有响应。

授权范围

需要以下 OAuth 范围：

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

如需了解详情，请参阅 OAuth 2.0 Overview。