מעבר מ-v1 ל-v2

עדכון אחרון: 6.12.2022

העברת האפליקציה שלך

כדי לעבור מגרסה 1 לגרסה 2, צריך לעדכן את כתובות ה-URL של נקודות הקצה לקריאה לגרסה 2. בנוסף, צריך לעדכן את האפליקציה כדי להביא בחשבון שינויים שעלולים לגרום לכשלים.

עדכון הקריאות ל-API מגרסה 1 לגרסה 2

כדי להשתמש ב-v2 במקום ב-v1, תצטרכו לעדכן את הבקשות לשימוש בנקודות קצה (endpoints) חדשות.

לדוגמה, כדי להפעיל את השיטה advertisers.get עם v1, צריך להשתמש בכתובת ה-URL הבאה:

GET https://displayvideo.googleapis.com/v1/advertisers/advertiserId

בגרסה 2, מעדכנים את כתובת ה-URL לכתובת הבאה:

GET https://displayvideo.googleapis.com/v2/advertisers/advertiserId

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

צריך לבצע את השינויים הנדרשים

הוספנו בגרסה 2 כמה שינויי תוכנה שעלולים לגרום לכשלים. עיינו בהוראות הבאות ובצעו את השינויים הנדרשים הרלוונטיים לשימוש הנוכחי שלכם ב-Display & Video 360 API.

עדכון השיחות לשיטות הטירגוט

• סוגי מיקוד מסוימים מוקצים כעת באמצעות ערכי 'טיפוסים בני מנייה (enum)' במקום באמצעות מזהי אפשרויות מיקוד. לדוגמה, מכשירי טאבלט מטורגטים עכשיו ישירות באמצעות טיפוסים בני מנייה (enum) DEVICE_TYPE_TABLET DeviceType, ולא באמצעות מזהה אפשרות הטירגוט בשירות targetingTypes.targetingOptions. גרסאות של מחרוזות מחרוזת של טיפוסים בני מנייה (enums) כאלה מיוצגות בשדה החדש assignedTargetingOptionIdAlias במשאבים האלה של AssignedTargetingOption, ואפשר להשתמש בהן כדי לאחזר או למחוק את הגדרות הטירגוט הקיים. הערך של assignedTargetingOptionId ב-AssignedTargetingOption המשאבים האלה לא השתנה.

  צריך לעדכן שיחות שמנהלות את סוגי הטירגוט הבאים כדי להשתמש בערכי 'טיפוסים בני מנייה (enum)':

  • TARGETING_TYPE_AGE_RANGE
  • TARGETING_TYPE_CONTENT_INSTREAM_POSITION
  • TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION
  • TARGETING_TYPE_DEVICE_TYPE
  • TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
  • TARGETING_TYPE_ENVIRONMENT
  • TARGETING_TYPE_EXCHANGE
  • TARGETING_TYPE_GENDER
  • TARGETING_TYPE_HOUSEHOLD_INCOME
  • TARGETING_TYPE_NATIVE_CONTENT_POSITION
  • TARGETING_TYPE_OMID
  • TARGETING_TYPE_PARENTAL_STATUS
  • TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
  • TARGETING_TYPE_VIDEO_PLAYER_SIZE
  • TARGETING_TYPE_VIEWABILITY

• השיטה advertisers.lineItems.bulkEditLineItemAssignedTargetingOptions הוחלפה בשיטה advertisers.lineItems.bulkEditAssignedTargetingOptions.

• השיטה advertisers.lineItems.bulkListLineItemAssignedTargetingOptions הוחלפה בשיטה advertisers.lineItems.bulkListAssignedTargetingOptions.

• צריך לעדכן את ההגדרות של ניהול השיחות TARGETING_TYPE_PROXIMITY_LOCATION_LIST כך שישתמשו בגודל רדיוס וביחידת מרחק שהוגדרו, במקום בערך 'טיפוסים בני מנייה (enum)' ProximityRadiusRange.

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

  כדי להשתמש בשמות החדשים של הקריאות, מומלץ לעשות זאת בדרכים הבאות:

  • advertisers.bulkEditAdvertiserAssignedTargetingOptions עד advertisers.editAssignedTargetingOptions
  • advertisers.bulkListAdvertiserAssignedTargetingOptions עד advertisers.listAssignedTargetingOptions
  • advertisers.campaigns.bulkListCampaignAssignedTargetingOptions עד advertisers.campaigns.listAssignedTargetingOptions
  • advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions אל advertisers.insertionOrders.listAssignedTargetingOptions
  • partners.bulkEditPartnerAssignedTargetingOptions עד partners.editAssignedTargetingOptions

עדכון השיחות לשירות advertisers.lineItems

• השדה inventorySourceIds הוסר. ניהול הקצאת מקור המלאי באמצעות AssignedTargetingOption משאבים של TARGETING_TYPE_INVENTORY_SOURCE.

• ערכי ה-enum הבאים של LineItemWarningMessage הוצאו משימוש בגרסה 2 ולא יופיעו יותר ב-LineItem.warningMessages:

  • NO_POSITIVE_AUDIENCE_LIST_TARGETED
  • APP_INSTALL_NO_CONVERSION_PIXEL
  • TARGETING_REVOKED_OR_CLOSED_USER_LIST
  • APP_INSTALL_NO_OPTIMAL_BIDDING_STRATEGY
  • CREATIVE_SIZE_NOT_IN_USE_FOR_TARGETED_DEALS
  • NO_CREATIVE_FOR_TARGETED_DEALS
  • TARGETING_DEPRECATED_GEO_TARGET

• השדה triggerId הוסר מהאובייקט LineItemFlight והערך LINE_ITEM_FLIGHT_DATE_TYPE_TRIGGER הוסר מה-enum מסוג LineItemFlightDateType. בגרסה 2 אין תמיכה בהגדרת פריטים להוצאה על סמך הפעלה של טריגרים ידניים.

עדכון השיחות לשירות customBiddingAlgorithms

השדות customBiddingAlgorithmState ו-modelReadiness הוחלפו בשדה modelDetails . השדה הזה מספק את מצבי מוּכנוּת וההשעיה של מודל האלגוריתם הקיים לכל מפרסם שיש לו גישה דרך רשימת אובייקטים של CustomBiddingModelDetails.

שינויים נוספים

בנוסף לשינויי התוכנה שפירטנו למעלה, V2 כולל גם תכונות חדשות.

התכונות שנוספו לגרסה 2 אחרי ההשקה הראשונית מופיעות בנתוני הגרסה שלנו.

הרשאת קריאה בלבד לפריטים ב-YouTube

בגרסה 2, אפשר לאחזר את הפריטים של YouTube ואת הגדרות הטירגוט שלהם באמצעות השירותים advertisers.lineItems ו-advertisers.lineItems.targetingTypes.assignedTargetingOptions, בהתאמה. ל-API יש הרשאת קריאה בלבד, כלומר כל ניסיון לכתיבה של בקשות שיישלחו לפריטים האלה יחזיר שגיאה. פריטי YouTube יהיו מאחד מהערכים הבאים של LineItemType:

• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_ACTION
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_AUDIO
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_NON_SKIPPABLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_REACH_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_SIMPLE_OVER_THE_TOP
• LINE_ITEM_TYPE_YOUTUBE_AND_PARTNERS_VIDEO_SEQUENCE

שיטות חדשות לשיפור הביצועים

בגרסה 2, השירות advertisers.lineItems מספק שיטות חדשות במקום בקשות מקובצות כדי לשפר את הביצועים ולצמצם את צריכת המכסות:

• באמצעות advertisers.lineItems.bulkUpdate אפשר להגדיר את אותם ערכי שדות לכמה פריטים. כרגע נתמכים רק עדכונים של השדה entityStatus.
• בעזרת advertisers.lineItems.bulkEditAssignedTargetingOptions אפשר להוסיף או להסיר את אפשרויות הטירגוט שהוקצו למשתמשים בכמה פריטים.
• בעזרת advertisers.lineItems.bulkListAssignedTargetingOptions אפשר להציג רשימה של אפשרויות טירגוט שהוקצו בפריטים מרובים.
• באמצעות advertisers.lineItems.duplicate תוכלו ליצור עותק משוכפל של פריט קיים באותו סדר הכנסה, תוך העתקה של כל ההגדרות והגדרות המיקוד.

גישת כתיבה חלקית לטירגוט לפי הזמנת קמפיין

בגרסה 2 אפשר לערוך את הגדרות הטירגוט של קבוצת משנה עבור המשאבים InsertionOrder באמצעות השיטות החדשות create ו-delete בשירות advertisers.insertionOrders.targetingTypes.assignedTargetingOptions. ניתן לנהל באופן מלא את סוגי המיקוד הבאים ברמת סדר ההכנסה:

• TARGETING_TYPE_AGE_RANGE
• TARGETING_TYPE_BROWSER
• TARGETING_TYPE_CATEGORY
• TARGETING_TYPE_CHANNEL
• TARGETING_TYPE_DEVICE_MAKE_MODEL
• TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION
• TARGETING_TYPE_ENVIRONMENT
• TARGETING_TYPE_GENDER
• TARGETING_TYPE_KEYWORD
• TARGETING_TYPE_LANGUAGE
• TARGETING_TYPE_NEGATIVE_KEYWORD_LIST
• TARGETING_TYPE_OPERATING_SYSTEM
• TARGETING_TYPE_PARENTAL_STATUS
• TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION
• TARGETING_TYPE_VIEWABILITY