דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

פרטו שיטות מקבילות

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

השמות הבאים של כל השירותים והשיטות השתנו מעט בין v1.1 לבין v2:

השירותים Queries ו-Reports בגרסה 1.1 נקראים queries ו-queries.reports בגרסה 2.

שמות השיטות השתנו באופן הבא בגרסה 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 בגרסה 1.1, תצטרכו להשתמש בכתובת ה-URL הבאה:

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

כדי להפעיל את השיטה המקבילה ב-v2, שנקראת queries.get, מעדכנים את כתובת ה-URL כך:

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

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

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

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

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

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

שדה v1.1	סוג אובייקט שווה ערך v2
`metadata`	`QueryMetadata`
`params`	`Parameters`
`params.options`	`Options`
`params.options.pathQueryOptions`	`PathQueryOptions`
`params.options.pathQueryOptions.channelGrouping`	`ChannelGrouping`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`schedule`	`QuerySchedule`

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

שדה רשימה בגרסה 1.1	סוג אובייקט v2
`params.filters[]`	`FilterPair`
`params.options.pathQueryOptions.channelGrouping.rules[]`	`Rule`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`	`DisjunctiveMatchStatement`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`	`EventFilter`
`params.options.pathQueryOptions.pathFilters[]`	`PathFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[]`	`EventFilter`

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

בגרסה 2 המקבילה של metadata.dataRange משתמשים עכשיו במספר Range טיפוסים בני מנייה (enum). בהמרה לטיפוסים בני מנייה (enum) זה, הערך PREVIOUS_HALF_MONTH הוסר והערך TYPE_NOT_SUPPORTED השתנה ל-RANGE_UNSPECIFIED.
הפונקציה metadata.format משתמשת עכשיו במספרים Format טיפוסים בני מנייה (enum). בהמרה לרשימה הזו, הוסר הערך EXCEL_CSV והערך FORMAT_UNSPECIFIED נוסף.
params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match ו-params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match עכשיו משתמשים במספר Match טיפוסים בני מנייה (enum).
הקוד params.options.pathQueryOptions.pathFilters[].pathMatchPosition משתמש עכשיו בטיפוסים בני מנייה (enum) PathMatchPosition. בהמרה לטיפוסים בני מנייה (enum) הזה, נוסף הערך PATH_MATCH_POSITION_UNSPECIFIED.
הפונקציה schedule.frequency משתמשת עכשיו במספרים Frequency טיפוסים בני מנייה (enum). בהמרה לערך טיפוסים בני מנייה (enum) זה, נוסף הערך FREQUENCY_UNSPECIFIED.
הפונקציה params.type משתמשת עכשיו במספרים 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 description", כדי להבטיח שבבקשה יופיעו קודם הדוחות העדכניים.
השדות 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	סוג אובייקט שווה ערך v2
`key`	`ReportKey`
`metadata`	`ReportMetadata`
`metadata.status`	`ReportStatus`
`params`	`Parameters`
`params.options`	`Options`
`params.options.pathQueryOptions`	`PathQueryOptions`
`params.options.pathQueryOptions.channelGrouping`	`ChannelGrouping`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter`	`PathQueryOptionsFilter`

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

שדה רשימה בגרסה 1.1	סוג אובייקט v2
`params.filters[]`	`FilterPair`
`params.options.pathQueryOptions.channelGrouping.rules[]`	`Rule`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]`	`DisjunctiveMatchStatement`
`params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]`	`EventFilter`
`params.options.pathQueryOptions.pathFilters[]`	`PathFilter`
`params.options.pathQueryOptions.pathFilters[].eventFilters[]`	`EventFilter`

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

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

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