ماسک های میدانی

در API گوگل ادز، به‌روزرسانی‌ها با استفاده از یک ماسک فیلد انجام می‌شوند. ماسک فیلد تمام فیلدهایی را که قصد دارید با به‌روزرسانی تغییر دهید، فهرست می‌کند و هر فیلد مشخصی که در ماسک فیلد نباشد، حتی اگر به سرور ارسال شود، نادیده گرفته می‌شود. می‌توانید با ایجاد یک FieldMask ( Google\Protobuf\FieldMask )، ایجاد آرایه‌ای با نام تمام فیلدهایی که قصد تغییر آنها را دارید و سپس اختصاص آن آرایه به فیلد paths ماسک فیلد، یک ماسک فیلد به صورت دستی ایجاد کنید.

همچنین می‌توانید از ابزار ماسک فیلد داخلی ما ( FieldMasks ) استفاده کنید که بسیاری از جزئیات خاص را پنهان می‌کند و به شما امکان می‌دهد با بررسی تغییراتی که در فیلدهای موجودیت ایجاد می‌کنید، ماسک‌های فیلد را به طور خودکار ایجاد کنید.

در اینجا مثالی برای به‌روزرسانی یک کمپین آورده شده است:

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

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

این کد ابتدا یک شیء Campaign ایجاد می‌کند و سپس نام منبع آن را با استفاده از ResourceNames تنظیم می‌کند، به طوری که API بداند کدام کمپین در حال به‌روزرسانی است. status نیز روی CampaignStatus::PAUSED تنظیم شده است.

سپس کد یک شیء CampaignOperation ایجاد می‌کند و کمپین ایجاد شده قبلی را روی آن تنظیم می‌کند. پس از آن، از FieldMasks::allSetFieldsOf() برای ایجاد یک ماسک فیلد برای کمپین با شمارش تمام فیلدهای اصلاح شده استفاده می‌کند. در نهایت، ماسک برگردانده شده را به شیء عملیات کمپین ارسال می‌کند.

توجه داشته باشید که FieldMasks::allSetFieldsOf() یک متد کمکی برای FieldMasks::compare() است. این متد شیء ارسالی شما را با یک شیء خالی از همان کلاس مقایسه می‌کند. برای مثال، در کد قبلی، می‌توانستید به جای FieldMasks::compare(new Campaign(), $campaign) از FieldMasks::allSetFieldsOf($campaign) استفاده کنید.

به‌روزرسانی فیلدهای پیام و زیرفیلدهای آنها

فیلدهای MESSAGE می‌توانند زیرفیلد داشته باشند (مانند MaximizeConversions که شامل زیرفیلدهایی مانند target_cpa_micros ، cpc_bid_ceiling_micros و cpc_bid_floor_micros می‌شود)، یا می‌توانند اصلاً هیچ زیرفیلدی نداشته باشند (مانند ManualCpm ).

فیلدهای پیام بدون زیرفیلد تعریف‌شده

هنگام به‌روزرسانی فیلد MESSAGE که با هیچ زیرفیلدی تعریف نشده است، FieldMasks برای تولید ماسک فیلد، همانطور که قبلاً توضیح داده شد، استفاده کنید.

فیلدهای پیام با زیرفیلدهای تعریف‌شده

هنگام به‌روزرسانی یک فیلد MESSAGE که با زیرفیلدهایی تعریف شده است، بدون تنظیم صریح هیچ یک از زیرفیلدهای آن پیام، باید هر یک از زیرفیلدهای قابل تغییر MESSAGE را به صورت دستی به FieldMask اضافه کنید، مشابه مثال قبلی که یک ماسک فیلد را از ابتدا ایجاد کرد.

یک مثال رایج، به‌روزرسانی استراتژی پیشنهاد قیمت یک کمپین بدون تنظیم هیچ یک از فیلدهای استراتژی پیشنهاد قیمت جدید است. کد زیر نحوه به‌روزرسانی یک کمپین برای استفاده از استراتژی پیشنهاد قیمت MaximizeConversions بدون تنظیم هیچ یک از زیرفیلدهای استراتژی پیشنهاد قیمت نشان می‌دهد.

در این حالت، استفاده از متدهای allSetFieldsOf() و compare() از FieldMasks به هدف مورد نظر نمی‌رسد.

کد زیر یک ماسک فیلد ایجاد می‌کند که شامل maximize_conversions می‌شود. با این حال، API گوگل ادز برای جلوگیری از پاک شدن تصادفی فیلدها، این رفتار را مجاز نمی‌داند و خطای FieldMaskError.FIELD_HAS_SUBFIELDS را ایجاد می‌کند.

هشدار: کد زیر خطا تولید می‌کند.

// 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 includes 'maximize_conversions',
// which produces 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 results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields cannot
// be included in a field mask.
$campaignServiceClient = $googleAdsClient->getCampaignServiceClient();
$response = $campaignServiceClient->mutateCampaigns(
    MutateCampaignsRequest::build($customerId, [$campaignOperation])
);

کد زیر نحوه به‌روزرسانی صحیح یک کمپین برای استفاده از استراتژی پیشنهاد قیمت MaximizeConversions بدون تنظیم هیچ یک از زیرفیلدهای آن نشان می‌دهد.

موفقیت: کد زیر با موفقیت استراتژی پیشنهاد قیمت کمپین را به‌روزرسانی می‌کند.

// 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 the mutable
// subfield 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 sets 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:
// https://developers.google.com/google-ads/api/docs/campaigns/bidding/assign-strategies
$fieldMask->getPaths()[] = '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);

پاک کردن فیلدها

برخی از فیلدها را می‌توان به طور صریح پاک کرد. مشابه مثال قبلی، شما باید این فیلدها را به طور صریح به ماسک فیلد اضافه کنید زیرا FieldMasks فیلدهای اسکالر Proto3 را که روی مقادیر پیش‌فرض خود (مانند 0 ، false یا "" ) تنظیم شده‌اند، نادیده می‌گیرد. به عنوان مثال، فرض کنید کمپینی دارید که از استراتژی پیشنهاد قیمت MaximizeConversions استفاده می‌کند و فیلد target_cpa_micros با مقداری بزرگتر از 0 تنظیم شده است.

کد زیر اجرا می‌شود؛ با این حال، maximize_conversions.target_cpa_micros به ماسک فیلد اضافه نمی‌شود و بنابراین هیچ تغییری در فیلد target_cpa_micros ایجاد نمی‌شود:

هشدار: این کد خطایی ایجاد نمی‌کند، اما فیلد target_cpa_micros از استراتژی پیشنهاد قیمت MaximizeConversions پاک نمی‌شود.

// 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_micros' => 0
    ]),
    'status' => CampaignStatusEnum\CampaignStatus::PAUSED
]);

// Constructs an operation, using the FieldMasks' allSetFieldsOf utility to
// derive the update mask. However, the field mask does 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 succeeds, but does 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(
    MutateCampaignsRequest::build($customerId, [$campaignOperation])
);

کد زیر نحوه‌ی صحیح پاک کردن فیلد target_cpa_micros در استراتژی پیشنهاد قیمت MaximizeConversions را نشان می‌دهد.

موفقیت: کد زیر فیلد 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
// clears this field from the bidding strategy without impacting any other
// fields on the bidding strategy.
$fieldMask = FieldMasks::allSetFieldsOf($campaign);
$fieldMask->getPaths()[] = '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);

توجه داشته باشید که تنظیم مقدار پیش‌فرض برای فیلدهایی که در بافرهای پروتکل API گوگل ادز به عنوان optional تعریف شده‌اند، همانطور که در نظر گرفته شده است، کار می‌کند. با این حال، از آنجا که target_cpa_micros یک فیلد optional نیست، تنظیم آن روی 0 بدون اضافه کردن صریح مسیر به ماسک فیلد، استراتژی پیشنهاد قیمت را برای پاک کردن target_cpa_micros به‌روزرسانی نمی‌کند .

نکته کلیدی: اگر قصد دارید فیلدی را پاک کنید، امن‌ترین راه این است که آن فیلد را به صراحت به field mask اضافه کنید.