Von der Bid Manager API (Version 1.1 zu Version 2) migrieren

Im März 2022 haben wir Version 2 der Bid Manager API veröffentlicht. Aufgrund der Veröffentlichung dieser neuen Version planen wir, ein Ablaufdatum für v1.1 bekanntzugeben. Wir empfehlen Ihnen, so schnell wie möglich mit der Migration von Version 1.1 zu Version 2 zu beginnen.

Anwendung migrieren

Für die Migration von v1.1 zu v2 müssen Sie Ihre Endpunkt-URLs aktualisieren, um v2 aufzurufen, und Ihre Anwendung aktualisieren, um funktionsgefährdende Änderungen zu berücksichtigen.

API-Aufrufe von Version 1.1 auf Version 2 aktualisieren

Wenn Sie v2 anstelle von v1.1 verwenden möchten, müssen Sie Ihre Anfragen aktualisieren, um neue v2-Endpunkte zu verwenden.

Äquivalente Methoden identifizieren

Damit Sie Ihre API-Aufrufe von v1.1 auf v2 aktualisieren können, müssen Sie zuerst die entsprechenden v1.1-Methoden in v2 identifizieren.

Die folgenden Namen aller Dienste und Methoden haben sich zwischen v1.1 und v2 geringfügig geändert:

• Die Dienste Queries und Reports in Version 1.1 werden in Version 2 als queries und queries.reports bezeichnet.
• Methoden wurden in Version 2 wie folgt umbenannt:

  v1.1-Methodenname	Entsprechende V2-Methode
  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

Auf neue Endpunkte aktualisieren

Sobald Sie gleichwertige Methoden identifiziert haben, müssen Sie Ihre Anfragen aktualisieren. Um beispielsweise die Methode queries.getquery mit v1.1 aufzurufen, verwenden Sie die folgende URL:

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

Zum Aufrufen der entsprechenden Methode in v2, auch queries.get genannt, aktualisieren Sie die URL so:

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

Wenn Sie Anfragen an die API über eine Clientbibliothek senden, verwenden Sie die neueste Version der Clientbibliothek und aktualisieren Sie Ihre Konfiguration auf Version 2.

Erforderliche Änderungen ausführen

In Version 2 wurden mehrere funktionsgefährdende Änderungen eingeführt. Lesen Sie die folgende Anleitung und nehmen Sie die erforderlichen Änderungen vor, die für Ihre bestehende Verwendung der Bid Manager API relevant sind.

Aufrufe an den Dienst „queries“ aktualisieren

• Die folgenden Felder in der Ressource Query, die ursprünglich durch allgemeine verschachtelte Objekte dargestellt wurden, wurden so geändert, dass sie die folgenden Objekttypen verwenden:

  Feld v1.1	Entsprechender V2-Objekttyp
  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

• Die folgenden Felder in der Ressource Query, die ursprünglich durch allgemeine Listenobjekte dargestellt wurden, wurden in Listen der folgenden neuen Objekttypen geändert:

  v1.1-Listenfeld	V2-Objekttyp
  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

• Die folgenden Felder in der Ressource Query, die ursprünglich durch Strings dargestellt wurden, werden in v2 durch Enum-Typen dargestellt. Sie umfassen die folgenden Änderungen:
  • In der V2-Entsprechung von metadata.dataRange wird jetzt Range verwendet. Bei der Konvertierung in diese Enum wurde der Wert PREVIOUS_HALF_MONTH entfernt und der Wert TYPE_NOT_SUPPORTED in RANGE_UNSPECIFIED geändert.
  • metadata.format verwendet jetzt die Aufzählung Format. Bei der Umwandlung in diese Enum wurde der Wert EXCEL_CSV entfernt und der Wert FORMAT_UNSPECIFIED hinzugefügt.
  • Für params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match und params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match wird jetzt die Enum Match verwendet.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition verwendet jetzt die Aufzählung PathMatchPosition. Bei der Konvertierung in diese Enum wurde der Wert PATH_MATCH_POSITION_UNSPECIFIED hinzugefügt.
  • schedule.frequency verwendet jetzt die Aufzählung Frequency. Bei der Konvertierung in diese Enum wurde der Wert FREQUENCY_UNSPECIFIED hinzugefügt.
  • params.type verwendet jetzt die Aufzählung ReportType. Bei der Konvertierung in diese Enum wurden folgende Änderungen vorgenommen:
  • Die folgenden Werte wurden eingestellt:
    • 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
  • Die übrigen Werte wurden alle aktualisiert, um die äquivalenten Werte in der UI besser widerzuspiegeln:

    v1.1-Werte	Entsprechender ReportType-Wert
    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

• Die Felder metadata.dataRange, reportDataStartTimeMs und reportDataEndTimeMs wurden durch die Felder range, customStartDate und customEndDate ersetzt. Die neuen Datumsfelder verwenden Date-Objekte anstelle von Millisekunden seit der Unix-Epoche. Diese Ersatzfelder wurden in das Objekt DataRange verschoben, das dem Feld dataRange im Objekt QueryMetadata zugewiesen ist.
• Die Felder schedule.startTimeMs und schedule.endTimeMs wurden durch die Felder startDate und endDate im Objekt QuerySchedule ersetzt. Die neuen Datumsfelder verwenden Date-Objekte anstelle von Millisekunden seit der Unix-Epoche.
• Die Felder metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport und metadata.latestReportRunTimeMs wurden entfernt. Informationen zu den zuletzt erstellten Berichten einer Abfrage sollten stattdessen mit der Methode queries.reports.list und dem Abfrageparameter orderBy von „key.reportId desc“ abgerufen werden. So wird sichergestellt, dass in der Anfrage die neuesten Berichte zuerst aufgelistet werden.
• Die Felder kind, timezoneCode, metadata.locale, params.includeInviteData und schedule.nextRunMinuteOfDay wurden entfernt.
• queries.create führt Abfragen nach der Erstellung nicht mehr automatisch aus und der Abfrageparameter asynchronous wurde entfernt. Rufen Sie nach dem queries.create queries.run auf, um Berichte für neue Abfragen zu generieren.
• Die Methode queries.run wurde so aktualisiert:
  • Der Abfrageparameter asynchronous wurde durch den Abfrageparameter synchronous ersetzt. Der neue Abfrageparameter arbeitet mit Umkehrlogik und gilt als falsch, wenn er nicht angegeben wird. Daher generiert queries.run Berichte in Version 2 standardmäßig asynchron und nicht synchron, was in Version 1.1 die Standardeinstellung ist.
  • Der Anfragetext wurde aktualisiert, um das Feld timezoneCode zu entfernen und die Felder dataRange, reportDataStartTimeMs und reportDataEndTimeMs durch ein Objekt DataRange zu ersetzen, das dem Feld dataRange zugewiesen ist.
  • Die Methode gibt das resultierende Report-Objekt anstelle eines leeren Antworttexts zurück.
• Das Feld kind im Antworttext queries.list wurde entfernt.

Aufrufe an den Dienst „reports“ aktualisieren

• Die folgenden Felder in der Ressource Report, die ursprünglich durch allgemeine verschachtelte Objekte dargestellt wurden, wurden so geändert, dass sie die folgenden Objekttypen verwenden:

  Feld v1.1	Entsprechender V2-Objekttyp
  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

• Die folgenden Felder in der Ressource Report, die ursprünglich durch allgemeine Listenobjekte dargestellt wurden, wurden in Listen der folgenden neuen Objekttypen geändert:

  v1.1-Listenfeld	V2-Objekttyp
  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

• Die folgenden Felder in der Ressource Report, die ursprünglich durch Strings dargestellt wurden, wurden geändert. Die entsprechenden Felder in V2 werden nun durch neue Enum-Typen dargestellt und enthalten Änderungen an zulässigen Werten:
  • metadata.status.format verwendet jetzt die Aufzählung Format. Bei der Konvertierung in diese Enum wurde der Wert EXCEL_CSV entfernt und FORMAT_UNSPECIFIED hinzugefügt.
  • metadata.status.state verwendet jetzt die Aufzählung State. Bei der Konvertierung in diese Enum wurden die Werte QUEUED und STATE_UNSPECIFIED hinzugefügt.
  • Für params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match und params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match wird jetzt die Enum Match verwendet.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition verwendet jetzt die Aufzählung PathMatchPosition. Bei der Konvertierung in diese Enum wurde der Wert PATH_MATCH_POSITION_UNSPECIFIED hinzugefügt.
  • params.type verwendet jetzt die Aufzählung ReportType. Bei der Konvertierung zu dieser Enum wurden zahlreiche Änderungen vorgenommen, die im vorherigen Abschnitt zum Aktualisieren von Dienstaufrufen für Abfragen ausführlich beschrieben sind.
• Die Felder metadata.reportDataStartTimeMs und metadata.reportDataEndTimeMs wurden im Objekt ReportMetadata durch die Felder reportDataStartDate und reportDataEndDate ersetzt. Die neuen Felder verwenden Date-Objekte anstelle von Millisekunden seit der Unix-Epoche.
• metadata.status.finishTimeMs wurde durch das Feld finishTime im Objekt ReportStatus ersetzt. Dieses neue Zeitfeld stellt die Datumszeit als Zeitstempel im Format RFC3339 UTC „Zulu“ dar und nicht in Millisekunden seit der Unix-Epoche.
• Die Felder metadata.status.failure und params.includeInviteData wurden entfernt.
• Das Feld kind im Antworttext reports.list wurde entfernt.

Fehlerbehandlungslogik für Updates

Fehlermeldungen in der gesamten API wurden in Version 2 aktualisiert. Diese neuen Fehlermeldungen sind spezifischer und enthalten in einigen Fällen Informationen zu den Werten in der API-Anfrage, die zur Rückgabe des Fehlers führen. Wenn Ihre vorhandene Fehlerbehandlungslogik auf bestimmten Fehlermeldungstexten basiert, verallgemeinern Sie Ihre Fehlerbehandlung vor der Migration zu Version 2.