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 theo lô, 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 cũng như tiêu chí phụ thuộc của chiến dịch đó trong một công việc theo lô duy nhất trước khi mã 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 bản tải lên AddBatchJobOperations của yêu cầu đó.

Để tham chiếu đến một tài nguyên mới tạo trong cùng một yêu cầu thay đổi tài nguyên hoặc công việc theo lô, 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 chiến dịch trong một yêu cầu theo lô, 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 gốc. 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 quy tắ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 gốc (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 theo lô: 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 yêu cầu thay đổi tài nguyên hoặc công việc 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 hệ thống: Trong một yêu cầu thay đổi tài nguyên hoặc một công việc, 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 theo lô sẽ trả về lỗi NewResourceCreationError.DUPLICATE_TEMP_IDS.

Phần tải 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 theo lô. Bạn có thể định 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ụ về JSON REST sau đây (với các trường tài nguyên bắt buộc khác được bỏ qua để cho 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 chính sau:

• Nhóm quảng cáo sử dụng một 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 chính nó với chiến dịch được tạo trong thao tác trước đó.
• adGroupAdOperation tham chiếu đến customers/CUSTOMER_ID/adGroups/-2 và bỏ qua resourceName vì không có thao tác nào tiếp theo trong yêu cầu tham chiếu đến quảng cáo mới.

Xử lý lỗi trong công việc theo lô

Vì các thao tác chuẩn trong một công việc theo lô được thực thi khi bật chế độ lỗi một phần (ngoại trừ trong các lô phụ 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à trả về lỗ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 theo lô sẽ trả về lỗi 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.