Method: customers.googleAds.mutate

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

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

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

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

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

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

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

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

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

הערה:

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

זמן אחזור

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

< -C להתחיAdCustomizerErrorAdErrorAdGroupAdErrorAdGroupCriterionErrorAdGroupErrorAssetErrorAuthenticationErrorAuthorizationErrorBiddingErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

בקשת HTTP

POST https://googleads.googleapis.com/v14/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)

ההגדרה של סוג התוכן של התשובה. המדיניות הזו קובעת אם המערכת תחזיר את המשאב שניתן לשינוי או רק את שם המשאב אחרי השינוי. המשאב שניתן לשינוי יוחזר רק אם המשאב כולל את שדה התגובה המתאים. לדוגמה, MutateCampaignResult.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.