Migrer depuis des fichiers de lecture des entités

Les fichiers de lecture des entités (ERF) sont des représentations JSON des objets de campagne d'un partenaire mises à disposition via Google Cloud Storage.

Les ERF ont été abandonnées en juin 2021 et seront supprimées le 31 octobre 2024. Les ERF ne sont plus générés. Utilisez l'API Display & Video 360 pour récupérer des ressources Display & Video 360.

Ce guide explique comment passer des fichiers de lecture des entités à l'API Display & Video 360 en:

  • Présentation des différences entre les deux interfaces
  • Comparer les tables ERF aux services d'API
  • Conseils sur la récupération d'entités via l'API
  • Prendre en compte les lacunes de données existantes
  • Présentation d'un mappage de tous les champs ERF à des champs de ressources d'API comparables

Présentation

Lorsque vous passez des ERF à l'API Display & Video 360, vous devez tenir compte de plusieurs différences clés, y compris les suivantes:

  • Fraîcheur des données Les fichiers ERF sont générés quotidiennement et de manière groupée, tandis que l'API récupère la version la plus à jour d'une ressource.
  • Structure des ressources. L'API utilise des structures JSON différentes de celles de l'ERF pour représenter les mêmes types de ressources. Certaines ressources, comme les paramètres de ciblage public, peuvent utiliser un espace d'ID différent.
  • Méthode de récupération. L'API Display & Video 360 ne permet de récupérer des ressources que de manière individuelle, dans des listes paginées ou via des transferts de données BigQuery, contrairement aux fichiers JSON bruts fournis par ERF.
  • Champ d'application Contrairement aux ERF, qui sont limitées par l'ID du partenaire, la plupart des ressources de l'API sont limitées par l'ID de l'annonceur. Les ressources incluses dans les réponses sont limitées aux ressources de ce champ d'application.

Représentation des données ERF dans l'API

Les fichiers de lecture des entités sont séparés en tables "Public" (Public) et "Private" (Privé). Les tables publiques fournissent des informations disponibles et applicables à tous les utilisateurs, telles que les valeurs de ciblage. Les tables privées fournissent des données spécifiques à un partenaire, telles que des ressources de création ou d'éléments de campagne.

L'API Display & Video 360 n'utilise pas cette dichotomie. Elle permet plutôt de récupérer toutes ces informations via divers services et en utilisant différentes structures JSON. Cette section compare les informations fournies via les tables d'erreurs de facturation publiques et privées à celles mises à disposition via les ressources et services de l'API Display & Video 360.

Informations publiques

Les tables publiques de l'ERF fournissent des documents de référence que les utilisateurs peuvent utiliser pour interpréter les paramètres de ciblage de leurs ressources privées récupérées et attribuer un ciblage via un sous-ensemble de versions de fichiers de données structurées (SDF) importées via l'UI. Ces documents de référence sont les mêmes pour tous les utilisateurs. Ils se composent d'un ID numérique, utilisé pour le mappage, et de détails plus descriptifs, tels qu'un nom à afficher.

Lorsque vous utilisez l'API Display & Video 360, vous pouvez récupérer des informations de référence sur le ciblage via le service targetingTypes.targetingOptions. Comme les tables publiques, ce service fournit les ID et les informations sur les options de ciblage pour un type de ciblage spécifique. Consultez notre page Définir le ciblage pour obtenir un exemple de code illustrant la récupération de l'ID de l'option de ciblage.

Tables et fichiers SDF publics

Avant la version 7 des fichiers de données structurées, les fichiers de lecture d'entités et les fichiers de données structurées utilisent le même espace d'ID pour les paramètres de ciblage. Si vous utilisez des fichiers de données structurées et les tables publiques de l'ERF pour interpréter ou attribuer des paramètres de ciblage à l'aide de fichiers de données structurées, vous pouvez télécharger ce document de référence au format CSV via l'interface utilisateur de Display & Video 360.

À partir de la version 7, les espaces d'ID utilisés par un sous-ensemble de colonnes de fichiers de données structurées ont été mis à jour pour dissocier les fichiers de données structurées des fichiers d'enchères en temps réel et les aligner davantage sur l'API Display & Video 360. Pour en savoir plus, consultez le guide de migration vers la version 7 et la documentation de référence.

Ressources privées

Les tables privées de l'ERF fournissent un instantané quotidien des paramètres actuels des ressources privées appartenant à un partenaire. En raison du volume considérable de ressources pouvant être créées pour un même partenaire, ces fichiers peuvent devenir très volumineux et difficiles à télécharger et à traiter.

Dans l'API, chaque table privée dispose d'un service correspondant qui fournit des points de terminaison pour la récupération et la gestion de ce type de ressource. Les ressources peuvent être récupérées de manière groupée à l'aide de la méthode de liste respective de chaque service. La structure JSON de chaque ressource est différente dans l'API par rapport à l'ERF, car elle utilise des noms de champ et des ressources partagées différents.

Certaines informations disponibles dans la représentation de l'ERF d'une ressource, telles que les paramètres de ciblage attribués d'une ressource ou les sites d'une chaîne, sont représentées dans l'API en tant qu'enfants de la ressource d'origine et doivent être récupérées via des requêtes API supplémentaires.

Récupération d'entités dans l'API

Les ressources Display & Video 360 peuvent être récupérées via des requêtes API directes ou des importations automatiques dans BigQuery.

Requêtes API directes

Chaque type de ressource peut être récupéré via un service API différent. Les ressources peuvent être récupérées individuellement ou de manière groupée à l'aide de la méthode get ou list du service approprié, respectivement. Voici quelques propriétés importantes des méthodes de liste de l'API Display & Video 360:

  • Champ d'application obligatoire. Contrairement aux ERF, qui sont limitées par partenaire, la plupart des ressources de l'API sont limitées par annonceur. La récupération de l'ensemble d'un type de ressource, comme les éléments de campagne, sous un partenaire peut nécessiter une demande de liste individuelle pour chaque annonceur enfant de ce partenaire. Les exceptions incluent les enfants directs d'un partenaire, tels que les annonceurs et les chaînes appartenant à un partenaire.
  • Pagination. Les méthodes de liste de l'API utilisent la pagination pour s'assurer que les réponses sont d'une taille raisonnable, en limitant la plupart des réponses de requêtes individuelles (ou pages) à 100 ressources. Si le nombre de ressources pertinentes est supérieur à la taille de la page, des appels de liste consécutifs sont nécessaires pour récupérer les pages suivantes de la réponse de liste complète. Un exemple de code permettant de paginer une réponse de liste est fourni dans la section de notre page du guide de ciblage concernant la récupération des options de ciblage disponibles .
  • Requêtes supplémentaires requises pour la récupération du ciblage. Les paramètres de ciblage d'une ressource ne sont pas inclus dans son objet JSON d'API, mais sont des ressources enfants appelées options de ciblage attribuées. Ces ressources enfants doivent être récupérées via une demande distincte. Par exemple, pour chaque élément de campagne récupéré via une requête advertisers.lineItems.list, une requête advertisers.lineItems.bulkListAssignedTargetingOptions distincte doit être effectuée pour récupérer toutes les informations de ciblage.

Optimiser la récupération des ressources

L'API Display & Video 360 peut nécessiter plusieurs requêtes pour récupérer la même quantité d'informations disponibles dans un seul fichier de lecture des entités. Optimiser la manière dont vous récupérez les ressources peut vous aider à récupérer les données dont vous avez besoin plus efficacement:

  • Envoyer des requêtes simultanées à l'API L'API Display & Video 360 protège l'infrastructure à l'aide de limites de débit pour les requêtes par projet et par annonceur par projet. Cette structure de quota vous permet d'implémenter une solution multithread pour plusieurs annonceurs, ce qui réduit le temps total nécessaire pour récupérer toutes les ressources nécessaires. Bien que la pagination exige que toutes les ressources d'un type dans un certain champ d'application soient récupérées via des appels consécutifs, la récupération de ressources dans un autre champ d'application ou d'un autre type peut être effectuée simultanément.
  • Utilisez des filtres et des paramètres de tri dans vos appels de liste pour ne récupérer que les ressources pertinentes. Par exemple, si vous ne vous intéressez qu'aux éléments de campagne qui ont été mis à jour au cours des dernières 24 heures, vous pouvez utiliser le paramètre filter de la méthode advertisers.lineItems.list pour ne renvoyer que les éléments de campagne dont la valeur updateTime est supérieure à un code temporel donné. Cela peut réduire considérablement le nombre de requêtes à effectuer.
  • Mettez en cache les ID utilisés régulièrement pour éviter les requêtes API inutiles. Certaines informations de référence, telles que les ID des options de ciblage et les ID d'audience Google, sont relativement stables et peuvent être stockées en toute sécurité pour éviter d'avoir à les récupérer à chaque utilisation. Toutefois, les valeurs mises en cache doivent être vérifiées chaque semaine pour tenir compte des modifications ou des abandons peu fréquents.

Pour savoir comment accéder efficacement à l'API Display & Video 360, consultez notre guide d'optimisation des quotas.

Importer dans BigQuery

Le connecteur BigQuery de l'API Display & Video 360 vous permet d'importer automatiquement les configurations de ressources Display & Video 360 directement dans BigQuery sur une base quotidienne. Les configurations sont stockées dans BigQuery à l'aide de la conception de ressources de l'API Display & Video 360. Un sous-ensemble de ressources d'API est compatible.

Pour en savoir plus sur l'utilisation du connecteur BigQuery de l'API Display & Video 360, consultez la documentation Cloud suivante:

Lacunes de données API connues

Vous pouvez rencontrer des lacunes de données notables lors de la migration de l'ERF vers l'API Display & Video 360, par exemple:

  • Ordres d'insertion de type "Histoire". Les ordres d'insertion de stories ne sont pas récupérables via l'API et doivent être récupérés via l'interface utilisateur de Display & Video 360.
  • Sous-ensemble de champs de ressources. Un petit nombre de champs de ressources présents dans les objets ERF ne sont pas disponibles dans les ressources correspondantes récupérées via l'API Display & Video 360.

Annexe: Mappage des champs ERF sur l'API

Mappage de la table publique

Les tableaux ci-dessous font correspondre les champs des tables publiques de l'ERF aux types de ciblage et aux champs d'options de ciblage existants dans l'API Display & Video 360. Bien que la valeur d'un champ puisse être mappée sur un autre, cela ne garantit pas qu'ils utilisent le même type de données, les mêmes valeurs d'énumération ou l'espace d'ID.

Collection d'applications

Récupérable sous le type de ciblage TARGETING_TYPE_APP_CATEGORY.

Nom du champ ERFDisponibilité de l'API DV360
id Champ TargetingOption.targetingOptionId .
nom Champ TargetingOption.appCategoryDetails.displayName .

Navigateur

Récupérable sous le type de ciblage TARGETING_TYPE_BROWSER.

Nom du champ ERFDisponibilité de l'API DV360
id Champ TargetingOption.targetingOptionId .
is_mobile Non disponible.
nom Champ TargetingOption.browserDetails.displayName .

DataPartner

Aucune ressource ni aucun champ équivalents ne sont disponibles dans l'API Display & Video 360.

DeviceCriteria

Récupérables avec les types de ciblage TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL et TARGETING_TYPE_DEVICE_TYPE.

Nom du champ ERFDisponibilité de l'API DV360
id Champ TargetingOption.targetingOptionId ou énumération DeviceType .
is_mobile Non disponible.
nom Champ TargetingOption.operatingSystemDetails.displayName , champ TargetingOption.deviceMakeModelDetails.displayName ou énumération DeviceType , en fonction du type de ciblage.
criteria_type Champ TargetingOption.targetingType .
operating_system_id Non disponible.
mobile_brand_name Non disponible.
mobile_model_name Non disponible.
mobile_make_model_id Non disponible.
device_type DeviceType enum.

GeoLocation

Récupérable sous le type de ciblage TARGETING_TYPE_GEO_REGION.

Nom du champ ERFDisponibilité de l'API DV360
id Champ TargetingOption.targetingOptionId .
canonical_name Champ TargetingOption.geoRegionDetails.displayName .
geo_name Non disponible.
country_code Non disponible.
region_code Non disponible.
city_name Non disponible.
postal_name Non disponible.
dma_code Non disponible.

Isp

Récupérable sous le type de ciblage TARGETING_TYPE_CARRIER_AND_ISP.

Nom du champ ERFDisponibilité de l'API DV360
id Champ TargetingOption.targetingOptionId .
is_mobile Non disponible.
nom Champ TargetingOption.carrierAndIspDetails.displayName .
secondary_criteria_id Champ TargetingOption.targetingOptionId .

Langue

Récupérable sous le type de ciblage TARGETING_TYPE_LANGUAGE.

Nom du champ ERFDisponibilité de l'API DV360
id Champ TargetingOption.targetingOptionId .
nom Non disponible. Le nom complet à afficher d'une langue est disponible dans le champ TargetingOption.languageDetails.displayName .

SiteToPlacementId

Aucune ressource ni aucun champ équivalents ne sont disponibles dans l'API Display & Video 360.

SupportedExchange

Récupérable sous le type de ciblage TARGETING_TYPE_EXCHANGE.

Nom du champ ERFDisponibilité de l'API DV360
id Exchange enum.
nom Exchange enum.

UniversalSite

Aucune ressource ni aucun champ équivalents ne sont disponibles dans l'API Display & Video 360. Vous pouvez cibler directement des sites et des applications individuels dans les types de ciblage TARGETING_TYPE_URL et TARGETING_TYPE_APP, respectivement. Dans Display & Video 360, vous pouvez cibler n'importe quelle application ou URL, mais toutes ne peuvent pas être incluses dans les rapports. Si vous souhaitez supprimer des applications et des URL non signalables des dépenses, suivez les instructions du Centre d'aide DV360.

Mappage des champs de la table privée

Les tableaux ci-dessous font correspondre les champs des tables privées de l'ERF aux champs ou services existants de l'API Display & Video 360. Bien que la valeur d'un champ puisse être mappée sur un autre, cela ne garantit pas qu'ils utilisent le même type de données, les mêmes valeurs d'énumération ou l'espace d'ID.

Annonceur

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ Advertiser.advertiserId .
common_data.name Champ Advertiser.displayName .
common_data.active Champ Advertiser.entityStatus .
common_data.integration_code Champ Advertiser.integrationDetails.integrationCode .
partner_id Champ Advertiser.partnerId .
currency_code Champ Advertiser.generalConfig.currencyCode .
timezone_code Champ Advertiser.generalConfig.timeZone .
landing_page_url Champ Advertiser.generalConfig.domainUrl .
available_channel_ids Récupérable via la méthode advertisers.channels.list .
blacklist_channel_id Récupérable via la méthode advertisers.targetingTypes.assignedtargetingOptions.list sous le type de ciblage TARGETING_TYPE_CHANNEL . Si AssignedTargetingOption.channelDetails.negative est défini sur "true", la chaîne est ciblée de manière négative.
dcm_configuration Non disponible.
dcm_network_id Champ Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id Le champ Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds liste les références annonceur CM360 qui partagent la configuration Floodlight CM360.
dcm_floodlight_group_id Champ Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids Champ Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags Non disponible.

Campagne

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ Campaign.campaignId .
common_data.name Champ Campaign.displayName .
common_data.active Champ Campaign.entityStatus .
common_data.integration_code Non disponible.
advertiser_id Champ Campaign.advertiserId .
budget Champs Campaign.campaignFlight et Campaign.campaignBudgets .
frequency_cap Champ Campaign.frequencyCap .
default_target_list Non disponible
uses_video_creatives Non disponible.
uses_display_creatives Non disponible.
uses_audio_creatives Non disponible.
objectif Champ Campaign.campaignGoal.campaignGoalType .
métrique Champ Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description Champ Campaign.campaignGoal.performanceGoal.performanceGoalString .
metric_amount_micros Champ Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros .

Création

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ Creative.creativeId .
common_data.name Champ Creative.displayName .
common_data.active Champ Creative.entityStatus .
common_data.integration_code Champ Creative.integrationCode .
advertiser_id Champ Creative.advertiserId .
dcm_placement_id Champ Creative.cmPlacementId .
width_pixels Champ Creative.dimensions.widthPixels .
height_pixels Champ Creative.dimensions.heightPixels .
approval_status Champ Creative.reviewStatus .
expanding_direction Champ Creative.expandingDirection .
creative_type Champ Creative.creativeType .

CustomAffinity

Nom du champ ERFDisponibilité de l'API DV360
id Champ CustomList.customListId .
nom Champ CustomList.displayName .
description Non disponible.
advertiser_id Non disponible.

FloodlightActivity

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ FloodlightActivity.floodlightActivityId .
common_data.name Champ FloodlightActivity.displayName .
common_data.active Champ FloodlightActivity.servingStatus .
common_data.integration_code Non disponible.
advertiser_id Le champ FloodlightActivity.advertiserIds liste tous les annonceurs ayant accès à l'activité Floodlight du partenaire donné.
partner_id Fourni par l'utilisateur lors de l'envoi d'une requête au service floodlightGroups.floodlightActivities.
remarketing_enabled Le champ FloodlightActivity.remarketingConfigs liste cette configuration pour chaque annonceur ayant accès à l'activité Floodlight du partenaire donné.
ssl_required Champ FloodlightActivity.sslRequired .

InsertionOrder

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ InsertionOrder.insertionOrderId .
common_data.name Champ InsertionOrder.displayName .
common_data.active Champ InsertionOrder.entityStatus .
common_data.integration_code Champ InsertionOrder.integrationDetails.integrationCode .
advertiser_id Champ InsertionOrder.advertiserId .
campaign_id Champ InsertionOrder.campaignId .
overall_budget Non disponible. Peut être calculé à l'aide du contenu du champ InsertionOrder.budget.budgetSegments .
scheduled_segments Champ InsertionOrder.budget.budgetSegments .
frequency_cap Champ InsertionOrder.frequencyCap .
default_partner_costs Champ InsertionOrder.partnerCosts .
default_target_list Non disponible.

InventorySource

Nom du champ ERFDisponibilité de l'API DV360
id Champ InventorySource.inventorySourceId .
non classifié Non disponible.
inventory_name Champ InventorySource.displayName .
exchange_id Champ InventorySource.exchange .
accessing_advertisers Champs InventorySource.readWriteAccessors et InventorySource.readAdvertiserIds .
external_id Champ InventorySource.dealId .
min_cpm_micros Champ InventorySource.rateDetails.rate.nanos , en fonction de la valeur du champ InventorySource.rateDetails.inventorySourceRateType .
min_cpm_currency_code Champ InventorySource.rateDetails.rate.currencyCode .

LineItem

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ LineItem.lineItemId .
common_data.name Champ LineItem.displayName .
common_data.active Champ LineItem.entityStatus .
common_data.integration_code Champ LineItem.integrationDetails.integrationCode .
line_item_type Champ LineItem.lineItemType .
insertion_order_id Champ LineItem.insertionOrderId .
creative_ids Champ LineItem.creativeIds .
max_cpm_advertiser_micros Champs LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros ou LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , en fonction du schéma de stratégie utilisé.
performance_goal Champs LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType ou LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , en fonction du schéma de stratégie utilisé.
goal_advertiser_micros Champ LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros .
partner_revenue_model Champ LineItem.partnerRevenueModel .
cost_tracking_pixels Champ LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec Champ LineItem.flight.dateRange.startDate .
budget.end_time_usec Champ LineItem.flight.dateRange.endDate .
budget.max_impressions Champ LineItem.budget.maxAmount si LineItem.budget.budgetUnit est BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros Champ LineItem.budget.maxAmount si LineItem.budget.budgetUnit est BUDGET_UNIT_CURRENCY .
budget.pacing_type Champ LineItem.pacing.pacingPeriod .
budget.pacing_max_impressions Champ LineItem.pacing.dailyMaxImpressions .
budget.pacing_max_spend_advertiser_micros Champ LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution Champ LineItem.pacing.pacingType .
frequency_cap Champ LineItem.frequencyCap .
partner_costs Champ LineItem.partnerCosts .
target_list Récupérable via la méthode advertisers.lineItems.bulkListAssignedTargetingOptions .

NegativeKeywordList

Nom du champ ERFDisponibilité de l'API DV360
id Champ NegativeKeywordList.negativeKeywordListId .
nom Champ NegativeKeywordList.displayName .
advertiser_id Champ NegativeKeywordList.advertiserId .

Partner

Nom du champ ERFDisponibilité de l'API DV360
common_data.id Champ Partner.partnerId .
common_data.name Champ Partner.displayName .
common_data.active Champ Partner.entityStatus .
common_data.integration_code Non disponible.
currency_code Champ Partner.generalConfig.currencyCode .
exchange_settings Champ Partner.exchangeConfig.enabledExchanges .
default_partner_costs Non disponible.
default_partner_revenue Non disponible.
default_target_list Non disponible.

Pixel

Aucune ressource ni aucun champ équivalents ne sont disponibles dans l'API Display & Video 360.

UniversalChannel

Nom du champ ERFDisponibilité de l'API DV360
id Champ Channel.channelId .
nom Champ Channel.displayName .
site_ids Récupérable via les méthodes advertisers.channels.sites.list et partners.channels.sites.list , en fonction du type de owner .
accessing_advertisers Non disponible.
is_deleted Non disponible.
is_brand_safe_channel Non disponible.

UserList

Nom du champ ERFDisponibilité de l'API DV360
id Champ FirstPartyAndPartnerAudience.firstPartyAndPartnerAudienceId .
nom Champ FirstPartyAndPartnerAudience.displayName .
data_partner_id Non disponible.
accessing_advertisers Non disponible.
partner_pricing Non disponible.
advertiser_pricings Non disponible.