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 một chiến dịch và ngân sách chiến dịch theo từng phần tử hoặc thực hiện hàng nghìn thao tác thay đổi theo từng phần 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 đột biến. Các tính năng duy nhất mà lớp này cung cấp so với 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 (mô tả bên dưới)
  • Giảm độ trễ khi thực hiện một loạt lệnh gọi thay đổi

Lưu ý: Phương thức này chỉ bao gồm các tài nguyên hỗ trợ giao dịch nguyên tử, 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ử

Tính 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 đang thực hiện một loạt thay đổi và 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ẽ trực tiếp chuyển đến trạng thái đã chọn hoặc 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 tài nguyên đó trong cùng một yêu cầu. Ví dụ: nếu bạn tạo ngân sách chiến dịch 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 và liên kết một cách nguyên tử.

Để 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 về CampaignBudget+Campaign 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ớ trên 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ễ

Điều quan trọng là bạn phải nhóm các đột biến 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 loạt 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 thay đổi 10 chiến dịch rồi thay đổi 10 nhóm quảng cáo tương đương với 2 lệnh gọi, trong khi việc thay đổ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 tương đương với 4 lệnh gọi.

Danh sách lỗi đã gửi: 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 ResourceCountLimitExceededError SettingError SharedSetError SizeLimitError StringFormatError StringLengthError UrlFieldError UserListError YoutubeVideoRegistrationError

Yêu cầu HTTP

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

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

Tham số đường dẫn

Thông số
customerId

string

Bắt buộc. Mã nhận dạng 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 các 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 nếu 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 chứ 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 sẽ đượ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

Thông báo 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 các lỗi hoạt động ở chế độ không thực hiện được một phần. Chỉ được trả về khi partialFailure = true và tất cả lỗi xảy ra bên trong các thao tác. Nếu có lỗi xảy ra bên 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 hoạt động 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 OAuth 2.0 Overview.