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

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

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

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

מגבלות על השימוש

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

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

דוגמה למטען ייעודי

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

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