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

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

BatchJobService תומך בשמות זמניים של משאבים שאפשר להפנות אליהם בפעולות הבאות באותו BatchJob, כולל בכמה בקשות 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 (כשל חלקי) מופעלת (למעט בתוך atomic sub-batches), אם משאב אב עם מזהה זמני לא עובר אימות, כל פעולות הצאצא התלויות שמפנות למזהה הזמני הזה נכשלות עם NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS. אם משתמשים באותו מזהה שלילי בכמה פעולות של create באותו BatchJob, מוחזרת השגיאה NewResourceCreationError.DUPLICATE_TEMP_IDS. מזהים זמניים תקפים רק כשיוצרים משאבים (create) או כשמפנים למשאבי אב חדשים שנוצרו. לדוגמה, העברת מזהה זמני שלילי ב-AdGroupCriterionOperation.remove כשמתקשרים אל AddBatchJobOperations מחזירה RequestError.RESOURCE_NAME_MALFORMED.