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

W marcu 2022 roku udostępniliśmy wersję 2 interfejsu Bid Manager API. W związku z udostępnieniem tej nowej wersji planujemy wkrótce ogłosić datę wycofania wersji 1.1. Zalecamy jak najszybsze rozpoczęcie migracji z wersji 1.1 na wersję 2.

Migracja aplikacji

Przejście z wersji 1.1 na wersję 2 wymaga zaktualizowania adresów URL punktów końcowych, aby wywoływać wersję 2, oraz zaktualizowania aplikacji, aby uwzględniała zmiany powodujące niezgodność wsteczną.

Aktualizowanie wywołań interfejsu API z wersji 1.1 do wersji 2

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

Wskaż równoważne metody

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

Nazwy wszystkich usług i metod zostały nieznacznie zmienione w wersji 2 w porównaniu z wersją 1.1:

• Usługi Queries i Reports w wersji 1.1 są znane jako queries i queries.reports w wersji 2.
• W wersji 2 nazwy metod zostały zmienione w ten sposób:

  Nazwa metody w wersji 1.1	Metoda 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

Aktualizacja do nowych punktów końcowych

Gdy znajdziesz równoważne metody, musisz zaktualizować swoje żądania. Na przykład, aby wywołać metodę queries.getquery w wersji 1.1, użyj tego adresu URL:

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

Aby wywołać odpowiednią metodę w wersji 2, czyli 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 tej biblioteki i zaktualizuj konfigurację, aby korzystać z wersji 2.

Wprowadzanie wymaganych zmian

W wersji 2 wprowadzamy szereg zmian powodujących niezgodność wsteczną. Zapoznaj się z poniższymi instrukcjami i wprowadź wymagane zmiany w sposobie korzystania z interfejsu Bid Managera API.

Aktualizowanie połączeń z usługą queries

• Te pola w zasobie Query, które pierwotnie były reprezentowane przez ogólne zagnieżdżone obiekty, zostały zmienione tak, aby używać tych typów obiektów:

  Pole v1.1	Odpowiednik typu obiektu w wersji 2
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Usunięta
  params.options.pathQueryOptions.channelGrouping	Usunięta
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Usunięta
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Usunięta
  schedule	QuerySchedule

• Te pola w zasobie Query, które pierwotnie były reprezentowane przez ogólne obiekty listy, 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[]	Usunięta
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Usunięta
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Usunięta
  params.options.pathQueryOptions.pathFilters[]	Usunięta
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Usunięta

• Te pola w zasobie Query, które pierwotnie były reprezentowane przez ciągi znaków, w wersji 2 są reprezentowane przez typy wyliczeniowe. Obejmują one te zmiany:
  • Odpowiednik parametru metadata.dataRange w wersji 2 korzysta teraz z wyliczenia Range. Podczas konwersji na ten typ wyliczeniowy wartość PREVIOUS_HALF_MONTH została usunięta, a wartość TYPE_NOT_SUPPORTED została zmieniona na RANGE_UNSPECIFIED.
  • metadata.format korzysta teraz z wyliczenia Format. Podczas konwersji na ten typ wyliczeniowy wartość EXCEL_CSV została usunięta, a wartość FORMAT_UNSPECIFIED została dodana.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match i params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match używają teraz wyliczenia Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition korzysta teraz z wyliczenia PathMatchPosition. Podczas konwersji na ten typ wyliczeniowy dodano wartość PATH_MATCH_POSITION_UNSPECIFIED.
  • schedule.frequency korzysta teraz z wyliczenia Frequency. Podczas konwersji na ten typ wyliczeniowy dodano wartość FREQUENCY_UNSPECIFIED.
  • params.type korzysta teraz z wyliczenia ReportType. W trakcie konwersji na ten typ wyliczeniowy wprowadziliśmy te zmiany:
  • Te wartości nie są już używane:
    • 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 ich odpowiedniki w interfejsie:

    Wartości w wersji 1.1	Równoważna wartość 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 daty używają obiektów Date zamiast 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 daty używają obiektów Date zamiast 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 wygenerowanych raportach dotyczących zapytania należy pobierać za pomocą metody queries.reports.list z parametrem zapytania orderBy „key.reportId desc”, aby mieć pewność, że na liście żądań najpierw 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 funkcję queries.run po wywołaniu funkcji queries.create, aby generować raporty dotyczące nowych zapytań.
• Metoda queries.run została zaktualizowana w ten sposób:
  • Parametr zapytania asynchronous został zastąpiony parametrem synchronous. Nowy parametr zapytania działa z logiką odwrotną i jest uznawany za fałszywy, jeśli nie jest określony. W związku z tym queries.run domyślnie generuje raporty asynchronicznie w wersji 2, a nie synchronicznie, co jest domyślnym ustawieniem 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.
• Usunięto pole kind z treści odpowiedzi queries.list.

Aktualizowanie połączeń z usługą reports

• Te pola w zasobie Report, który pierwotnie był reprezentowany przez ogólne obiekty zagnieżdżone, zostały zmienione tak, aby używać 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	Usunięta
  params.options.pathQueryOptions.channelGrouping	Usunięta
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Usunięta
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Usunięta

• Te pola w zasobie Report, które pierwotnie były reprezentowane przez obiekty listy ogólnej, 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[]	Usunięta
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Usunięta
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Usunięta
  params.options.pathQueryOptions.pathFilters[]	Usunięta
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Usunięta

• W tych polach w zasobie Report, który pierwotnie był reprezentowany przez ciągi znaków, wprowadziliśmy zmiany, więc ich odpowiedniki w wersji 2 są reprezentowane przez nowe typy wyliczeniowe i obejmują zmiany dopuszczalnych wartości:
  • metadata.status.format korzysta teraz z wyliczenia Format. Podczas konwersji na ten typ wyliczeniowy wartość EXCEL_CSV została usunięta, a wartość FORMAT_UNSPECIFIED została dodana.
  • metadata.status.state korzysta teraz z wyliczenia State. Podczas konwersji na ten typ wyliczeniowy dodano wartości QUEUED i STATE_UNSPECIFIED.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match i params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match używają teraz wyliczenia Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition korzysta teraz z wyliczenia PathMatchPosition. Podczas konwersji na ten typ wyliczeniowy dodano wartość PATH_MATCH_POSITION_UNSPECIFIED.
  • params.type korzysta teraz z wyliczenia ReportType. W ramach konwersji na ten typ wyliczeniowy wprowadzono liczne zmiany, które są szczegółowo opisane 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. Nowe pola używają obiektów Date zamiast milisekund od początku epoki uniksowej.
• Pole metadata.status.finishTimeMs zostało zastąpione polem finishTime w obiekcie ReportStatus. To nowe pole czasu reprezentuje datę i godzinę jako sygnaturę czasową 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.
• Usunięto pole kind z treści odpowiedzi reports.list.

Aktualizowanie logiki obsługi błędów

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