Method: customers.googleAds.mutate

Tạo, cập nhật hoặc xoá tài nguyên. Phương thức này hỗ trợ các giao dịch không thể phân chia với nhiều loại tài nguyên. Ví dụ: bạn có thể tạo một chiến dịch và ngân sách chiến dịch cho từng chiến dịch hoặc thực hiện hàng nghìn thay đổi một cách triệt để.

Về cơ bản, phương thức này là một trình bao bọc xung quanh một loạt phương thức biến đổi. Các tính năng duy nhất mà lớp này cung cấp thay vì gọi trực tiếp các phương thức đó là:

  • Giao dịch nguyên tử
  • Tên tài nguyên tạm thời (mô tả bên dưới)
  • Giảm độ trễ một chút so với việc thực hiện một loạt các lệnh gọi đột biến

Lưu ý: Chỉ những tài nguyên hỗ trợ giao dịch không thể phân chia mới được đưa vào, vì vậy, phương thức này không thể thay thế tất cả các lệnh gọi đến các dịch vụ riêng lẻ.

Lợi ích của giao dịch nguyên tử

Atomicity giúp việc xử lý lỗi trở nên dễ dàng hơn nhiều. Nếu bạn thực hiện một loạt thay đổi nhưng không thực hiện được một thay đổi, thì điều này có thể khiến tài khoản của bạn có trạng thái không nhất quán. Với tính nguyên tố, bạn sẽ trực tiếp đạt đến trạng thái đã chọn, nếu không yêu cầu không thành công và bạn có thể thử lại.

Tên tài nguyên tạm thời

Tên tài nguyên tạm thời là một loại tên tài nguyên đặc biệt dùng để tạo tài nguyên và tham chiếu đến tài nguyên đó trong cùng một yêu cầu. Ví dụ: nếu ngân sách chiến dịch được tạo với resourceName bằng customers/123/campaignBudgets/-1, thì bạn có thể sử dụng lại tên tài nguyên đó trong trường Campaign.budget trong cùng một yêu cầu. Bằng cách đó, hai tài nguyên được tạo ra và liên kết chặt chẽ với nhau.

Để tạo tên tài nguyên tạm thời, hãy đặt một số âm vào phần tên mà máy chủ thường phân bổ.

Lưu ý:

  • Bạn phải tạo tài nguyên bằng tên tạm thời trước khi có thể sử dụng lại tên đó. Ví dụ: ví dụ trước đây về Ngân sách chiến dịch+Chiến dịch sẽ không thành công nếu đơn đặt hàng thay đổi đã bị đảo ngược.
  • Tên tạm thời không được ghi nhớ trong các yêu cầu.
  • Không có giới hạn về số lượng tên tạm thời trong một yêu cầu.
  • Mỗi tên tạm thời phải sử dụng một số âm duy nhất, ngay cả khi các loại tài nguyên khác nhau.

Độ trễ

Bạn cần phải nhóm các thay đổi theo loại tài nguyên, nếu không yêu cầu có thể hết thời gian chờ và không thực hiện được. Độ trễ gần bằng với một chuỗi các lệnh gọi đến từng phương thức đột biến, trong đó mỗi thay đổi về loại tài nguyên là một lệnh gọi mới. Ví dụ: việc biến đổi 10 chiến dịch thì 10 nhóm quảng cáo giống như 2 lệnh gọi, trong khi việc biến đổi 1 chiến dịch, 1 nhóm quảng cáo, 1 chiến dịch, 1 nhóm quảng cáo giống như 4 lệnh gọi.

Lỗi liên quan đến lỗi mà người dùng gửiAdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Yêu cầu HTTP

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

URL sử dụng cú pháp Chuyển mã gRPC.

Tham số đường dẫn

Tham số
customerId

string

Bắt buộc. Mã của khách hàng có tài nguyên đang được sửa đổi.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
Trường
mutateOperations[]

object (MutateOperation)

Bắt buộc. Danh sách thao tác cần thực hiện trên từng tài nguyên.
partialFailure

boolean

Nếu đúng, các thao tác thành công sẽ được thực hiện và các thao tác không hợp lệ sẽ trả về lỗi. Nếu giá trị là false, tất cả các thao tác sẽ được thực hiện trong một giao dịch khi và chỉ khi tất cả các thao tác đó đều hợp lệ. Mặc định là sai.
validateOnly

boolean

Nếu đúng, yêu cầu sẽ được xác thực nhưng không được thực thi. Chỉ trả về lỗi, không trả về kết quả.
responseContentType

enum (ResponseContentType)

Chế độ cài đặt loại nội dung phản hồi. Xác định xem tài nguyên có thể thay đổi hay chỉ tên tài nguyên được trả về sau khi đột biến. Tài nguyên có thể thay đổi sẽ chỉ được trả về nếu tài nguyên có trường phản hồi thích hợp. Ví dụ: MutateCampaignResult.campaign.

Nội dung phản hồi

Tin nhắn phản hồi cho GoogleAdsService.Mutate.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
Trường
partialFailureError

object (Status)

Lỗi liên quan đến lỗi thao tác ở chế độ lỗi một phần. Giá trị chỉ được trả về khi internalFailure = true và tất cả lỗi xảy ra trong thao tác. Nếu có lỗi xảy ra ngoài thao tác (ví dụ: lỗi xác thực), chúng tôi sẽ trả về lỗi ở cấp RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

Tất cả phản hồi cho trường hợp thay đổi.

Phạm vi uỷ quyền

Yêu cầu phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem Tổng quan về OAuth 2.0.