Sử dụng mã tạm thời

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

BatchJobService hỗ trợ tên tài nguyên tạm thời có thể được tham chiếu trong các thao tác tiếp theo trong cùng một công việc hàng loạt, bao gồm cả nhiều yêu cầu AddBatchJobOperations tuần tự được tải lên bằng sequence_token. Nhờ đó, bạn có thể tạo một chiến dịch và các nhóm quảng cáo, quảng cáo và tiêu chí phụ thuộc trong một công việc hàng loạt trước khi mã nhận dạng phía máy chủ được chỉ định. Trong các quy tắc chung và ví dụ sau đây, một yêu cầu duy nhất đề cập đến toàn bộ BatchJob trên tất cả các lượt tải lên AddBatchJobOperations.

Để tham chiếu một tài nguyên mới tạo trong cùng một yêu cầu thay đổi hoặc công việc hàng loạt, hãy chỉ định một mã nhận dạng số nguyên âm (chẳng hạn như -1 hoặc -2, ngoại trừ 0) trong trường resource_name của tài nguyên mới. Ví dụ: khi tạo một chiến dịch trong yêu cầu hàng loạt, hãy đặt tên tài nguyên của chiến dịch đó thành customers/CUSTOMER_ID/campaigns/-1. Khi tạo một nhóm quảng cáo trong một thao tác sau đó trong cùng một yêu cầu, hãy tham chiếu customers/CUSTOMER_ID/campaigns/-1 làm chiến dịch mẹ. API sẽ tự động thay thế -1 bằng mã chiến dịch thực tế được tạo khi tạo.

Các ràng buộc về việc sử dụng

Hãy lưu ý các quy tắc sau khi sử dụng tên tài nguyên tạm thời:

• Thứ tự rất quan trọng: Bạn chỉ có thể tham chiếu tên tài nguyên tạm thời sau khi xác định tên đó. Trong danh sách các thao tác, thao tác phụ thuộc (chẳng hạn như tạo nhóm quảng cáo) phải xuất hiện sau thao tác tạo tài nguyên mẹ (chẳng hạn như tạo chiến dịch).
• Phạm vi yêu cầu đơn lẻ hoặc công việc hàng loạt: Tên tài nguyên tạm thời không tồn tại trong các công việc hoặc yêu cầu thay đổi tài nguyên riêng biệt. Để tham chiếu một tài nguyên được tạo trong một công việc hoặc yêu cầu thay đổi trước đó, hãy sử dụng tên tài nguyên thực tế do hệ thống tạo.
• Tính duy nhất trên toàn cầu: Trong một công việc hoặc yêu cầu thay đổi tài nguyên duy nhất, mỗi tên tài nguyên tạm thời phải sử dụng một số nguyên âm duy nhất trên tất cả các loại tài nguyên. Ví dụ: bạn không thể chỉ định -1 cho cả chiến dịch và nhóm quảng cáo trong cùng một yêu cầu. Việc sử dụng lại mã tạm thời trong cùng một yêu cầu hoặc công việc hàng loạt sẽ trả về lỗi NewResourceCreationError.DUPLICATE_TEMP_IDS.

Tải trọng mẫu

Giả sử bạn muốn thêm một chiến dịch, một nhóm quảng cáo và một quảng cáo trong một yêu cầu API hoặc công việc hàng loạt. Bạn có thể cấu trúc mảng mutateOperations trong tải trọng yêu cầu GoogleAdsService.Mutate hoặc BatchJobService.AddBatchJobOperations như trong ví dụ JSON REST sau (các trường tài nguyên bắt buộc khác bị bỏ qua để ngắn gọn):

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

Ví dụ này minh hoạ các thông tin chi tiết chính sau:

• Nhóm quảng cáo sử dụng mã tạm thời mới (-2) vì -1 đã được chỉ định cho chiến dịch.
• Nhóm quảng cáo tham chiếu customers/CUSTOMER_ID/campaigns/-1 để liên kết với chiến dịch được tạo trong thao tác trước đó.
• adGroupAdOperation tham chiếu customers/CUSTOMER_ID/adGroups/-2 và bỏ qua resourceName vì không có thao tác tiếp theo nào trong yêu cầu tham chiếu đến quảng cáo mới.

Xử lý lỗi trong công việc hàng loạt

Vì các thao tác tiêu chuẩn trong một công việc hàng loạt thực thi khi bật lỗi một phần (ngoại trừ trong các lô con nguyên tử), nên nếu một tài nguyên mẹ có mã tạm thời không xác thực được, thì mọi thao tác con phụ thuộc tham chiếu đến mã tạm thời đó sẽ không thành công với NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. Việc sử dụng lại cùng một mã nhận dạng âm trên nhiều thao tác create trong cùng một công việc hàng loạt sẽ trả về NewResourceCreationError.DUPLICATE_TEMP_IDS. Mã tạm thời chỉ hợp lệ khi tạo tài nguyên (create) hoặc tham chiếu đến tài nguyên mẹ mới tạo; ví dụ: việc truyền mã tạm thời âm trong AdGroupCriterionOperation.remove khi gọi AddBatchJobOperations sẽ trả về RequestError.RESOURCE_NAME_MALFORMED.