Khẩu trang tại chỗ

Trong API Google Ads, quá trình cập nhật được thực hiện bằng cách sử dụng mặt nạ trường. Danh sách mặt nạ trường tất cả các trường mà bạn dự định thay đổi trong bản cập nhật và mọi trường được chỉ định không có trong mặt nạ trường sẽ bị bỏ qua, ngay cả khi được gửi đến máy chủ. Bạn có thể tạo mặt nạ trường theo cách thủ công, bằng cách tạo một Google\Protobuf\FieldMask! tạo một mảng điền sẵn tên của tất cả các trường mà bạn dự định thay đổi, rồi gán mã đó vào trường đường dẫn của mặt nạ trường.

Bạn cũng có thể dùng tiện ích mặt nạ trường tích hợp sẵn của chúng tôi (FieldMasks), ẩn nhiều thông tin cụ thể và cho phép bạn tạo trường mặt nạ tự động bằng cách giám sát những thay đổi bạn thực hiện đối với các trường của thực thể.

Dưới đây là ví dụ về cách cập nhật chiến dịch:

    $campaign = new Campaign([
        'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
        'status' => CampaignStatus::PAUSED
    ]);

    $campaignOperation = new CampaignOperation();
    $campaignOperation->setUpdate($campaign);
    $campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

Trước tiên, mã này sẽ tạo đối tượng Chiến dịch và sau đó đặt tên tài nguyên bằng cách sử dụng ResourceNames để API biết chiến dịch nào đang được đã cập nhật. status cũng được đặt thành PAUSED.

Sau đó, mã này sẽ tạo một đối tượng CampaignOperation và đặt giá trị đã tạo chiến dịch vào nhóm quảng cáo đó. Sau đó, Chrome sẽ sử dụng FieldMasks::allSetFieldsOf() để tạo mặt nạ trường cho chiến dịch bằng cách sử dụng tất cả các trường đã thay đổi. Cuối cùng, chuyển mặt nạ được trả về đến đối tượng hoạt động chiến dịch.

Lưu ý rằng FieldMasks::allSetFieldsOf là một phương thức thuận tiện để FieldMasks::compare(). Phương thức này so sánh đối tượng đã truyền với một đối tượng trống trong cùng một lớp. Cho Ví dụ: trong mã trước đó, bạn có thể đã sử dụng FieldMasks::compare(new Campaign(), $campaign) thay vì allSetFieldsOf().

Cập nhật các trường thông báo và trường phụ của các trường đó

Các trường MESSAGE có thể có các trường phụ (chẳng hạn như MaximizeConversions có 3 thuộc tính: target_cpa_micros, cpc_bid_ceiling_micros và cpc_bid_floor_micros) hoặc không thể không có (chẳng hạn như ManualCpm).

Trường thông báo không có trường phụ được xác định

Khi cập nhật trường MESSAGE không được xác định bằng bất kỳ trường phụ nào, hãy sử dụng FieldMasks để tạo mặt nạ trường, như mô tả trước đó.

Trường thông báo có trường phụ được xác định

Khi cập nhật trường MESSAGE được xác định bằng các trường phụ không có cài đặt rõ ràng bất kỳ trường phụ nào trên thông báo đó, bạn phải tự mình thêm từng trường con MESSAGE có thể thay đổi vào FieldMask, tương tự như ví dụ trước về việc tạo một mặt nạ trường từ đầu.

Một ví dụ phổ biến là cập nhật chiến lược đặt giá thầu của chiến dịch mà không đặt của các trường trên chiến lược đặt giá thầu mới. Mã dưới đây minh hoạ cách hãy cập nhật chiến dịch để sử dụng MaximizeConversions chiến lược đặt giá thầu mà không cần thiết lập bất kỳ trường phụ nào trong chiến lược đặt giá thầu.

Trong trường hợp này, việc sử dụng phương thức allSetFieldsOf() và compare() của phương thức FieldMasks không đạt được mục tiêu.

Mã sau đây sẽ tạo một mặt nạ trường bao gồm maximize_conversions. Tuy nhiên, API Google Ads không cho phép hành vi này để ngăn chặn vô tình xoá các trường và tạo ra FieldMaskError.FIELD_HAS_SUBFIELDS .

Cảnh báo: Mã sau đây tạo ra lỗi.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions()
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. The field mask will include 'maximize_conversions`,
// which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that will result in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

Mã sau đây minh hoạ cách cập nhật chiến dịch đúng cách để sử dụng MaximizeConversions chiến lược đặt giá thầu mà không đặt bất kỳ trường phụ nào.

Thành công: Đoạn mã bên dưới đã cập nhật thành công chiến lược đặt giá thầu của chiến dịch.

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Creates a field mask from the existing campaign and adds all of the mutable
// fields (only one in this case) on the MaximizeConversions bidding strategy to
// the field mask. Because this field is included in the field mask but
// excluded from the campaign object, the Google Ads API will set the campaign's
// bidding strategy to a MaximizeConversions object without any of its subfields
// set.
fieldMask = FieldMasks::allSetFieldsOf($campaign);
// Only include 'maximize_conversions.target_cpa_micros' in the field mask
// as it is the only mutable subfield on MaximizeConversions when used as a
// standard bidding strategy.
//
// Learn more about standard and portfolio bidding strategies here:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified fields.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

Xoá trường

Bạn có thể xoá một số trường một cách rõ ràng. Tương tự như ví dụ trước, bạn phải thêm rõ ràng các trường này vào mặt nạ trường. Ví dụ: giả sử bạn có một chiến dịch sử dụng chiến lược đặt giá thầu MaximizeConversions và chiến dịch Trường target_cpa_micros được đặt với giá trị lớn hơn 0.

Đoạn mã sau đây chạy; tuy nhiên, maximize_conversions.target_cpa_micros sẽ không được thêm vào mặt nạ trường nên sẽ không có thay đổi nào đối với Trường target_cpa_micros:

Cảnh báo: Mã này không gây ra lỗi, nhưng target_cpa_micros của chiến lược đặt giá thầu MaximizeConversions sẽ không bị xoá.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId),
    'maximize_conversions' => new MaximizeConversions(['target_cpa' => 0]),
    'status' => CampaignStatus::PAUSED
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask will NOT include
// 'maximize_conversions.target_cpa_micros'.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask(FieldMasks::allSetFieldsOf($campaign));

// Sends the operation in a mutate request that will succeed but will NOT update
// the 'target_cpa_micros' field because
// 'maximize_conversions.target_cpa_micros' was not included in the field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns($customerId, [$campaignOperation]);

Mã sau đây minh hoạ cách xoá target_cpa_micros đúng cách trên chiến lược đặt giá thầu MaximizeConversions.

Thành công: Mã sau đây không xoá target_cpa_micros.

// Creates a Campaign object with the proper resource name.
$campaign = new Campaign([
    'resource_name' => ResourceNames::forCampaign($customerId, $campaignId)
]);

// Constructs a field mask from the existing campaign and adds the
// 'maximize_conversions.target_cpa_micros' field to the field mask, which will
// clear this field from the bidding strategy without impacting any other fields
// on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->setPaths(array_merge(
    iterator_to_array($fieldMask->getPaths()->getIterator()),
    ['maximize_conversions.target_cpa_micros']
));

// Creates an operation to update the campaign with the specified field.
$campaignOperation = new CampaignOperation();
$campaignOperation->setUpdate($campaign);
$campaignOperation->setUpdateMask($fieldMask);

Lưu ý rằng giá trị "không chính xác" mã có hoạt động như dự kiến cho các trường được xác định dưới dạng optional trong API Google Ads protocol buffers. Nhưng vì target_cpa_micros không phải là trường optional, trường "không chính xác" mã này không cập nhật để xoá trường target_cpa.

Lưu ý quan trọng: Nếu bạn muốn xoá một trường, thì cách an toàn nhất là hãy thêm trường đó vào mặt nạ trường.