שינוי של שירות המשאב

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

נקודות קצה (endpoints) לשינוי נתונים

לכל משאב שניתן לשינוי יש שירות וסוג פעולה תואמים. כדי לשנות משאב באמצעות השירות הייעודי שלו, מאכלסים את אחד מהשדות הבאים בפעולה ושולחים אותה לנקודת הקצה (endpoint) של השירות:

• ‫Create (create): אובייקט משאב חדש שרוצים ליצור.
• עדכון (update): אובייקט המשאב ששונה, בצירוף update_mask שמציין את השדות שהשתנו.
• ‫Remove (remove): המחרוזת resource_name של משאב המטרה שרוצים להסיר.

לדוגמה, כדי ליצור Campaign חדש:

1. יוצרים אובייקט Campaign עם המאפיינים שבחרתם.
2. מקצים אותו לשדה create של CampaignOperation.
3. שולחים את הפעולה ב-MutateCampaignsRequest אל CampaignService.MutateCampaigns.

התבנית הזו חלה על כל השירותים הספציפיים למשאבים ב-Google Ads API:

• ‫AdGroup: מעבירים AdGroupOperation אל AdGroupService.MutateAdGroups.
• ‫CampaignCriterion: מעבירים את CampaignCriterionOperation אל CampaignCriterionService.MutateCampaignCriteria.

המטען הייעודי (payload) הבא של REST JSON ממחיש בקשה אל CampaignService.MutateCampaigns:

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

פעולות מרובות ומגבלות

רוב הבקשות לשינוי נתונים של משאב ספציפי מקבלות שדה operations חוזר, כך שבקשה אחת יכולה להכיל כמה פעולות לאותו סוג משאב (עד 10,000 פעולות לכל בקשה, או 20,000 ל-AdGroupCriterionService.MutateAdGroupCriteria; CustomerService.MutateCustomer מקבלת שדה operation יחיד). כברירת מחדל, כל הפעולות בבקשה מבוצעות באופן אטומי, אלא אם השירות תומך ב-partial_failure והגדרתם אותו ל-true.

עם זאת, לשירותי משאבים נפרדים יש שתי מגבלות חשובות:

• סוג משאב יחיד: בקשה לשירות משאבים יכולה לשנות רק משאבים שמנוהלים על ידי אותו שירות ספציפי.
• אין מזהים זמניים בין משאבים: מכיוון שקריאת mutate ספציפית למשאב מקבלת רק סוג משאב אחד, אי אפשר להקצות מזהה שלילי זמני למשאב הורה (כמו customers/CUSTOMER_ID/campaigns/-1) ולהפנות אליו ממשאב צאצא מסוג אחר (כמו AdGroup) באותה בקשה. (מזהים זמניים עם הפניה עצמית באותו סוג משאב נתמכים בעצים היררכיים, כמו קבוצות של כרטיסי מוצר ב-AdGroupCriterion וצמתים ב-AssetGroupListingGroupFilter).

אם אתם צריכים לשנות כמה סוגי משאבים בבקשה אחת או להפנות לשמות זמניים של משאבים בסוגי משאבים שונים, השתמשו במקום זאת ב-GoogleAdsService.Mutate.

הבדלים בין הגרסאות

כשמשנים משאבים, חשוב לזכור את ההבדל הבא בין הגרסאות הנתמכות של Google Ads API:

• שירותים של יעדים שקשורים למחזור החיים של הלקוח: היעדים של שימור לקוחות משתנים בכל הגרסאות הנתמכות דרך GoalService.MutateGoals (retention_goal_settings) ו-CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings) באמצעות שדה operations חוזר רגיל. בגרסה 25 ואילך, גם היעדים "צירוף לקוחות חדשים" (new_customer_acquisition_goal_settings / campaign_new_customer_acquisition_settings) ו"שימור לקוחות נאמנים" (loyalty_retention_goal_settings / campaign_loyalty_retention_settings) משתנים באמצעות GoalService.MutateGoals ו-CampaignGoalConfigService.MutateCampaignGoalConfigs. השדה הזה מחליף את השדות CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals ו-CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals, שמשמשים לצירוף לקוחות חדשים בגרסאות v23 ו-v24 ומקבלים שדה operation יחיד.