Ta strona została przetłumaczona przez Cloud Translation API.

Przechodzenie z interfejsu Bid Manager API v1.1 na wersję 2

W marcu 2022 roku opublikowaliśmy wersję 2 interfejsu Bid Manager API. Ze względu na wprowadzenie tej nowej wersji planujemy wkrótce ogłosić datę wycofania jej wersji 1.1. Zalecamy jak najszybsze rozpoczęcie migracji z wersji 1.1 do 2.

Migracja aplikacji

Migracja z wersji 1.1 do wersji 2 wymaga zaktualizowania adresów URL punktów końcowych tak, aby wywoływały wersję 2, oraz zaktualizowania aplikacji pod kątem zmian powodujących niezgodność.

Zaktualizuj wywołania interfejsu API z wersji 1.1 do wersji 2

Aby używać wersji 2 zamiast 1.1, musisz zaktualizować żądania, tak aby używały nowych punktów końcowych w wersji 2.

Określ równoważne metody

Aby zaktualizować wywołania interfejsu API z wersji 1.1 do wersji 2, musisz najpierw zidentyfikować metody odpowiadające wersji 1.1 w wersji 2.

Następujące nazwy wszystkich usług i metod nieco się zmieniły między wersjami 1.1 i 2:

Usługi Queries i Reports w wersji 1.1 są znane jako queries, a w wersji 2 – queries.reports.

W wersji 2 nazwy metod zmieniły się w następujący sposób:

Nazwa metody w wersji 1.1	Odpowiednik metody w wersji 2
`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`

Zaktualizuj do nowych punktów końcowych

Po znalezieniu równoważnych metod musisz zaktualizować żądania. Aby na przykład wywołać metodę queries.getquery w wersji 1.1, użyj tego adresu URL:

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

Aby w wersji 2 wywołać równoważną metodę o nazwie queries.get, zaktualizuj adres URL w ten sposób:

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

Jeśli do wysyłania żądań do interfejsu API używasz biblioteki klienta, użyj najnowszej wersji biblioteki klienta i zaktualizuj konfigurację tak, aby używała wersji 2.

Wprowadzanie wymaganych zmian

Wprowadzamy w wersji 2 pewne zmiany powodujące niezgodność. Zapoznaj się z instrukcjami poniżej i wprowadź wymagane zmiany w związku z dotychczasowym korzystaniem z interfejsu Bid Manager API.

Zaktualizuj połączenia z usługą `queries`

Poniższe pola w zasobie Query, które pierwotnie były reprezentowane przez ogólne zagnieżdżone obiekty, zostały zmienione i będą korzystać z tych typów obiektów:

Pole v1.1	Odpowiednik typu obiektu w wersji 2
`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`

Te pola w zasobie Query, które pierwotnie były reprezentowane przez obiekty list ogólnych, zostały zmienione na listy tych nowych typów obiektów:

Pole listy w wersji 1.1	Typ obiektu w wersji 2
`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`

Poniższe pola w zasobie Query, pierwotnie reprezentowane przez ciągi, są reprezentowane przez typy wyliczeniowe w wersji 2 i zawierają te zmiany:

Odpowiednik w wersji 2 funkcji metadata.dataRange korzysta teraz z wyliczenia Range. Podczas konwersji na tę wyliczenie wartość PREVIOUS_HALF_MONTH została usunięta, a wartość TYPE_NOT_SUPPORTED zmieniona na RANGE_UNSPECIFIED.
metadata.format używa teraz wyliczenia Format. Podczas konwersji na tę wyliczenie wartość EXCEL_CSV została usunięta, a wartość FORMAT_UNSPECIFIED dodana.
params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match a params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match teraz użyj wartości enum Match.
params.options.pathQueryOptions.pathFilters[].pathMatchPosition używa teraz wyliczenia PathMatchPosition. Podczas konwersji na tę wyliczenie dodano wartość PATH_MATCH_POSITION_UNSPECIFIED.
schedule.frequency używa teraz wyliczenia Frequency. Podczas przeliczania na tę wyliczenie została dodana wartość FREQUENCY_UNSPECIFIED.
params.type używa teraz wyliczenia ReportType. W wyniku konwersji tej wyliczenia wprowadzono te zmiany:
Te wartości zostały wycofane:
- 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

Pozostałe wartości zostały zaktualizowane, aby lepiej odzwierciedlały równoważne wartości w interfejsie:

Wartości w wersji 1.1	Odpowiednik wartości `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`

Pola metadata.dataRange, reportDataStartTimeMs i reportDataEndTimeMs zostały zastąpione polami range, customStartDate i customEndDate. Nowe pola dat używają obiektów Date, a nie milisekund od początku epoki uniksowej. Te pola zastępcze zostały przeniesione do obiektu DataRange przypisanego do pola dataRange w obiekcie QueryMetadata.
Pola schedule.startTimeMs i schedule.endTimeMs zostały zastąpione polami startDate i endDate w obiekcie QuerySchedule. Nowe pola dat używają obiektów Date, a nie milisekund od początku epoki uniksowej.
Pola metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport i metadata.latestReportRunTimeMs zostały usunięte. Informacje o najnowszych raportach związanych z zapytaniem należy pobierać za pomocą metody queries.reports.list z parametrem zapytania orderBy o wartości „key.reportId desc”, aby zagwarantować, że w żądaniu na początku pojawią się najnowsze raporty.
Pola kind, timezoneCode, metadata.locale, params.includeInviteData i schedule.nextRunMinuteOfDay zostały usunięte.
queries.create nie uruchamia już automatycznie zapytań po utworzeniu, a parametr zapytania asynchronous został usunięty. Wywołaj metodę queries.run po queries.create, aby wygenerować raporty dla nowych zapytań.
Metoda queries.run została zaktualizowana w ten sposób:
- Parametr zapytania asynchronous został zastąpiony parametrem zapytania synchronous. Nowy parametr zapytania działa z logiką odwrotną i jeśli nie jest określony, jest uznawany za fałszywy. Z tego względu queries.run domyślnie generuje raporty w wersji 2 asynchronicznie, a nie synchronicznie (w wersji 1.1).
- Treść żądania została zaktualizowana w celu usunięcia pola timezoneCode i zastąpienia pól dataRange, reportDataStartTimeMs i reportDataEndTimeMs obiektem DataRange przypisanym do pola dataRange.
- Metoda zwraca wynikowy obiekt Report zamiast pustej treści odpowiedzi.
Pole kind w treści odpowiedzi queries.list zostało usunięte.

Zaktualizuj połączenia z usługą `reports`

Poniższe pola w zasobie Report pierwotnie reprezentowane przez ogólne zagnieżdżone obiekty zostały zmienione i używają tych typów obiektów:

Pole v1.1	Odpowiednik typu obiektu w wersji 2
`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`

Te pola w zasobie Report, które pierwotnie były reprezentowane przez obiekty list ogólnych, zostały zmienione na listy tych nowych typów obiektów:

Pole listy w wersji 1.1	Typ obiektu w wersji 2
`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`

Te pola w zasobie Report, które pierwotnie były reprezentowane przez ciągi znaków, uległy zmianie, więc odpowiadające im pola w wersji 2 są reprezentowane przez nowe typy wyliczeniowe i zawierają zmiany akceptowanych wartości:
- metadata.status.format używa teraz wyliczenia Format. Podczas przeliczania na tę wyliczenie wartość EXCEL_CSV została usunięta i dodana do pola FORMAT_UNSPECIFIED.
- metadata.status.state używa teraz wyliczenia State. Podczas konwersji na tę wyliczenie zostały dodane wartości QUEUED i STATE_UNSPECIFIED.
- params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match a params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match teraz użyj wartości enum Match.
- params.options.pathQueryOptions.pathFilters[].pathMatchPosition używa teraz wyliczenia PathMatchPosition. Podczas konwersji na tę wyliczenie dodano wartość PATH_MATCH_POSITION_UNSPECIFIED.
- params.type używa teraz wyliczenia ReportType. Podczas konwersji do tej wyliczenia wprowadzono wiele zmian. Szczegółowo opisano je w poprzedniej sekcji dotyczącej aktualizowania wywołań usługi zapytań.
Pola metadata.reportDataStartTimeMs i metadata.reportDataEndTimeMs zostały zastąpione polami reportDataStartDate i reportDataEndDate w obiekcie ReportMetadata. Od początku epoki uniksowej nowe pola używają obiektów Date, a nie milisekund.
Zastąpienie metadata.status.finishTimeMs polem finishTime w obiekcie ReportStatus zostało zastąpione. To nowe pole czasu przedstawia datę i godzinę w formie sygnatury czasowej w formacie RFC3339 UTC „Zulu”, a nie w milisekundach od początku epoki uniksowej.
Pola metadata.status.failure i params.includeInviteData zostały usunięte.
Pole kind w treści odpowiedzi reports.list zostało usunięte.

Zaktualizuj logikę obsługi błędów

W wersji 2 zaktualizowano komunikaty o błędach interfejsu API. Te nowe komunikaty o błędach są bardziej szczegółowe, a w niektórych przypadkach zawierają informacje o wartościach w żądaniu do interfejsu API, które powodują zwrócenie błędu. Jeśli obecna logika obsługi błędów opiera się na określonym tekście komunikatu o błędzie, uogólnij swoją obsługę błędów przed migracją do wersji 2.