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 lô công việc, bao gồm cả trên nhiều yêu cầu AddBatchJobOperations tuần tự được tải lên bằng một sequence_token. Điều này cho phép bạn 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 của chiến dịch đó trong một công việc hàng loạt duy nhấ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ả nội dung tải lên AddBatchJobOperations.

Để 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 lô công việc, 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 này sẽ tự động thay thế -1 bằng mã chiến dịch thực tế được tạo khi tạo chiến dịch.

Các quy tắc ràng buộc đối với việc sử dụng

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

• Thứ 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 một 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 một 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 duy trì trên các yêu cầu riêng biệt hoặc yêu cầu biến đổi. Để tham chiếu đến một tài nguyên được tạo trong một công việc hoặc yêu cầu thay đổi tài nguyên trước đó, hãy sử dụng tên tài nguyên thực do hệ thống tạo.
• Tính duy nhất trên toàn cầu: Trong một yêu cầu duy nhất về công việc hoặc yêu cầu thay đổi, 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 lệnh hàng loạt sẽ trả về lỗi NewResourceCreationError.DUPLICATE_TEMP_IDS.

Ví dụ về tải trọng

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 lô công việc duy nhấ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ụ về JSON REST sau đây (các trường tài nguyên bắt buộc khác bị 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 chi tiết 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ác lô công việc

Vì các thao tác tiêu chuẩn trong một tác vụ hàng loạt sẽ 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 lô công việc 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ụ: truyền mã tạm thời âm trong AdGroupCriterionOperation.remove khi gọi AddBatchJobOperations sẽ trả về RequestError.RESOURCE_NAME_MALFORMED.