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 nguyên tử với nhiều loại tài nguyên. Ví dụ: bạn có thể tạo chiến dịch và ngân sách chiến dịch một cách triệt để, hoặc thực hiện lên đến hàng nghìn thay đổi một cách triệt để.

Về cơ bản, phương thức này là trình bao bọc xung quanh một loạt các phương thức biến đổi. Các tính năng duy nhất mà nền tảng này cung cấp qua việc 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 (được mô tả bên dưới)
  • Giảm đáng kể độ trễ nhờ thực hiện một loạt cuộc gọi thay đổi

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

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

Nguyên tử 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 chỉ thực hiện một thay đổi không thành công, thì tài khoản của bạn có thể ở trạng thái không nhất quán. Với tính chất nguyên tử, bạn sẽ đạt được trạng thái đã chọn trực tiếp, nếu không yêu cầu sẽ 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 được dùng để tạo tài nguyên và tham chiếu 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 sẽ được tạo ra và liên kết với nhau về mặt nguyên tử.

Để tạo tên tài nguyên tạm thời, hãy đặ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 đó về CampaignNgân sách+Chiến dịch sẽ không thành công nếu thứ tự 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 biến đổ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ành công. Độ trễ gần bằng với một chuỗi lệnh gọi đến từng phương thức thay đổi, trong đó mỗi thay đổi về loại tài nguyên là một lệnh gọi mới. Ví dụ: biến đổi 10 chiến dịch thì 10 nhóm quảng cáo giống như 2 cuộc gọi, trong khi 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 cuộc gọi.

Lỗi {1717171AdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

Yêu cầu HTTP

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

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

Tham số đường dẫn

Các 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)
}
Các trường
mutateOperations[]

object (MutateOperation)

Bắt buộc. Danh sách thao tác cần thực hiện đối với 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 với điều kiện 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 thì yêu cầu sẽ được xác thực nhưng không được thực thi. Chỉ có lỗi được trả về, chứ không phải 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ầ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 trả lờ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)
    }
  ]
}
Các trường
partialFailureError

object (Status)

Các lỗi liên quan đến lỗi thao tác ở chế độ lỗi một phần. Chỉ trả về khi partialFailure = true và tất cả lỗi đều xảy ra trong thao tác. Nếu có lỗi xảy ra ngoài các 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 biến đổ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.