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 qui, sur demande, sont générés quotidiennement et disponibles via Google Cloud Storage.

Les ERF ont été abandonnés en juin 2021. À compter du 31 octobre 2024, les ERF seront officiellement abandonnés et ne seront plus générés. Nous encourageons tous les utilisateurs existants du fichier de lecture des entités à migrer vers l'API Display & Video 360 afin de continuer à récupérer les ressources Display & Video 360.

Ce guide explique comment effectuer la migration des fichiers de lecture des entités vers l'API Display & Video 360 en procédant comme suit:

• Présenter les différences entre les deux interfaces
• Comparer les tables ERF aux services d'API
• Fournir des conseils sur la récupération d'entités via l'API
• Reconnaître les écarts de données existants
• Présentation d'un mappage de tous les champs ERF avec les champs de ressources d'API comparables

Présentation

Lorsque vous passez des ERF à l'API Display & Video 360, vous devez prendre en compte un certain nombre de différences clés, y compris les suivantes:

• Fraîcheur des données. Les ERF sont générés quotidiennement et de manière groupée pendant que l'API récupère la version la plus récente d'une ressource.
• Structure des ressources. L'API utilise des structures JSON différentes de celles d'ERF pour représenter les mêmes types de ressources. Certaines ressources, telles que les paramètres de ciblage publics, peuvent utiliser un espace d'ID différent.
• Méthode de récupération. Contrairement aux fichiers JSON bruts fournis par ERF, l'API Display & Video 360 permet uniquement de récupérer des ressources individuellement, dans des listes paginées ou via des transferts de données BigQuery.
• Portée : Contrairement aux ERF, qui sont limités par l'ID de partenaire, la plupart des ressources d'API sont limitées par la référence 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 "publiques" et "privées". Les tableaux publics fournissent des informations disponibles et applicables à tous les utilisateurs, telles que les valeurs de ciblage. Les tableaux privés fournissent des données spécifiques à un partenaire, comme les ressources de création ou d'élément de campagne.

L'API Display & Video 360 n'utilise pas cette dichotomie. Toutes ces informations peuvent être récupérées via divers services et différentes structures JSON. Cette section compare les informations fournies via les tables ERF publiques et privées avec celles mises à disposition via les ressources et les services de l'API Display & Video 360.

Informations publiques

Les tables publiques ERF fournissent des supports 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 importées via l'interface utilisateur. Ces supports de référence sont les mêmes pour tous les utilisateurs. Ils se composent d'un ID numérique utilisé pour la mise en correspondance et d'autres détails descriptifs, tels qu'un nom à afficher.

Avertissement :Étant donné que l'API Display & Video 360 utilise un espace d'ID différent pour les paramètres de ciblage, toutes les informations mises en cache dans les tables publiques ERF devront être récupérées à nouveau via l'API.

Lorsque vous utilisez l'API Display & Video 360, vous pouvez récupérer les informations de référence sur le ciblage via le service targetingTypes.targetingOptions. Comme pour les tables publiques, ce service fournit les ID et les détails des 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 d'option de ciblage.

Remarque :Bien que les requêtes adressées au service targetingTypes.targetingOptions nécessitent une référence annonceur, les informations récupérées doivent être identiques pour tous les annonceurs.

Tables publiques et fichiers de données structurées

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

À partir de la v7, 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 SDF des fichiers ERF et s'aligner davantage sur l'API Display & Video 360. Pour en savoir plus, consultez le guide de migration v7 et la documentation de référence.

Ressources privées

Les tables privées ERF fournissent un instantané quotidien des paramètres actuels des ressources privées appartenant à un partenaire. En raison du volume important de ressources pouvant être créées sous un même partenaire, ces fichiers peuvent être 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 "list" de chaque service. La structure JSON de chaque ressource est différente dans l'API par rapport à ERF, car elle utilise des noms de champs et des ressources partagées différents.

Certaines informations disponibles dans la représentation ERF d'une ressource, telles que les paramètres de ciblage attribués à une ressource ou les sites d'un canal, 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 en important automatiquement les données dans BigQuery.

Requêtes API directes

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

• Champ d'application requis. Contrairement aux ERF, qui sont définis par partenaire, la plupart des ressources de l'API sont définies par annonceur. Pour récupérer toutes les ressources d'un type donné, telles que des éléments de campagne, pour un partenaire, vous devrez peut-être envoyer une requête de liste individuelle pour chaque annonceur enfant de ce partenaire. à l'exception des enfants directs d'un partenaire (annonceurs et chaînes appartenant à un partenaire, par exemple).
• Pagination Les méthodes de liste d'API utilisent la pagination pour garantir que les réponses sont dans une taille raisonnable, en limitant la plupart des pages ou réponses aux requêtes individuelles à 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. Vous trouverez un exemple de code de pagination d'une réponse de liste dans une section de notre guide sur le ciblage concernant la récupération des options de ciblage disponibles .
• Des demandes supplémentaires sont 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 requête 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 afin de récupérer toutes les informations de ciblage.

Optimiser la récupération de ressources

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

• Envoyer des requêtes simultanées à l'API L'API Display & Video 360 protège l'infrastructure en utilisant des limites de débit par annonceur et par projet. Cette structure de quotas vous permet de mettre en œuvre une solution multithread pour plusieurs annonceurs, ce qui réduira le temps total nécessaire pour récupérer toutes les ressources nécessaires. Bien que la pagination nécessite que toutes les ressources d'un type situé dans un certain champ d'application soient récupérées via des appels consécutifs, la récupération des ressources d'un autre champ d'application ou d'un autre type peut être effectuée simultanément.
• Utilisez des filtres et triez par paramètres dans vos appels de liste pour ne récupérer que les ressources pertinentes. Par exemple, si vous n'êtes intéressé que par les éléments de campagne mis à jour au cours du dernier jour, 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 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 d'options de ciblage et les ID d'audience Google, sont relativement stables et peuvent être stockées de manière sécurisée 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.

Consultez notre guide d'optimisation des quotas pour découvrir comment accéder efficacement à l'API Display & Video 360.

Importer dans BigQuery

Le connecteur BigQuery de l'API Display & Video 360 vous permet d'importer automatiquement et quotidiennement les configurations des ressources Display & Video 360 directement dans BigQuery. Les configurations sont stockées dans BigQuery à l'aide de la conception des 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:

• Qu'est-ce qu'un service de transfert de données BigQuery ?
• Planifier un transfert Display & Video 360
• Transformation des données dans Display & Video 360

Écarts de données connus pour les API

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

• Ordres d'insertion de type "Histoire" : Les ordres d'insertion de type "Histoire" ne peuvent pas être récupérés via l'API. Vous devez les récupérer via l'interface utilisateur de Display & Video 360.
• Sous-ensemble de champs de ressource. 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 avec l'API

Mappage de tables publiques

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

Collection d'applications

Récupération possible avec le type de ciblage TARGETING_TYPE_APP_CATEGORY.

Nom du champ ERF	Disponibilité de l'API DV360
id	TargetingOption.targetingOptionId .
name	TargetingOption.appCategoryDetails.displayName .

Navigateur

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

Nom du champ ERF	Disponibilité de l'API DV360
id	TargetingOption.targetingOptionId .
is_mobile	Non disponible.
name	TargetingOption.browserDetails.displayName .

DataPartner

Il n'existe aucune ressource ni aucun champ équivalents disponibles dans l'API Display & Video 360.

DeviceCriteria

Récupérable dans les types de ciblage TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL et TARGETING_TYPE_DEVICE_TYPE.

Nom du champ ERF	Disponibilité de l'API DV360
id	Champ TargetingOption.targetingOptionId ou énumération DeviceType .
is_mobile	Non disponible.
name	un champ TargetingOption.operatingSystemDetails.displayName , un champ TargetingOption.deviceMakeModelDetails.displayName ou une énumération DeviceType , selon le type de ciblage.
criteria_type	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 .

GeoLocation

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

Nom du champ ERF	Disponibilité de l'API DV360
id	TargetingOption.targetingOptionId .
canonical_name	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.

FAI

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

Nom du champ ERF	Disponibilité de l'API DV360
id	TargetingOption.targetingOptionId .
is_mobile	Non disponible.
name	TargetingOption.carrierAndIspDetails.displayName .
secondary_criteria_id	TargetingOption.targetingOptionId .

Langue

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

Nom du champ ERF	Disponibilité de l'API DV360
id	TargetingOption.targetingOptionId .
name	Non disponible. Le nom complet à afficher pour une langue est disponible dans le champ TargetingOption.languageDetails.displayName .

SiteToPlacementId

Il n'existe aucune ressource ni aucun champ équivalents disponibles dans l'API Display & Video 360.

SupportedExchange

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

Nom du champ ERF	Disponibilité de l'API DV360
id	Exchange .
name	Exchange .

UniversalSite

Il n'existe aucune ressource ni aucun champ équivalents disponibles dans l'API Display & Video 360. Des sites et des applications individuels peuvent être ciblés directement sous 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 il n'est pas possible de créer des rapports sur toutes les applications ou URL. Si vous souhaitez exclure des dépenses des applications et des URL ne pouvant pas faire l'objet de rapports, suivez les instructions du Centre d'aide DV360.

Mappage des champs de la table privée

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

Annonceur

Nom du champ ERF	Disponibilité de l'API DV360
common_data.id	Advertiser.advertiserId .
common_data.name	Advertiser.displayName .
common_data.active	Advertiser.entityStatus .
common_data.integration_code	Advertiser.integrationDetails.integrationCode .
partner_id	Advertiser.partnerId .
currency_code	Advertiser.generalConfig.currencyCode .
timezone_code	Advertiser.generalConfig.timeZone .
landing_page_url	Advertiser.generalConfig.domainUrl .
available_channel_ids	Récupération possible via la méthode advertisers.channels.list .
blacklist_channel_id	Récupération possible via la méthode advertisers.targetingTypes.assignedtargetingOptions.list sous le type de ciblage TARGETING_TYPE_CHANNEL . Si AssignedTargetingOption.channelDetails.negative est "true", le canal est ciblé par exclusion.
dcm_configuration	Non disponible.
dcm_network_id	Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id	Le champ Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds répertorie les références annonceur CM360 qui partagent la configuration Floodlight CM360.
dcm_floodlight_group_id	Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids	Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags	Non disponible.

Campaign

Nom du champ ERF	Disponibilité de l'API DV360
common_data.id	Campaign.campaignId .
common_data.name	Campaign.displayName .
common_data.active	Campaign.entityStatus .
common_data.integration_code	Non disponible.
advertiser_id	Campaign.advertiserId .
budget	Champs Campaign.campaignFlight et Campaign.campaignBudgets .
frequency_cap	Campaign.frequencyCap .
default_target_list	Récupération possible via la méthode advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
uses_video_creatives	Non disponible.
uses_display_creatives	Non disponible.
uses_audio_creatives	Non disponible.
objectif	Campaign.campaignGoal.campaignGoalType .
metric	Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description	Campaign.campaignGoal.performanceGoal.performanceGoalString .
metric_amount_micros	Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros .

Création

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

CustomAffinity

Nom du champ ERF	Disponibilité de l'API DV360
id	CustomList.customListId .
name	CustomList.displayName .
description	Non disponible.
advertiser_id	Non disponible.

FloodlightActivity

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

InsertionOrder

Nom du champ ERF	Disponibilité de l'API DV360
common_data.id	InsertionOrder.insertionOrderId .
common_data.name	InsertionOrder.displayName .
common_data.active	InsertionOrder.entityStatus .
common_data.integration_code	InsertionOrder.integrationDetails.integrationCode .
advertiser_id	InsertionOrder.advertiserId .
campaign_id	InsertionOrder.campaignId .
overall_budget	Non disponible. Cette valeur peut être calculée à l'aide du contenu du champ InsertionOrder.budget.budgetSegments .
scheduled_segments	InsertionOrder.budget.budgetSegments .
frequency_cap	InsertionOrder.frequencyCap .
default_partner_costs	InsertionOrder.partnerCosts .
default_target_list	Récupération possible via la méthode advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

InventorySource

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

LineItem

Nom du champ ERF	Disponibilité de l'API DV360
common_data.id	LineItem.lineItemId .
common_data.name	LineItem.displayName .
common_data.active	LineItem.entityStatus .
common_data.integration_code	LineItem.integrationDetails.integrationCode .
line_item_type	LineItem.lineItemType .
insertion_order_id	LineItem.insertionOrderId .
creative_ids	LineItem.creativeIds .
max_cpm_advertiser_micros	LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros ou LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , selon le schéma de stratégie utilisé.
performance_goal	LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType ou LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , selon le schéma de stratégie utilisé.
goal_advertiser_micros	LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros .
partner_revenue_model	LineItem.partnerRevenueModel .
cost_tracking_pixels	LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec	LineItem.flight.dateRange.startDate .
budget.end_time_usec	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	LineItem.pacing.pacingPeriod .
budget.pacing_max_impressions	LineItem.pacing.dailyMaxImpressions .
budget.pacing_max_spend_advertiser_micros	LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution	LineItem.pacing.pacingType .
frequency_cap	LineItem.frequencyCap .
partner_costs	LineItem.partnerCosts .
target_list	Récupération possible via la méthode advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

Nom du champ ERF	Disponibilité de l'API DV360
id	NegativeKeywordList.negativeKeywordListId .
name	NegativeKeywordList.displayName .
advertiser_id	NegativeKeywordList.advertiserId .

Partner

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

Pixel

Il n'existe aucune ressource ni aucun champ équivalents disponibles dans l'API Display & Video 360.

UniversalChannel

Nom du champ ERF	Disponibilité de l'API DV360
id	Channel.channelId .
name	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 ERF	Disponibilité de l'API DV360
id	FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId .
name	FirstAndThirdPartyAudience.displayName .
data_partner_id	Non disponible.
accessing_advertisers	Non disponible.
partner_pricing	Non disponible.
advertiser_pricings	Non disponible.