Dịch vụ tài nguyên biến đổi

Sử dụng dịch vụ chuyên dụng của một tài nguyên là cách trực tiếp nhất để tạo, cập nhật hoặc xoá các thực thể thuộc một loại tài nguyên duy nhất trong Google Ads API.

Thay đổi điểm cuối

Mỗi tài nguyên có thể thay đổi đều có một dịch vụ và loại thao tác tương ứng. Để thay đổi một tài nguyên bằng dịch vụ chuyên dụng, hãy điền một trong các trường sau vào thao tác và gửi đến điểm cuối đột biến của dịch vụ:

  • Tạo (create): Một đối tượng tài nguyên mới cần tạo.
  • Cập nhật (update): Đối tượng tài nguyên đã sửa đổi, kèm theo một update_mask chỉ định các trường đã thay đổi.
  • Xoá (remove): Chuỗi resource_name của tài nguyên mục tiêu cần xoá.

Ví dụ: để tạo một Campaign mới, hãy hoàn tất các bước sau:

  1. Tạo một đối tượng Campaign bằng các thuộc tính mà bạn đã chọn.
  2. Chỉ định giá trị này cho trường create của CampaignOperation.
  3. Gửi thao tác trong MutateCampaignsRequest đến CampaignService.MutateCampaigns.

Mô hình này áp dụng cho tất cả các dịch vụ dành riêng cho tài nguyên trong Google Ads API:

Tải trọng JSON REST sau đây minh hoạ một yêu cầu đối với CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

Nhiều thao tác và hạn chế

Vì trường operations của một yêu cầu thay đổi tài nguyên được lặp lại, nên một yêu cầu duy nhất có thể chứa nhiều thao tác (tối đa 10.000 thao tác cho mỗi yêu cầu) đối với loại tài nguyên đó. Theo mặc định, tất cả các thao tác trong yêu cầu đều thực thi một cách nguyên tử, trừ phi bạn đặt partial_failure thành true.

Tuy nhiên, các dịch vụ tài nguyên riêng lẻ có hai hạn chế quan trọng:

  • Một loại tài nguyên: Yêu cầu đối với một dịch vụ tài nguyên chỉ có thể thay đổi các tài nguyên do dịch vụ cụ thể đó quản lý.
  • Không có mã nhận dạng tài nguyên tạm thời hoặc tham chiếu chéo: Các thao tác trong một lệnh gọi biến đổi dành riêng cho tài nguyên sẽ được xử lý độc lập. Bạn không thể chỉ định mã nhận dạng âm tạm thời (chẳng hạn như customers/CUSTOMER_ID/campaigns/-1) hoặc tham chiếu các thực thể mới tạo từ các thao tác khác trong cùng một yêu cầu.

Nếu bạn cần thay đổi nhiều loại tài nguyên trong một yêu cầu hoặc tham chiếu tên tài nguyên tạm thời trên các thao tác phụ thuộc, hãy sử dụng GoogleAdsService.Mutate.

Sự khác biệt theo phiên bản

Hãy lưu ý những điểm khác biệt sau đây giữa các phiên bản Google Ads API được hỗ trợ khi biến đổi tài nguyên:

  • Dịch vụ mục tiêu vòng đời: Trong phiên bản 25 trở lên, tất cả mục tiêu vòng đời (bao gồm cả Thu nạp khách hàng mới (new_customer_acquisition_goal_settings), Giữ chân khách hàng (retention_goal_settings) và Giữ chân khách hàng thân thiết (loyalty_retention_goal_settings)) đều được thay đổi thông qua GoalService.MutateGoals và CampaignGoalConfigService.MutateCampaignGoalConfigs bằng cách sử dụng trường operations lặp lại tiêu chuẩn. Thao tác này sẽ thay thế CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals và CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (được dùng cho tính năng Thu nạp khách hàng mới trong phiên bản 24 trở xuống và chấp nhận một trường operation duy nhất).
  • Các trường ngày và giờ của chiến dịch: Khi tạo hoặc cập nhật Campaign, phiên bản 23 trở lên sẽ sử dụng start_date_time và end_date_time (yyyy-MM-dd HH:mm:ss), thay thế các trường chỉ có ngày start_date và end_date được dùng trong phiên bản 22.
  • Tính bất biến của chứng thực nội dung giả tạo: Mặc dù Asset.synthetic_content_info và Ad.synthetic_content_info xuất hiện trong giản đồ cho phiên bản 22 trở lên, nhưng các trường synthetic_content_info.advertiser_attestation.status và synthetic_content_info.advertiser_attestation.source chỉ có thể thay đổi trong phiên bản 23 trở lên (system_attestation luôn là OUTPUT_ONLY). Việc cố gắng thay đổi các trường con advertiser_attestation trong phiên bản 22 sẽ trả về lỗi trường bất biến ("The field attempted to be mutated is immutable" hoặc "Field cannot be set").
Trước
Tổng quan
Tiếp
Thay đổi hàng loạt