מעבר מ-Bid Manager API גרסה 1.1 לגרסה 2

במרץ 2022 השקנו את גרסה 2 של Bid Manager API. לאור ההשקה של הגרסה החדשה הזו, אנחנו מתכננים להודיע בקרוב על תאריך סיום התמיכה בגרסה v1.1. מומלץ להתחיל את המיגרציה מגרסה 1.1 לגרסה 2 בהקדם האפשרי.

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

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

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

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

זיהוי שיטות שוות ערך

כדי לעדכן את הקריאות ל-API מגרסה v1.1 לגרסה v2, קודם צריך לזהות את השיטות המקבילות בגרסה v1.1 בגרסה v2.

השמות הבאים של כל השירותים והשיטות השתנו מעט בין גרסה 1.1 לגרסה 2:

• השירותים Queries ו-Reports בגרסה 1.1 נקראים queries ו-queries.reports בגרסה 2.
• השמות של ה-methods בגרסה 2 השתנו באופן הבא:

  שם השיטה בגרסה 1.1	שיטה מקבילה v2
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

עדכון לנקודות קצה חדשות

אחרי שמזהים שיטות שוות ערך, צריך לעדכן את הבקשות. לדוגמה, כדי להפעיל את השיטה queries.getquery עם גרסה v1.1, משתמשים בכתובת ה-URL הבאה:

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

כדי להפעיל את השיטה המקבילה בגרסה 2, שנקראת queries.get, צריך לעדכן את כתובת ה-URL לכתובת הבאה:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

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

ביצוע השינויים הנדרשים

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

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

• השדות הבאים במשאב Query, שיוצגו במקור על ידי אובייקטים מוכללים כלליים, השתנו כך שהם משתמשים בסוגי האובייקטים הבאים:

  שדה v1.1	סוג האובייקט המקביל בגרסה 2
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	הוסר
  params.options.pathQueryOptions.channelGrouping	הוסר
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	הוסר
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	הוסר
  schedule	QuerySchedule

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

  שדה לרשימת אפשרויות, גרסה 1.1	סוג האובייקט בגרסה 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	הוסר
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	הוסר
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	הוסר
  params.options.pathQueryOptions.pathFilters[]	הוסר
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	הוסר

• השדות הבאים במשאב Query, שיוצגו במקור כמחרוזות,מיוצגים על ידי סוגי enum בגרסה 2, וכוללים את השינויים הבאים:
  • המקבילה של metadata.dataRange בגרסה 2 משתמשת עכשיו ב-enum‏ Range. בתהליך ההמרה לסוג הנתונים הזה, הערך PREVIOUS_HALF_MONTH הוסר והערך TYPE_NOT_SUPPORTED שונה ל-RANGE_UNSPECIFIED.
  • ‫metadata.format משתמש עכשיו ב-enum‏ Format. בתהליך ההמרה לסוג ה-enum הזה, הערך EXCEL_CSV הוסר והערך FORMAT_UNSPECIFIED נוסף.
  • ‫params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match ו-params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match משתמשים עכשיו ב-enum‏ Match.
  • האפליקציה params.options.pathQueryOptions.pathFilters[].pathMatchPosition משתמשת עכשיו בטיפוס PathMatchPosition. במהלך ההמרה ל-enum הזה, הערך PATH_MATCH_POSITION_UNSPECIFIED נוסף.
  • ‫schedule.frequency משתמש עכשיו ב-enum‏ Frequency. במהלך ההמרה לסוג ה-enum הזה, הערך FREQUENCY_UNSPECIFIED נוסף.
  • ‫params.type משתמש עכשיו ב-enum‏ ReportType. במהלך ההמרה לסוג ה-enum הזה, בוצעו השינויים הבאים:
  • הערכים הבאים הוצאו משימוש:
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • הערכים הנותרים עודכנו כדי לשקף טוב יותר את הערכים המקבילים שלהם בממשק המשתמש:

    ערכים של גרסה 1.1	ערך מקביל של ReportType
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• השדות metadata.dataRange,‏ reportDataStartTimeMs ו-reportDataEndTimeMs הוחלפו בשדות range,‏ customStartDate ו-customEndDate. בשדות התאריך החדשים נעשה שימוש באובייקטים Date במקום באלפיות שנייה מאז ראשית זמן יוניקס (Unix epoch). שדות ההחלפה האלה הועברו לאובייקט DataRange שהוקצה לשדה dataRange באובייקט QueryMetadata.
• השדות schedule.startTimeMs ו-schedule.endTimeMs הוחלפו בשדות startDate ו-endDate באובייקט QuerySchedule. בשדות התאריך החדשים נעשה שימוש באובייקטים Date במקום באלפיות שנייה מאז ראשית זמן יוניקס (Unix epoch).
• השדות metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport ו- metadata.latestReportRunTimeMs הוסרו. כדי לקבל מידע על הדוחות האחרונים שנוצרו משאילתה, צריך להשתמש במקום זאת בשיטה queries.reports.list עם פרמטר השאילתה orderBy של 'key.reportId desc' כדי להבטיח שהבקשה תציג את הדוחות האחרונים קודם.
• השדות kind,‏ timezoneCode,‏ metadata.locale,‏ params.includeInviteData ו-schedule.nextRunMinuteOfDay הוסרו.
• ‫queries.create לא מריץ יותר שאילתות באופן אוטומטי אחרי היצירה, והפרמטר asynchronous של השאילתה הוסר. מפעילים את queries.run אחרי queries.create כדי ליצור דוחות לשאילתות חדשות.
• השיטה queries.run עודכנה באופן הבא:
  • פרמטר השאילתה asynchronous הוחלף בפרמטר השאילתה synchronous. פרמטר השאילתה החדש פועל עם לוגיקה הפוכה, ונחשב כ-false אם לא מציינים אותו. לכן, queries.run יוצר דוחות באופן אסינכרוני כברירת מחדל בגרסה 2, בניגוד לגרסה 1.1 שבה הדוחות נוצרים באופן סינכרוני כברירת מחדל.
  • גוף הבקשה עודכן כך שהשדה timezoneCode הוסר והשדות dataRange,‏ reportDataStartTimeMs ו-reportDataEndTimeMs הוחלפו באובייקט DataRange שהוקצה לשדה dataRange.
  • השיטה מחזירה את אובייקט Report שנוצר במקום גוף תגובה ריק.
• השדה kind בגוף התגובה queries.list הוסר.

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

• השדות הבאים במשאב Report, שיוצגו במקור על ידי אובייקטים כלליים מקוננים, השתנו כך שהם משתמשים בסוגי האובייקטים הבאים:

  שדה v1.1	סוג האובייקט המקביל בגרסה 2
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	הוסר
  params.options.pathQueryOptions.channelGrouping	הוסר
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	הוסר
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	הוסר

• השדות הבאים במשאב Report, שיוצג במקור על ידי אובייקטים של רשימה כללית, השתנו לרשימות של סוגי האובייקטים החדשים הבאים:

  שדה לרשימת אפשרויות, גרסה 1.1	סוג האובייקט בגרסה 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	הוסר
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	הוסר
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	הוסר
  params.options.pathQueryOptions.pathFilters[]	הוסר
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	הוסר

• השדות הבאים במשאב Report, שיוצגו במקור על ידי מחרוזות, השתנו כך שהשדות המקבילים להם בגרסה 2 יוצגו על ידי סוגי enum חדשים, ויכללו שינויים בערכים הקבילים:
  • ‫metadata.status.format משתמש עכשיו ב-enum‏ Format. במהלך ההמרה ל-enum הזה, הערך EXCEL_CSV הוסר והערך FORMAT_UNSPECIFIED נוסף.
  • ‫metadata.status.state משתמש עכשיו ב-enum‏ State. במהלך ההמרה לסוג ה-enum הזה, הערכים QUEUED ו-STATE_UNSPECIFIED נוספו.
  • ‫params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match ו-params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match משתמשים עכשיו ב-enum‏ Match.
  • האפליקציה params.options.pathQueryOptions.pathFilters[].pathMatchPosition משתמשת עכשיו בטיפוס PathMatchPosition. במהלך ההמרה ל-enum הזה, הערך PATH_MATCH_POSITION_UNSPECIFIED נוסף.
  • ‫params.type משתמש עכשיו ב-enum‏ ReportType. במהלך ההמרה ל-enum הזה, בוצעו שינויים רבים שמפורטים בקטע הקודם בנושא עדכון קריאות לשירות של שאילתות.
• השדות metadata.reportDataStartTimeMs ו-metadata.reportDataEndTimeMs הוחלפו בשדות reportDataStartDate ו-reportDataEndDate באובייקט ReportMetadata. השדות החדשים משתמשים באובייקטים Date במקום באלפיות השנייה מאז תקופת Unix.
• השדה metadata.status.finishTimeMs הוחלף בשדה finishTime באובייקט ReportStatus. שדה הזמן החדש הזה מייצג את התאריך והשעה כחותמת זמן בפורמט RFC3339 UTC ‏'Zulu', במקום במילי-שניות מאז ראשית זמן יוניקס (Unix epoch).
• השדות metadata.status.failure ו-params.includeInviteData הוסרו.
• השדה kind בגוף התגובה reports.list הוסר.

עדכון הלוגיקה של הטיפול בשגיאות

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