Migrer depuis des fichiers de lecture des entités

Les fichiers de lecture des entités sont arrêté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 fichiers ERF ne sont plus générés. Utilisez l'API Display & Video 360 pour récupérer les 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 de l'ERF à des champs de ressources d'API comparables

Présentation

Lorsque vous passez des fichiers 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 d'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.
• Portée Contrairement aux ERF, qui sont définis par l'ID du partenaire, la plupart des ressources 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 "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 ERF 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.

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 des tables publiques de l'ERF devront être récupérées à nouveau via l'API.

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 pour les tables publiques, ce service fournit les ID et les détails des options de ciblage pour un type de ciblage spécifique. Reportez-vous à notre page Définir le ciblage pour obtenir un exemple de code illustrant la récupération des ID d'option de ciblage.

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

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 que vous utilisez des tableaux publics ERF pour interpréter ou attribuer des paramètres de ciblage à l'aide des fichiers SDF, vous pouvez télécharger cette documentation 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 et dans ERF, car elle utilise des noms de champ différents et des ressources partagées.

Certaines informations disponibles dans la représentation ERF d'une ressource, telles que ses paramètres de ciblage attribués 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 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. à l'exception des enfants directs d'un partenaire, tels que les annonceurs et les chaînes détenues par un partenaire.
• Pagination. Les méthodes de liste de l'API utilisent la pagination pour garantir que les réponses ont 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 une section de notre guide sur le 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 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 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 récupération des 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 à l'aide de limites de taux de requêtes par annonceur et par projet. Cette structure de quotas vous permet de mettre en œuvre 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 chaque jour. 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:

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

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 extraites via l'API Display &Video 360.

Annexe: Mapper des champs ERF avec l'API

Mappage de 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

Elles peuvent être récupérées avec le type de ciblage TARGETING_TYPE_APP_CATEGORY.

Nom du champ ERF	Disponibilité 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 ERF	Disponibilité de l'API DV360
id	Champ TargetingOption.targetingOptionId .
is_mobile	Non disponible.
nom	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 ERF	Disponibilité 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	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 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.

Isp

Elles peuvent être récupérées 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.
nom	TargetingOption.carrierAndIspDetails.displayName .
secondary_criteria_id	TargetingOption.targetingOptionId .

Langue

Elles peuvent être récupérées avec le type de ciblage TARGETING_TYPE_LANGUAGE.

Nom du champ ERF	Disponibilité de l'API DV360
id	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 ERF	Disponibilité 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 correspondre à un autre, cela ne garantit pas qu'ils utilisent 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	Champ Advertiser.advertiserId .
common_data.name	Champ Advertiser.displayName .
common_data.active	Champ Advertiser.entityStatus .
common_data.integration_code	Advertiser.integrationDetails.integrationCode .
partner_id	Champ Advertiser.partnerId .
currency_code	Advertiser.generalConfig.currencyCode .
timezone_code	Advertiser.generalConfig.timeZone .
landing_page_url	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", le canal est ciblé de manière négative.
dcm_configuration	Non disponible.
dcm_network_id	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 ERF	Disponibilité de l'API DV360
common_data.id	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	Récupérable via la méthode advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
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 ERF	Disponibilité de l'API DV360
common_data.id	Champ Creative.creativeId .
common_data.name	Creative.displayName .
common_data.active	Champ Creative.entityStatus .
common_data.integration_code	Creative.integrationCode .
advertiser_id	Creative.advertiserId .
dcm_placement_id	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 ERF	Disponibilité de l'API DV360
id	Champ CustomList.customListId .
nom	Champ CustomList.displayName .
description	Non disponible.
advertiser_id	Non disponible.

FloodlightActivity

Nom du champ ERF	Disponibilité de l'API DV360
common_data.id	Champ FloodlightActivity.floodlightActivityId .
common_data.name	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 ERF	Disponibilité de l'API DV360
common_data.id	Champ InsertionOrder.insertionOrderId .
common_data.name	Champ InsertionOrder.displayName .
common_data.active	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	Récupérable via la méthode advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

InventorySource

Nom du champ ERF	Disponibilité de l'API DV360
id	InventorySource.inventorySourceId .
non classifié	Non disponible.
inventory_name	InventorySource.displayName .
exchange_id	Champ InventorySource.exchange .
accessing_advertisers	Champs InventorySource.readWriteAccessors et InventorySource.readAdvertiserIds .
external_id	InventorySource.dealId .
min_cpm_micros	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	Champ LineItem.lineItemId .
common_data.name	LineItem.displayName .
common_data.active	Champ LineItem.entityStatus .
common_data.integration_code	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	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	LineItem.partnerCosts .
target_list	Récupérable via la méthode advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

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

Partner

Nom du champ ERF	Disponibilité 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	Partner.exchangeConfig.enabledExchanges .
default_partner_costs	Non disponible.
default_partner_revenue	Non disponible.
default_target_list	Non disponible.

Pixel

Il n'existe pas de ressource ni de champ équivalents dans l'API Display &Video 360.

UniversalChannel

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