מעבר מ-v1 ל-v2

תאריך העדכון האחרון: 6 בדצמבר 2022

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

כדי לעבור מ-v1 ל-v2, צריך לעדכן את כתובות ה-URL של נקודות הקצה כדי לבצע קריאה ל-v2, ולעדכן את האפליקציה כך שתתחשב בשינויים הבלתי הפיכים.

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

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

לדוגמה, כדי להפעיל את השיטה 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) DeviceType של DEVICE_TYPE_TABLET, ולא באמצעות מזהה אפשרות הטירגוט מהשירות targetingTypes.targetingOptions. גרסאות מחרוזת של המאפיינים האלה מיוצגות בשדה החדש 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 הוסר מסוג המניין LineItemFlightDateType. בגרסה 2 אין תמיכה בהגדרת פריטים להוצאה על סמך הפעלה של טריגרים ידניים.

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

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

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

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

תכונות שנוספו לגרסה 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