שימוש במזהים זמניים

שמות זמניים של משאבים

BatchJobService תומך בשמות זמניים של משאבים שאפשר להפנות אליהם בפעולות הבאות באותו batch job, כולל בכמה בקשות AddBatchJobOperations עוקבות שמועלות באמצעות sequence_token. כך אפשר ליצור קמפיין ואת קבוצות המודעות, המודעות והקריטריונים שתלויים בו במשימת אצווה אחת, לפני שמוקצים מזהים בצד השרת. בכללי האצבע ובדוגמה הבאים, בקשה אחת מתייחסת לכל BatchJob בכל ההעלאות של AddBatchJobOperations.

כדי להפנות למשאב חדש שנוצר באותה בקשה לשינוי נתונים או באותו batch job, צריך לציין מזהה של מספר שלם שלילי (כמו -1 או -2, לא כולל 0) בשדה resource_name של המשאב החדש. לדוגמה, כשיוצרים קמפיין בבקשת Batch, מגדירים את שם המשאב שלו בתור customers/CUSTOMER_ID/campaigns/-1. כשיוצרים קבוצת מודעות בפעולה מאוחרת יותר באותה בקשה, צריך להפנות אל customers/CUSTOMER_ID/campaigns/-1 כקמפיין ההורה. ה-API מחליף באופן אוטומטי את -1 במזהה הקמפיין שנוצר בפועל.

מגבלות שימוש

כשמשתמשים בשמות זמניים של משאבים, חשוב לזכור את הכללים הבאים:

• הסדר חשוב: אפשר להפנות לשם זמני של משאב רק אחרי שמגדירים אותו. ברשימת פעולות, הפעולה התלויה (כמו יצירת קבוצת מודעות) חייבת להופיע אחרי הפעולה שיוצרת את משאב ההורה שלה (כמו יצירת קמפיין).
• היקף של בקשה אחת או של משימה באצווה: שמות זמניים של משאבים לא נשמרים בין משימות נפרדות או בקשות לשינוי נתונים. כדי להפנות למשאב שנוצר במשימה קודמת או בבקשה קודמת לשינוי נתונים, צריך להשתמש בשם המשאב שנוצר בפועל על ידי המערכת.
• ייחודיות גלובלית: בכל משימה או בקשה לשינוי נתונים, לכל שם זמני של משאב צריך להיות מספר שלם שלילי ייחודי בכל סוגי המשאבים. לדוגמה, אי אפשר להקצות את -1 גם לקמפיין וגם לקבוצת מודעות באותה בקשה. אם תשתמשו שוב במזהה זמני באותה בקשה או באותה משימה באצווה, תוחזר השגיאה NewResourceCreationError.DUPLICATE_TEMP_IDS.

דוגמה למטען ייעודי (payload)

נניח שאתם רוצים להוסיף קמפיין, קבוצת מודעות ומודעה בבקשת API אחת או במשימה באצווה. אפשר להגדיר את המערך mutateOperations במטען ייעודי (payload) של בקשת GoogleAdsService.Mutate או BatchJobService.AddBatchJobOperations, כמו בדוגמה הבאה של REST JSON (שדות משאבים נדרשים אחרים הושמטו כדי לקצר):

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

הדוגמה הזו ממחישה את הפרטים החשובים הבאים:

• קבוצת המודעות משתמשת במזהה זמני חדש (-2) כי המזהה -1 כבר הוקצה לקמפיין.
• קבוצת המודעות מפנה אל customers/CUSTOMER_ID/campaigns/-1 כדי לקשר את עצמה לקמפיין שנוצר בפעולה הקודמת.
• השדה adGroupAdOperation מפנה אל customers/CUSTOMER_ID/adGroups/-2 ומשמיט את resourceName כי אין פעולה נוספת בבקשה שמפנה למודעה החדשה.

טיפול בשגיאות במשימות באצווה

בפעולות רגילות ב-משימה באצווה, מופעלת האפשרות partial failure (למעט בתת-קבוצות אטומיות). לכן, אם משאב הורה עם מזהה זמני נכשל באימות, כל פעולות הצאצא התלויות שמפנות למזהה הזמני הזה נכשלות עם השגיאה NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. אם משתמשים שוב באותו מזהה שלילי בכמה פעולות של create באותה משימה באצווה, מוחזרת השגיאה NewResourceCreationError.DUPLICATE_TEMP_IDS. מזהים זמניים תקפים רק כשיוצרים משאבים (create) או כשמפנים למשאבי הורה חדשים שנוצרו. לדוגמה, העברת מזהה זמני שלילי ב-AdGroupCriterionOperation.remove כשקוראים ל-AddBatchJobOperations מחזירה את השגיאה RequestError.RESOURCE_NAME_MALFORMED.