Method: customers.googleAds.mutate

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

השיטה הזו היא בעצם מעטפת סביב סדרה של שיטות mutate. התכונות היחידות שהשיטה הזו מציעה בהשוואה לקריאה ישירה ל-methods האלה הן:

  • עסקאות אטומיות
  • שמות של משאבים זמניים (מתוארים בהמשך)
  • זמן אחזור קצר יותר במעט בהשוואה לביצוע סדרה של קריאות mutate

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

היתרונות של עסקאות אטומיות

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

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

שמות של משאבים זמניים הם סוג מיוחד של שם משאב שמשמש ליצירת משאב ולהפניה למשאב הזה באותה בקשה. לדוגמה, אם נוצר תקציב קמפיין עם resourceName שווה ל-customers/123/campaignBudgets/-1, אפשר לעשות שימוש חוזר בשם המשאב הזה בשדה Campaign.budget באותה בקשה. כך שני המשאבים נוצרים ומקושרים באופן אטומי.

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

הערה:

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

זמן אחזור

חשוב לקבץ את השינויים לפי סוג המשאב, אחרת יכול להיות שהבקשה תסתיים בזמן קצוב ותיכשל. זמן האחזור שווה בערך לסדרה של קריאות לשיטות בודדות של שינוי (mutate), כאשר כל שינוי בסוג המשאב הוא קריאה חדשה. לדוגמה, ביצוע מוטציה ב-10 קמפיינים ואז ב-10 קבוצות מודעות זה כמו 2 קריאות, ואילו ביצוע מוטציה בקמפיין אחד, בקבוצת מודעות אחת, בקמפיין אחד ובקבוצת מודעות אחת זה כמו 4 קריאות.

רשימת השגיאות שהמערכת זרקה: AdCustomizerError AdError AdGroupAdError AdGroupCriterionError AdGroupError AssetError AuthenticationError AuthorizationError BiddingError CampaignBudgetError CampaignCriterionError CampaignError CampaignExperimentError CampaignSharedSetError CollectionSizeError ContextError ConversionActionError CriterionError CustomerFeedError DatabaseError DateError DateRangeError DistinctError ExtensionFeedItemError ExtensionSettingError FeedAttributeReferenceError FeedError FeedItemError FeedItemSetError FieldError FieldMaskError FunctionParsingError HeaderError ImageError InternalError

בקשת HTTP

POST https://googleads.googleapis.com/v19/customers/{customerId}/googleAds:mutate

כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.

פרמטרים של נתיב

פרמטרים
customerId

string

חובה. המזהה של הלקוח שהמשאבים שלו משתנים.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
שדות
mutateOperations[]

object (MutateOperation)

חובה. רשימת הפעולות לביצוע במשאבים ספציפיים.
partialFailure

boolean

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

boolean

אם הערך הוא true, הבקשה מאומתת אבל לא מבוצעת. המערכת מחזירה רק שגיאות, לא תוצאות.
responseContentType

enum (ResponseContentType)

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

גוף התשובה

הודעת התשובה עבור GoogleAdsService.Mutate.

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
שדות
partialFailureError

object (Status)

שגיאות שקשורות לכשלים בפעולות במצב של כשל חלקי. הפונקציה מחזירה את הערך הזה רק אם partialFailure = true וכל השגיאות מתרחשות בתוך הפעולות. אם יצוצו שגיאות מחוץ לפעולות (לדוגמה, שגיאות אימות), אנחנו מחזירים שגיאה ברמת ה-RPC.
mutateOperationResponses[]

object (MutateOperationResponse)

כל התשובות של ה-mutate.

היקפי הרשאה

נדרש היקף הרשאות OAuth הבא:

  • https://www.googleapis.com/auth/adwords

מידע נוסף זמין בOAuth 2.0 Overview.