Passer de la version 1.1 à la version 2 de l'API Bid Manager

En mars 2022, nous avons lancé la version 2 de l'API Bid Manager. Étant donné la sortie de cette nouvelle version, nous prévoyons d'annoncer prochainement une date d'abandon pour la version 1.1. Nous vous recommandons de commencer la migration de la version 1.1 vers la version 2 dès que possible.

Migrer votre application

La migration de la version 1.1 vers la version 2 nécessite de mettre à jour vos URL de point de terminaison pour appeler la version 2 et de mettre à jour votre application pour tenir compte des modifications destructives.

Mettre à jour vos appels d'API de la version 1.1 vers la version 2

Pour utiliser la version 2 au lieu de la version 1.1, vous devez mettre à jour vos requêtes afin qu'elles utilisent les nouveaux points de terminaison de la version 2.

Identifier les méthodes équivalentes

Pour mettre à jour vos appels d'API de la version 1.1 vers la version 2, vous devez d'abord identifier les méthodes équivalentes de la version 1.1 dans la version 2.

Les noms suivants de tous les services et méthodes ont légèrement changé entre la version 1.1 et la version 2 :

• Les services Queries et Reports de la version 1.1 sont appelés queries et queries.reports dans la version 2.
• Les méthodes ont été renommées comme suit dans la version 2 :

  Nom de la méthode dans la version 1.1	Méthode équivalente dans la 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

Passer aux nouveaux points de terminaison

Une fois que vous avez identifié les méthodes équivalentes, vous devez mettre à jour vos requêtes. Par exemple, pour appeler la queries.getquery méthode avec la version 1.1, vous devez utiliser l'URL suivante :

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

Pour appeler la méthode équivalente dans la version 2, appelée queries.get, remplacez l' URL par la suivante :

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

Si vous utilisez une bibliothèque cliente pour envoyer des requêtes à l'API, utilisez la dernière version de la bibliothèque cliente et mettez à jour votre configuration pour utiliser la version 2.

Apporter les modifications requises

Nous introduisons un certain nombre de modifications destructives dans la version 2. Consultez les instructions suivantes et apportez les modifications requises en fonction de votre utilisation actuelle de l'API Bid Manager.

Mettre à jour les appels au service queries

• Les champs suivants de la ressource Query, initialement représentés par des objets imbriqués généraux, ont été modifiés pour utiliser les types d'objets suivants :

  Champ dans la version 1.1	Type d'objet équivalent dans la version 2
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Supprimé
  params.options.pathQueryOptions.channelGrouping	Supprimé
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Supprimé
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Supprimé
  schedule	QuerySchedule

• Les champs suivants de la ressource Query, initialement représentés par des objets de liste généraux, ont été modifiés pour devenir des listes des nouveaux types d'objets suivants :

  Champ de liste dans la version 1.1	Type d'objet dans la version 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Supprimé
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Supprimé
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Supprimé
  params.options.pathQueryOptions.pathFilters[]	Supprimé
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Supprimé

• Les champs suivants de la ressource Query, initialement représentés par des chaînes, sont représentés par des types d'énumération dans la version 2 et incluent les modifications suivantes :
  • L'équivalent de metadata.dataRange dans la version 2 utilise désormais l' Range énumération. Lors de la conversion vers cette énumération, la valeur PREVIOUS_HALF_MONTH a été supprimée et la valeur TYPE_NOT_SUPPORTED a été remplacée par RANGE_UNSPECIFIED.
  • metadata.format utilise désormais l'Format énumération. Lors de la conversion vers cette énumération, la valeur EXCEL_CSV a été supprimée et la valeur FORMAT_UNSPECIFIED a été ajoutée.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match et params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match utilisent désormais l'énumération Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition utilise désormais l'énumération PathMatchPosition. Lors de la conversion vers cette énumération, la valeur PATH_MATCH_POSITION_UNSPECIFIED a été ajoutée.
  • schedule.frequency utilise désormais l'Frequency énumération. Lors de la conversion vers cette énumération, la valeur FREQUENCY_UNSPECIFIED a été ajoutée.
  • params.type utilise désormais l'énumération ReportType. Lors de la conversion vers cette énumération, les modifications suivantes ont été apportées :
  • Les valeurs suivantes ont été abandonnées :
    • 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
  • Les valeurs restantes ont toutes été mises à jour pour mieux refléter leurs valeurs équivalentes dans l'interface utilisateur :

    Valeurs dans la version 1.1	Valeur ReportType équivalente
    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

• Les champs metadata.dataRange, reportDataStartTimeMs et reportDataEndTimeMs ont été remplacés par les champs range, customStartDate et customEndDate. Les nouveaux champs de date utilisent Date objets au lieu de millisecondes depuis l'époque UNIX. Ces champs de remplacement ont été déplacés vers l'objet DataRange attribué au champ dataRange dans l'objet QueryMetadata.
• Les champs schedule.startTimeMs et schedule.endTimeMs ont été remplacés par les champs startDate et endDate dans l'objet QuerySchedule. Les nouveaux champs de date utilisent Date objets au lieu de millisecondes depuis l'époque UNIX.
• Les champs metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport et metadata.latestReportRunTimeMs ont été supprimés. Les informations concernant les rapports les plus récents générés par une requête doivent être récupérées à l'aide de la queries.reports.list méthode avec le orderBy paramètre de requête de "key.reportId desc" pour garantir que la requête liste les rapports les plus récents en premier.
• Les champs kind, timezoneCode, metadata.locale, params.includeInviteData et schedule.nextRunMinuteOfDay ont été supprimés.
• queries.create n'exécute plus automatiquement les requêtes après leur création et le paramètre de requête asynchronous a été supprimé. Appelez queries.run après queries.create pour générer des rapports pour les nouvelles requêtes.
• La méthode queries.run a été mise à jour de la manière suivante :
  • Le paramètre de requête asynchronous a été remplacé par le synchronous paramètre de requête. Le nouveau paramètre de requête fonctionne avec une logique inverse et est considéré comme faux s'il n'est pas spécifié. Par conséquent, queries.run génère des rapports de manière asynchrone par défaut dans la version 2, contrairement à la version 1.1 où la génération est synchrone par défaut.
  • Le corps de la requête a été mis à jour pour supprimer le timezoneCode champ et remplacer les dataRange, reportDataStartTimeMs et reportDataEndTimeMs champs par un objet DataRange attribué au champ dataRange.
  • La méthode renvoie l'objet Report résultant au lieu d'un corps de réponse vide.
• Le champ kind dans le corps de réponse queries.list a été supprimé.

Mettre à jour les appels au service reports

• Les champs suivants de la ressource Report, initialement représentés par des objets imbriqués généraux, ont été modifiés pour utiliser les types d'objets suivants :

  Champ dans la version 1.1	Type d'objet équivalent dans la version 2
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Supprimé
  params.options.pathQueryOptions.channelGrouping	Supprimé
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Supprimé
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Supprimé

• Les champs suivants de la ressource Report, initialement représentés par des objets de liste généraux, ont été modifiés pour devenir des listes des nouveaux types d'objets suivants :

  Champ de liste dans la version 1.1	Type d'objet dans la version 2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Supprimé
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Supprimé
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Supprimé
  params.options.pathQueryOptions.pathFilters[]	Supprimé
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Supprimé

• Les champs suivants de la ressource Report, initialement représentés par des chaînes, ont été modifiés de sorte que leurs champs équivalents dans la version 2 soient représentés par de nouveaux types d'énumération et incluent des modifications des valeurs acceptables :
  • metadata.status.format utilise désormais l'Format énumération. Lors de la conversion vers cette énumération, la valeur EXCEL_CSV a été supprimée et la valeur FORMAT_UNSPECIFIED a été ajoutée.
  • metadata.status.state utilise désormais l'énumération State. Lors de la conversion vers cette énumération, les valeurs QUEUED et STATE_UNSPECIFIED ont été ajoutées.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match et params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match utilisent désormais l'énumération Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition utilise désormais l'énumération PathMatchPosition. Lors de la conversion vers cette énumération, la valeur PATH_MATCH_POSITION_UNSPECIFIED a été ajoutée.
  • params.type utilise désormais l'énumération ReportType. Lors de la conversion vers cette énumération, de nombreuses modifications ont été apportées et sont listées en détail dans la section précédente concernant la mise à jour des appels de service de requêtes.
• Les champs metadata.reportDataStartTimeMs et metadata.reportDataEndTimeMs ont été remplacés par les champs reportDataStartDate et reportDataEndDate dans l'objet ReportMetadata. Les nouveaux champs utilisent Date objets au lieu de millisecondes depuis l'époque UNIX.
• metadata.status.finishTimeMs a été remplacé par le champ finishTime dans l'objet ReportStatus. Ce nouveau champ temporel représente la date et l'heure sous forme d'horodatage au format RFC3339 UTC "Zulu" au lieu de millisecondes depuis l'époque UNIX.
• metadata.status.failure et params.includeInviteData champs ont été supprimés.
• Le champ kind dans le corps de réponse reports.list a été supprimé.

Mettre à jour la logique de gestion des erreurs

Les messages d'erreur de l'API ont été mis à jour dans la version 2. Ces nouveaux messages d'erreur sont plus spécifiques et, dans certains cas, fournissent des informations sur les valeurs de la requête API qui entraînent le renvoi de l'erreur. Si votre logique de gestion des erreurs existante repose sur un texte de message d'erreur spécifique, généralisez votre gestion des erreurs avant de migrer vers la version 2.