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. Da diese neue Version veröffentlicht wurde, planen wir, demnächst ein Ablaufdatum für v1.1 anzukündigen. Wir empfehlen Ihnen, so bald wie möglich mit der Migration von Version 1.1 zu Version 2 zu beginnen.

Anwendung migrieren

Für die Migration von Version 1.1 zu Version 2 müssen Sie Ihre Endpunkt-URLs aktualisieren, um Version 2 aufzurufen, und Ihre Anwendung aktualisieren, um wesentliche Änderungen zu berücksichtigen.

API-Aufrufe von v1.1 auf v2 aktualisieren

Wenn Sie v2 anstelle von v1.1 verwenden möchten, müssen Sie Ihre Anfragen aktualisieren, damit sie die neuen v2-Endpunkte verwenden.

Äquivalente Methoden identifizieren

Um Ihre API-Aufrufe von v1.1 auf v2 zu aktualisieren, müssen Sie zuerst die entsprechenden v1.1-Methoden in v2 ermitteln.

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

• Die Dienste Queries und Reports in Version 1.1 sind in Version 2 als queries und queries.reports bekannt.
• In Version 2 wurden Methoden so umbenannt:

  Methodenname in Version 1.1	Entsprechende Methode in Version 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

Auf neue Endpunkte umstellen

Nachdem Sie die entsprechenden Methoden ermittelt haben, müssen Sie Ihre Anfragen aktualisieren. Wenn Sie beispielsweise die Methode queries.getquery mit v1.1 aufrufen möchten, verwenden Sie die folgende URL:

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

Um die entsprechende Methode in Version 2 aufzurufen, die als queries.get bezeichnet wird, aktualisieren Sie die URL so:

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

Wenn Sie eine Clientbibliothek verwenden, um Anfragen an die API zu senden, verwenden Sie die aktuelle Version der Clientbibliothek und aktualisieren Sie Ihre Konfiguration auf Version 2.

Erforderliche Änderungen ausführen

In Version 2 führen wir eine Reihe von Änderungen ein, die nicht abwärtskompatibel sind. Sehen Sie sich die folgende Anleitung an und nehmen Sie die erforderlichen Änderungen vor, die für Ihre aktuelle Verwendung der Bid Manager API relevant sind.

Aufrufe des queries-Dienstes aktualisieren

• Die folgenden Felder in der Query-Ressource, die ursprünglich durch allgemeine verschachtelte Objekte dargestellt wurden, verwenden jetzt die folgenden Objekttypen:

  v1.1-Feld	Entsprechender V2-Objekttyp
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Entfernt
  params.options.pathQueryOptions.channelGrouping	Entfernt
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Entfernt
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Entfernt
  schedule	QuerySchedule

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

  Listenfeld für Version 1.1	v2-Objekttyp
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Entfernt
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Entfernt
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Entfernt
  params.options.pathQueryOptions.pathFilters[]	Entfernt
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Entfernt

• Die folgenden Felder in der Query-Ressource, die ursprünglich durch Strings dargestellt wurden, werden in Version 2 durch Enum-Typen dargestellt und umfassen die folgenden Änderungen:
  • Für das v2-Äquivalent von metadata.dataRange wird jetzt das Enum 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 das Enum Format. Bei der Umstellung auf diese Enum wurde der Wert EXCEL_CSV entfernt und der Wert FORMAT_UNSPECIFIED hinzugefügt.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match und params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match verwenden jetzt die Match-Aufzählung.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition verwendet jetzt die Enum PathMatchPosition. Bei der Umstellung auf diese Enumeration wurde der Wert PATH_MATCH_POSITION_UNSPECIFIED hinzugefügt.
  • schedule.frequency verwendet jetzt das Enum Frequency. Bei der Umstellung auf diese Enum wurde der Wert FREQUENCY_UNSPECIFIED hinzugefügt.
  • params.type verwendet jetzt das Enum ReportType. Bei der Umstellung auf dieses Enum wurden die folgenden Ä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 verbleibenden Werte wurden alle aktualisiert, um ihre entsprechenden Werte in der Benutzeroberfläche besser widerzuspiegeln:

    Werte für Version 1.1	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. In den neuen Datumsfeldern werden Date-Objekte anstelle von Millisekunden seit der Unix-Epoche verwendet. 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 im Objekt QuerySchedule durch die Felder startDate und endDate ersetzt. In den neuen Datumsfeldern werden Date-Objekte anstelle von Millisekunden seit der Unix-Epoche verwendet.
• Die Felder metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport und metadata.latestReportRunTimeMs wurden entfernt. Informationen zu den zuletzt generierten Berichten einer Abfrage sollten stattdessen mit der Methode queries.reports.list und dem Abfrageparameter orderBy „key.reportId desc“ abgerufen werden, damit die neuesten Berichte zuerst aufgeführt werden.
• Die Felder kind, timezoneCode, metadata.locale, params.includeInviteData und schedule.nextRunMinuteOfDay wurden entfernt.
• queries.create führt nach der Erstellung keine Abfragen mehr automatisch aus und der Abfrageparameter asynchronous wurde entfernt. Rufen Sie queries.run nach queries.create auf, um Berichte für neue Anfragen zu generieren.
• Die Methode queries.run wurde auf folgende Weise aktualisiert:
  • Der Abfrageparameter asynchronous wurde durch den Abfrageparameter synchronous ersetzt. Der neue Abfrageparameter arbeitet mit inverser Logik und wird als „false“ betrachtet, wenn er nicht angegeben ist. Daher werden Berichte in queries.run standardmäßig asynchron in Version 2 und synchron in Version 1.1 generiert.
  • Der Anfragetext wurde aktualisiert, um das Feld timezoneCode zu entfernen und die Felder dataRange, reportDataStartTimeMs und reportDataEndTimeMs durch ein DataRange-Objekt 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 von queries.list wurde entfernt.

Aufrufe des reports-Dienstes aktualisieren

• Die folgenden Felder in der Report-Ressource, die ursprünglich durch allgemeine verschachtelte Objekte dargestellt wurden, verwenden jetzt die folgenden Objekttypen:

  v1.1-Feld	Entsprechender V2-Objekttyp
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Entfernt
  params.options.pathQueryOptions.channelGrouping	Entfernt
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Entfernt
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Entfernt

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

  Listenfeld für Version 1.1	v2-Objekttyp
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Entfernt
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Entfernt
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Entfernt
  params.options.pathQueryOptions.pathFilters[]	Entfernt
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Entfernt

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

Fehlerbehandlungslogik aktualisieren

Die Fehlermeldungen in der 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 den Fehler verursachen. Wenn Ihre vorhandene Logik zur Fehlerbehandlung auf bestimmten Fehlermeldungstexten basiert, sollten Sie die Fehlerbehandlung vor der Migration zu Version 2 verallgemeinern.