Method: customers.googleAds.mutate

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

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

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

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

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

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

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

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

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

הערה:

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

זמן אחזור

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

רשימת השגיאה{9 {9999 {שם {99תי{ת מסוימים { מסוימים {9913 את מהי הגדרת שגיאה{/80 {Error0 {900 {לדוגמהויוו { 999 {99999ייי הזכותי{ {9 { {9 {999יי מסוימים {9999919י מסוימים ביוםAdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של 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)

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

גוף התשובה

הודעת תשובה לגבי GoogleAdsService.Mutate.

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

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

object (Status)

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

object (MutateOperationResponse)

כל התגובות עבור השינוי.

היקפי הרשאות

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

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

למידע נוסף, עיינו בסקירה הכללית על OAuth 2.0.