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

در API گوگل ادز، به‌روزرسانی‌ها با استفاده از یک ماسک فیلد انجام می‌شوند. ماسک فیلد ( google.protobuf.FieldMask ) شامل فهرستی از مسیرهای فیلد در snake_case است که قصد دارید با به‌روزرسانی تغییر دهید. هر فیلد مشخص شده‌ای که در ماسک فیلد نباشد، حتی اگر به سرور ارسال شود، نادیده گرفته می‌شود.

ابزار FieldMasks

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

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

// 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 updates 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() را در کمپین فراخوانی می‌کند تا به طور خودکار یک ماسک فیلد ایجاد کند که تمام فیلدهای تنظیم شده را شمارش می‌کند. می‌توانید ماسک برگشتی را مستقیماً به فراخوانی به‌روزرسانی ارسال کنید.

اگر نیاز دارید با یک شیء موجود کار کنید و چند فیلد را به‌روزرسانی کنید، FieldMasks.compare() به صورت زیر استفاده کنید:

// Assumes existingCampaign was retrieved from a previous API call.

// Creates a new campaign based on 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 updates 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 ایجاد کنید و نام snake_case هر فیلدی را که قصد تغییر آن را دارید، اضافه کنید:

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

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

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

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

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

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

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

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

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

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

هشدار: کد زیر خطای 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 FieldMasks.allSetFieldsOf to derive the update
// mask. The field mask includes 'maximize_conversions', which produces 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 results in a
// FieldMaskError.FIELD_HAS_SUBFIELDS error because empty MESSAGE fields with
// subfields cannot be included directly 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 campaign and adds the mutable subfield
// ('maximize_conversions.target_cpa_micros') on the MaximizeConversions
// bidding strategy to the field mask. Because this subfield is included in the
// field mask while excluded from the campaign object, the Google Ads API
// switches the campaign's bidding strategy oneof to MaximizeConversions with
// target_cpa_micros unset.
FieldMask fieldMask =
    FieldMasks.allSetFieldsOf(campaign).toBuilder()
        .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 در استراتژی پیشنهاد قیمت MaximizeConversions پاک نمی‌کند.

// Creates a campaign with the proper resource name and a MaximizeConversions
// object with target_cpa_micros set to 0L.
Campaign campaign =
    Campaign.newBuilder()
        .setResourceName(ResourceNames.campaign(customerId, campaignId))
        .setMaximizeConversions(
            MaximizeConversions.newBuilder().setTargetCpaMicros(0L).build())
        .setStatus(CampaignStatus.PAUSED)
        .build();

// Constructs an operation using FieldMasks.allSetFieldsOf to derive the
// update mask.
CampaignOperation operation =
    CampaignOperation.newBuilder()
        .setUpdate(campaign)
        .setUpdateMask(FieldMasks.allSetFieldsOf(campaign))
        .build();

// Sends the operation in a mutate request that does not clear the field
// cleanly.
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 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 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();

نکته کلیدی: اگر قصد دارید فیلدی را پاک کنید، مسیر آن فیلد را به صراحت به FieldMask اضافه کنید و فیلد را روی شیء منبع بدون تنظیم رها کنید.