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

در Google Ads API، به روز رسانی ها با استفاده از یک فیلد ماسک انجام می شود. فیلد ماسک تمام فیلدهایی را که می‌خواهید با به‌روزرسانی تغییر دهید فهرست می‌کند و هر فیلد مشخص شده که در فیلد ماسک نیست نادیده گرفته می‌شود، حتی اگر به سرور ارسال شود.

FieldMaskUtil

روش توصیه شده برای تولید ماسک‌های فیلد استفاده از ابزار ماسک فیلد داخلی ما است که به شما امکان می‌دهد به جای ساختن آن‌ها از ابتدا، ماسک‌های فیلد را از یک شی تغییر یافته تولید کنید.

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

// Creates a Campaign object with the proper resource name and any other changes.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that will update the campaign, using the FieldMasks'
// allSetFieldsOf utility to derive the update mask. This mask tells the Google
// Ads API which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

این مثال ابتدا یک شی Campaign خالی ایجاد می کند و سپس نام منبع آن را تنظیم می کند تا API بداند کدام کمپین در حال به روز رسانی است.

این مثال از متد FieldMasks.allSetFieldsOf() در کمپین استفاده می کند تا به طور خودکار یک فیلد ماسک تولید کند که تمام فیلدهای مجموعه را شمارش می کند. سپس می توانید ماسک برگشتی را مستقیماً به تماس به روز رسانی منتقل کنید.

اگر برای به روز رسانی چند فیلد نیاز به کار با یک شی موجود دارید، می توانید کد را به صورت زیر تغییر دهید:

Campaign existingCampaign;

// Obtains existingCampaign from elsewhere.
...

// Creates a new campaign based off the existing campaign and updates the
// campaign by setting its status to paused.
Campaign campaignToUpdate =
    existingCampaign.toBuilder()
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation that will update the campaign, using the FieldMasks'
// compare utility to derive the update mask. This mask tells the Google Ads API
// which attributes of the campaign you want to change.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaignToUpdate)
        .setUpdateMask(FieldMasks.compare(existingCampaign, campaignToUpdate))
        .build();

// Sends the operation in a mutate request.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

برای ایجاد یک فیلد ماسک از ابتدا، ابتدا یک شی FieldMask ایجاد می‌کنید، سپس نام هر یک از فیلدهایی را که می‌خواهید تغییر دهید به شی اضافه کنید.

FieldMask fieldMask =
    FieldMask.newBuilder()
        .addPaths("status")
        .addPaths("name")
        .build();

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

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

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

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

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

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

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

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

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

هشدار: کد زیر یک خطا ایجاد می کند.

// Creates a campaign with the proper resource name and an empty
// MaximizeConversions field.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .setMaximizeConversions(MaximizeConversions.newBuilder().build())
    .build();

// 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 operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// 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.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

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

// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .build();

// 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 fieldMask = FieldMasks.allSetFieldsOf(campaign)
    .toBuilder()
    // 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
    .addPaths("maximize_conversions.target_cpa_micros")
    .build();

// Creates an operation to update the campaign with the specified fields.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask)
        .build();

پاکسازی فیلدها

برخی از فیلدها را می توان به صراحت پاک کرد. مشابه مثال بالا، شما باید به صراحت این فیلدها را به فیلد ماسک اضافه کنید. به عنوان مثال، فرض کنید کمپینی دارید که از استراتژی پیشنهاد قیمت 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 campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpa(0).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// 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 operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// 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.
MutateCampaignsResponse response =
    campaignServiceClient.mutateCampaigns(
        customerId.toString(), Collections.singletonList(operation));

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

موفقیت: کد زیر target_cpa_micros را پاک می کند.

// Creates a Campaign object with the proper resource name.
Campaign campaign = Campaign.newBuilder()
    .setResourceName(ResourceNames.campaign(customerId, campaignId))
    .build();

// 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 fieldMask = FieldMasks.allSetFieldsOf(campaign)
    .toBuilder()
    .addPaths("maximize_conversions.target_cpa_micros")
    .build();

// Creates an operation to update the campaign with the specified field.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(fieldMask))
        .build();

توجه داشته باشید که مثال "نادرست" بالا برای فیلدهایی که به عنوان optional در protocol buffers Google Ads API تعریف شده اند، همانطور که در نظر گرفته شده است، کار می کند. اما از آنجایی که target_cpa_micros یک فیلد optional نیست، مثال "نادرست" استراتژی مناقصه را برای پاک کردن فیلد target_cpa به روز نمی کند.

نکته کلیدی: اگر قصد شما پاک کردن یک فیلد است، مطمئن ترین راه برای دستیابی به این هدف این است که صریحاً آن فیلد را به ماسک فیلد اضافه کنید.