מסכות שדה

ב-Google Ads API, העדכונים מתבצעים באמצעות אנונימיזציה של שדות. רשימת מסכות השדות כל השדות שבכוונתך לשנות בעדכון, וכל השדות שצוינו שלא מופיעים במסכת השדות, המערכת מתעלמת מהם, גם אם הם נשלחים לשרת.

הכלי FieldMasks

הדרך המומלצת ליצירת מסכות שדות היא להשתמש במסכת השדות המובנית שלנו חברת תשתיות (FieldMasks), שמאפשרת ליצור מסכות של שדות מאובייקט שעבר שינוי במקום ליצור מההתחלה.

דוגמה לעדכון קמפיין:

my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    status => PAUSED,
    networkSettings =>
      Google::Ads::GoogleAds::V17::Resources::NetworkSettings->new({
        targetSearchNetwork => "false"
      })
    });

my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

בדוגמה הזו קודם נוצר אובייקט Campaign על ידי הגדרת שם המשאב שלו באמצעות הכלי ResourceNames, כדי שה-API יידע הקמפיין שמתעדכן.

בדוגמה נשתמש FieldMasks::all_set_fields_of() בקמפיין כדי להפיק באופן אוטומטי מסכת שדות שמספורת את כל להגדיר שדות. לאחר מכן אפשר להעביר את המסכה שהוחזרה ישירות לשיחת העדכון.

FieldMasks::all_set_fields_of() היא שיטה נוחה עבור FieldMasks::field_mask(). היא משווה בין האובייקט שהעברתם לאובייקט ריק מאותה מחלקה. אז ב אפשר להשתמש גם בקוד שלמעלה

field_mask(Google::Ads::GoogleAds::V17::Resources::Campaign->new({}), $campaign)

במקום all_set_fields_of($campaign).

יצירת מסכה באופן ידני

כדי ליצור מסכת שדה מאפס, צריך קודם ליצור Google::Ads::GoogleAds::Common::FieldMask ואז ליצור הפניה למערך עם השמות של כל השדות שאתם מתכוונים לשנות, ולבסוף להקצות את ההפניה למערך מסיכת השדות שדה paths.

my $field_mask = Google::Ads::GoogleAds::Common::FieldMask->new({
    paths => ["status", "name"]
  });

עדכון שדות של אובייקטים ושדות המשנה שלהם

שדות אובייקט יכולים לכלול שדות משנה (כמו התג MaximizeConversions כולל 3: target_cpa_micros, cpc_bid_ceiling_micros ו-cpc_bid_floor_micros); או לא יכול להיות להם בכלל (למשל, ManualCpm).

שדות אובייקט ללא שדות משנה מוגדרים

שדה אובייקט ב-Perl מקביל ל-protobuf MESSAGE בלקוח ספריות שפועלות ב-gRPC. כשמעדכנים שדה אובייקט שלא מוגדר בכל שדה משנה, משתמשים בכלי FieldMasks כדי ליצור מסיכת שדות, שתוארו למעלה.

שדות אובייקט עם שדות משנה מוגדרים

כשמעדכנים שדה אובייקט שמוגדר עם שדות משנה בלי במפורש בהגדרה של אחד משדות המשנה בהודעה הזו, צריך להוסיף באופן ידני כל אחד משדות המשנה ניתן לשנות את שדות המשנה של האובייקט ל-FieldMask, בדומה לדוגמה שלמעלה שיוצרת מסכת שדה מאפס.

אחת הדוגמאות הנפוצות היא עדכון שיטת בידינג של קמפיין, בלי להגדיר השדות בשיטת הבידינג החדשה. הדוגמה הבאה ממחישה איך מעדכנים קמפיין כדי להשתמש שיטת בידינג MaximizeConversions בלי להגדיר אף אחד משדות המשנה בשיטת הבידינג.

במקרה הזה, באמצעות השיטות all_set_fields_of() ו-field_mask() של השירות FieldMasks לא משיג את המטרה הרצויה.

הדוגמה הבאה יוצרת אנונימיזציה של שדות שכוללת maximize_conversions עם זאת, Google Ads API לא מאפשר התנהגות כזו, כדי למנוע ניקוי בטעות של שדות ולהפיק FieldMaskError.FIELD_HAS_SUBFIELDS שגיאה.

אזהרה: הקוד הבא מייצר שגיאה.

# Creates a campaign with the proper resource name and an empty
# MaximizeConversions field.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName =>
      Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
        $customer_id, $campaign_id
      ),
    maximizeConversions =>
      Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new()
    });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask. The field mask will include 'maximize_conversions',
# which will produce a FieldMaskError.FIELD_HAS_SUBFIELDS error.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

# Sends the operation in a mutate request that will result in a
# FieldMaskError.FIELD_HAS_SUBFIELDS error because empty object fields cannot
# be included in a field mask.
my $response = $api_client->CampaignService()->mutate({
    customerId => $customer_id,
    operations => [$campaign_operation]
  });

הדוגמה הבאה ממחישה איך לעדכן קמפיין בצורה נכונה כדי להשתמש שיטת הבידינג MaximizeConversions בלי להגדיר אף אחד משדות המשנה שלה.

הצלחה: הקוד שבהמשך מעדכן בהצלחה את שיטת הבידינג של הקמפיין.

# Creates a campaign with the proper resource name.
my $campaign = Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    )
  });

# Creates a field mask from the existing campaign and adds all of the fields
# on the MaximizeConversions bidding strategy to the field mask. Because these
# fields are 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 with none of its subfields set.
# 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
my $field_mask = all_set_fields_of($campaign);
push @{$field_mask->{paths}}, "maximize_conversions.target_cpa_micros";

# Creates an operation to update the campaign with the specified fields.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => $field_mask
  });

ניקוי שדות

אפשר לנקות שדות באופן מפורש על ידי הוספתם למסכת השדות, כפי שמוצג למעלה, או על ידי הגדרת השדה לערך ריק או לא מוגדר. לדוגמה, נניח שיש לכם קמפיין שמוגדרת בו שיטת הבידינג MaximizeConversions ושהשדה target_cpa_micros מוגדר עם ערך שגדול מ- 0.

הצלחה: הקוד הבא מנקה את השדה target_cpa_micros.

# Creates a campaign with the proper resource name and a MaximizeConversions
# object with target_cpa_micros set to 0.
my $campaign =
  Google::Ads::GoogleAds::V17::Resources::Campaign->new({
    resourceName => Google::Ads::GoogleAds::V17::Utils::ResourceNames::campaign(
      $customer_id, $campaign_id
    ),
    maximizeConversions => Google::Ads::GoogleAds::V17::Resources::MaximizeConversions->new({
      targetCpaMicros => 0
    })
  });

# Constructs an operation, using the FieldMasks' all_set_fields_of utility to
# derive the update mask, which will include 'maximize_conversions.target_cpa_micros'.
my $campaign_operation =
  Google::Ads::GoogleAds::V17::Services::CampaignService::CampaignOperation->new({
    update     => $campaign,
    updateMask => all_set_fields_of($campaign)
  });

חשוב לזכור שאפשר להסיר שדות שכוללים שדות משנה בתוך שדות רק על ידי ניקוי של כל אחד מהערכים האלה. שדות המשנה הנפרדים, כמו שמוצג בשדות אובייקטים עם הגדרה שדות משנה.