Migracja z plików odczytu elementu

Pliki odczytu elementu to reprezentacje w formacie JSON obiektów kampanii partnera udostępnione w Google Cloud Storage.

Raporty ERF zostały wycofane w czerwcu 2021 r. i wycofane 31 października 2024 r. Pliki ERF nie są już generowane. Aby pobierać zasoby Display & Video 360, używaj interfejsu Display & Video 360 API.

W tym przewodniku znajdziesz informacje o tym, jak przejść z plików odczytującą z interfejsem Display & Video 360 API, aby:

  • Omówienie różnic między tymi dwoma interfejsami
  • Porównanie tabel ERF z usługami interfejsu API
  • Udzielanie wskazówek dotyczących pobierania elementów za pomocą interfejsu API
  • Przyznawanie istniejących luk w danych
  • Prezentacja mapowania wszystkich pól ERF na porównywalne pola zasobów interfejsu API

Omówienie

Podczas migracji z interfejsu ERF do interfejsu Display & Video 360 API należy wziąć pod uwagę kilka kluczowych różnic, m.in.:

  • Częstotliwość aktualizacji danych. Raporty ERF są generowane codziennie i komputerowo, a interfejs API pobiera najnowszą wersję zasobu.
  • Struktura zasobów. Do reprezentowania tych samych typów zasobów interfejs API używa innych struktur JSON niż ERF. Niektóre zasoby, np. publiczne ustawienia kierowania, mogą używać innej przestrzeni identyfikatorów.
  • Metoda pobierania. Interfejs Display & Video 360 API umożliwia pobieranie zasobów indywidualnie, na stronach lub za pomocą transferów danych BigQuery, a nie w postaci nieprzetworzonych plików JSON udostępnianych przez interfejs ERF.
  • Zakres. W przeciwieństwie do FUNKCJA.BŁ, które są ograniczone do identyfikatora partnera, większość zasobów interfejsu API ma zakres określony według identyfikatora reklamodawcy. Zasoby uwzględnione w odpowiedziach są ograniczone do zasobów w ramach tego zakresu.

Reprezentacja danych ERF w interfejsie API

Pliki odczytu elementu są rozdzielone na tabele „Publiczne” i „Prywatne”. Tabele publiczne zawierają informacje, które są dostępne dla wszystkich użytkowników, np. wartości kierowania. Tabele prywatne zawierają dane dotyczące konkretnego partnera, takie jak zasoby kreacji lub elementów zamówienia.

Interfejs API Display & Video 360 nie stosuje tej dychotomii, ponieważ wszystkie te informacje można pobrać za pomocą różnych usług i za pomocą różnych struktur JSON. W tej sekcji porównujemy informacje podawane w publicznych i prywatnych tabelach ERF z tymi udostępnianymi w ramach zasobów i usług interfejsu API Display & Video 360.

Informacje publiczne

Tablice publiczne ERF stanowią materiały referencyjne, których użytkownicy mogą używać do interpretowania ustawień kierowania w wyodebranych zasobach prywatnych oraz do przypisywania kierowania do podzbioru wersji plików uporządkowanych danych (SDF) przesłanych za pomocą interfejsu użytkownika. Te materiały referencyjne są takie same dla wszystkich użytkowników i składają się z liczbowego identyfikatora używanego do mapowania oraz dodatkowych informacji opisowych, takich jak wyświetlana nazwa.

Korzystając z interfejsu Display & Video 360 API, możesz pobierać informacje referencyjne dotyczące kierowania za pomocą usługi targetingTypes.targetingOptions. Podobnie jak tabele publiczne, ta usługa udostępnia identyfikatory i szczegóły opcji kierowania dla określonego typu kierowania. Przykład kodu pokazujący pobieranie identyfikatora opcji kierowania znajdziesz na stronie Ustaw kierowanie.

Publiczne tabele i pliki SDF

Przed wersją 7 plików SDF pliki odczytującą informacje o podmiocie i pliki uporządkowanych danych używają tej samej przestrzeni identyfikatorów w ustawieniach kierowania. Jeśli jesteś użytkownikiem plików SDF i używasz tabel publicznych ERF do interpretowania lub przypisywania ustawień kierowania za pomocą plików SDF, możesz pobrać te materiały referencyjne w formacie CSV w interfejsie Display &Video 360.

Począwszy od wersji 7, przestrzenie identyfikatorów używane przez podzbiór kolumn plików uporządkowanych danych zostały zaktualizowane, aby oddzielić SDF od ERF i jeszcze bardziej dostosować je do interfejsu Display & Video 360 API. Więcej informacji znajdziesz w przewodniku po migracji do wersji 7dokumentacji referencyjnej.

Zasoby prywatne

Tabele prywatne ERF zawierają codzienny podgląd bieżących ustawień prywatnych zasobów należących do partnera. Ze względu na ogromną liczbę zasobów, które można utworzyć w ramach jednego partnera, te pliki mogą stać się bardzo duże i trudne do pobrania oraz przetworzenia.

W interfejsie API każda tabela prywatna ma odpowiadającą jej usługę, która udostępnia punkty końcowe do pobierania i zarządzania tym typem zasobu. Zasoby można pobrać zbiorczo za pomocą odpowiedniej metody tworzenia listy dostępnej w danej usłudze. Struktura JSON każdego zasobu w interfejsie API różni się od struktury ERF, ponieważ wykorzystuje inne nazwy pól i udostępnione zasoby.

Niektóre informacje dostępne w reprezentacji zasobu w ramach ERF, takie jak przypisane ustawienia kierowania zasobu lub witryny kanału, są reprezentowane w interfejsie API jako elementy podrzędne względem oryginalnego zasobu i trzeba je pobierać przy użyciu dodatkowych żądań do interfejsu API.

Pobieranie encji w interfejsie API

Zasoby Display & Video 360 można pobierać za pomocą bezpośrednich żądań interfejsu API lub automatycznych importów do BigQuery.

Bezpośrednie żądania do interfejsu API

Każdy typ zasobu można pobrać za pomocą innej usługi API. Zasoby można pobierać pojedynczo lub zbiorczo, odpowiednio używając metody get lub list. Do ważnych właściwości metod listy interfejsu Display & Video 360 API należą:

  • Wymagany zakres. W przeciwieństwie do ERF, które są ograniczone do partnera, większość zasobów w interfejsie API jest ograniczona do reklamodawcy. Pobieranie wszystkich zasobów danego typu (np. elementów zamówienia) w ramach partnera może wymagać wysłania osobnego żądania listy dla każdego reklamodawcy podrzędnego tego partnera. Wyjątkiem są kanały podrzędne partnera, takie jak reklamodawcy i kanały należące do partnera.
  • Podział na strony. Metody listy interfejsu API korzystają z podziału na strony, aby zapewnić odpowiedni rozmiar odpowiedzi. Większość odpowiedzi na poszczególne żądania lub strony zawiera maksymalnie 100 zasobów. Jeśli liczba odpowiednich zasobów jest większa niż rozmiar strony, do pobrania kolejnych stron pełnej odpowiedzi na żądanie listy wymagane są kolejne wywołania listy. Przykład kodu, który pobiera odpowiedź z listy, znajdziesz w sekcji Przewodnika po kierowaniu dotyczącej pobierania dostępnych opcji kierowania .
  • Dodatkowe żądania wymagane do pobrania danych kierowania Ustawienia kierowania zasobu nie są uwzględniane w obiekcie JSON interfejsu API. Są to zasoby podrzędne nazywane przypisanymi opcjami kierowania. Te zasoby podrzędne należy pobrać za pomocą osobnego zapytania. Na przykład w przypadku każdego elementu zamówienia pobranego za pomocą żądania advertisers.lineItems.list trzeba wysłać osobne żądanie advertisers.lineItems.bulkListAssignedTargetingOptions, aby pobrać wszystkie informacje o kierowaniu.

Optymalizacja pobierania zasobów

Interfejs Display & Video 360 API może wymagać wysłania wielu żądań, aby pobrać tę samą ilość informacji, która jest dostępna w pojedynczym pliku odczytu informacji o podmiocie. Zoptymalizowanie sposobu pobierania zasobów może pomóc w skuteczniejszym pobieraniu potrzebnych danych:

  • Wysyłać równoczesne żądania do interfejsu API. Interfejs Display & Video 360 API chroni infrastrukturę za pomocą limitów szybkości dotyczących liczby żądań na reklamodawcę na projekt. Taka struktura limitów pozwala wdrożyć wielowątkowe rozwiązanie na potrzeby wielu reklamodawców, co pozwoli skrócić czas potrzebny na pobranie wszystkich niezbędnych zasobów. Chociaż podział na strony wymaga, aby wszystkie zasoby danego typu w określonym zakresie były pobierane w kolejnych wywołaniach, pobieranie zasobów w innym zakresie lub innego typu może odbywać się równolegle.
  • Używaj filtrów i sortowania według parametrów w wywołaniach listy, aby pobierać tylko odpowiednie zasoby. Jeśli na przykład interesują Cię tylko elementy zamówienia, które zostały zaktualizowane w ciągu ostatniego dnia, możesz użyć parametru filter metody advertisers.lineItems.list, aby zwrócić tylko elementy zamówienia o updateTime większym od określonej sygnatury czasowej. Może to znacznie zmniejszyć liczbę żądań.
  • Buforuj regularnie używane identyfikatory w pamięci podręcznej, aby uniknąć zbędnych żądań do interfejsu API. Niektóre informacje referencyjne, np. identyfikatory opcji kierowania i identyfikatory list odbiorców Google, są stosunkowo stabilne i można je bezpiecznie przechowywać, aby uniknąć konieczności ich pobierania przy każdym użyciu. Wartości w pamięci podręcznej należy jednak sprawdzać co tydzień, aby uwzględnić rzadkie zmiany lub wycofanie.

Więcej informacji o skutecznym uzyskiwaniu dostępu do interfejsu Display & Video 360 API znajdziesz w przewodniku Optymalizacja kwoty.

Importowanie do BigQuery

Oprogramowanie sprzęgające BigQuery z interfejsem Display &Video 360 API umożliwia automatyczne importowanie codziennie konfiguracji zasobów Display &Video 360 bezpośrednio do BigQuery. Konfiguracje są przechowywane w BigQuery zgodnie z projektem zasobów interfejsu Display &Video 360 API. Obsługiwany jest podzbiór zasobów interfejsu API.

Więcej informacji o używaniu oprogramowania sprzęgającego BigQuery Display & Video 360 API znajdziesz w tej dokumentacji usług w chmurze:

Znane luki w danych interfejsu API

Podczas migracji z interfejsu ERF do interfejsu Display & Video 360 API możesz napotkać znaczne luki w danych, np.:

  • Zamówienia reklamowe typu sekwencja. Zamówienia reklamowe typu sekwencja nie mogą być pobierane za pomocą interfejsu API. Należy je pobierać za pomocą interfejsu użytkownika Display & Video 360.
  • Podzbiór pól zasobu. Niewielka liczba pól zasobów w obiektach ERF jest niedostępna w odpowiadających im zasobach pobieranych przez interfejs Display &Video 360 API.

Załącznik: mapowanie pól ERF na interfejs API

Mapowanie tabeli publicznej

W tabeli poniżej mapujemy pola publicznych tabel ERF na istniejące typy kierowania i pola opcji kierowania w interfejsie API Display & Video 360. Chociaż wartość jednego pola może być mapowana na inne, nie oznacza to, że wykorzystują one ten sam typ danych, wartości enumeracji lub przestrzeń identyfikatorów.

Kolekcja aplikacji

Można je pobrać w ramach typu kierowania TARGETING_TYPE_APP_CATEGORY.

Nazwa pola ERFDostępność interfejsu API w DV360
id TargetingOption.targetingOptionId  pole.
nazwa TargetingOption.appCategoryDetails.displayName .

Przeglądarka

Można je pobrać w ramach typu kierowania TARGETING_TYPE_BROWSER.

Nazwa pola ERFDostępność interfejsu API w DV360
id TargetingOption.targetingOptionId .
is_mobile Niedostępne.
nazwa TargetingOption.browserDetails.displayName .

DataPartner

W interfejsie API Display & Video 360 nie ma odpowiednich zasobów ani pól.

DeviceCriteria

Można pobierać w typach kierowania TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL i TARGETING_TYPE_DEVICE_TYPE.

Nazwa pola ERFDostępność interfejsu API w DV360
id TargetingOption.targetingOptionId pole lub DeviceType wyliczenie.
is_mobile Niedostępne.
nazwa TargetingOption.operatingSystemDetails.displayName , TargetingOption.deviceMakeModelDetails.displayName , DeviceType , w zależności od typu kierowania.
criteria_type TargetingOption.targetingType .
operating_system_id Niedostępne.
mobile_brand_name Niedostępne.
mobile_model_name Niedostępne.
mobile_make_model_id Niedostępne.
device_type Wyliczenie DeviceType .

GeoLocation

Można je pobrać w ramach typu kierowania TARGETING_TYPE_GEO_REGION.

Nazwa pola ERFDostępność interfejsu API w DV360
id TargetingOption.targetingOptionId  pole.
canonical_name TargetingOption.geoRegionDetails.displayName  pole.
geo_name Niedostępne.
country_code Niedostępne.
region_code Niedostępne.
city_name Niedostępne.
postal_name Niedostępne.
dma_code Niedostępne.

Isp

Można pobierać w typie kierowania TARGETING_TYPE_CARRIER_AND_ISP.

Nazwa pola ERFDostępność interfejsu API w DV360
id TargetingOption.targetingOptionId .
is_mobile Niedostępne.
nazwa TargetingOption.carrierAndIspDetails.displayName  pole.
secondary_criteria_id TargetingOption.targetingOptionId  pole.

Język

Można je pobrać w ramach typu kierowania TARGETING_TYPE_LANGUAGE.

Nazwa pola ERFDostępność interfejsu API w DV360
id TargetingOption.targetingOptionId  pole.
nazwa Niedostępne. Pełna wyświetlana nazwa języka jest dostępna w polu TargetingOption.languageDetails.displayName .

SiteToPlacementId

W interfejsie API Display & Video 360 nie ma odpowiednich zasobów ani pól.

SupportedExchange

Można pobierać w typie kierowania TARGETING_TYPE_EXCHANGE.

Nazwa pola ERFDostępność interfejsu API w DV360
id Exchange wyliczenie.
nazwa Exchange wyliczenie.

UniversalSite

W interfejsie API Display & Video 360 nie ma odpowiednich zasobów ani pól. Poszczególne witryny i aplikacje mogą być kierowane bezpośrednio w ramach typów kierowania TARGETING_TYPE_URLTARGETING_TYPE_APP. W Display & Video 360 możesz kierować reklamy na dowolną aplikację lub dowolny adres URL, ale nie możesz raportować wszystkich aplikacji i adresów URL. Jeśli chcesz usunąć z kampanii aplikacje i adresy URL, których nie można zgłosić, postępuj zgodnie z instrukcjami w Centrum pomocy DV360.

Mapowanie pól tabeli prywatnej

W tabeli poniżej mapujemy pola prywatnych tabel ERF na istniejące pola lub usługi w interfejsie API Display & Video 360. Chociaż wartość jednego pola może być mapowana na inne, nie gwarantuje to, że pola te wykorzystują ten sam typ danych, wartości wyliczenia lub przestrzeń identyfikatorów.

Reklamodawca

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id Advertiser.advertiserId  pole.
common_data.name Advertiser.displayName  pole.
common_data.active Advertiser.entityStatus  pole.
common_data.integration_code Advertiser.integrationDetails.integrationCode .
partner_id Advertiser.partnerId  pole.
currency_code Advertiser.generalConfig.currencyCode .
timezone_code Advertiser.generalConfig.timeZone  pole.
landing_page_url Advertiser.generalConfig.domainUrl  pole.
available_channel_ids Można pobierać za pomocą metody advertisers.channels.list .
blacklist_channel_id Można pobrać za pomocą metody advertisers.targetingTypes.assignedtargetingOptions.list w typie kierowania TARGETING_TYPE_CHANNEL . Jeśli parametr AssignedTargetingOption.channelDetails.negative ma wartość Prawda, kanał jest kierowany negatywnie.
dcm_configuration Niedostępne.
dcm_network_id Advertiser.adServerConfig.cmHybridConfig.cmAccountId  pole.
dcm_advertiser_id W polu Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds podano identyfikatory reklamodawców CM360, które mają tę samą konfigurację Floodlight CM360.
dcm_floodlight_group_id Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId  pole.
dcm_syncable_site_ids Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds  pole.
enable_oba_tags Niedostępne.

Kampania

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id Campaign.campaignId  pole.
common_data.name Campaign.displayName .
common_data.active Campaign.entityStatus  pole.
common_data.integration_code Niedostępne.
advertiser_id Campaign.advertiserId  pole.
budżet Campaign.campaignFlight i Campaign.campaignBudgets
frequency_cap Campaign.frequencyCap  pole.
default_target_list Można pobrać za pomocą metody advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
uses_video_creatives Niedostępne.
uses_display_creatives Niedostępne.
uses_audio_creatives Niedostępne.
cel Campaign.campaignGoal.campaignGoalType  pole.
wskaźnik Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description Campaign.campaignGoal.performanceGoal.performanceGoalString  pole.
metric_amount_micros Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros  pole.

Kreacje

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id Creative.creativeId  pole.
common_data.name Creative.displayName  pole.
common_data.active Creative.entityStatus  pole.
common_data.integration_code Creative.integrationCode  pole.
advertiser_id Creative.advertiserId  pole.
dcm_placement_id Creative.cmPlacementId .
width_pixels Creative.dimensions.widthPixels  pole.
height_pixels Creative.dimensions.heightPixels  pole.
approval_status Creative.reviewStatus  pole.
expanding_direction Creative.expandingDirection  pole.
creative_type Creative.creativeType  pole.

CustomAffinity

Nazwa pola ERFDostępność interfejsu API w DV360
id CustomList.customListId  pole.
nazwa CustomList.displayName  pole.
opis Niedostępne.
advertiser_id Niedostępne.

FloodlightActivity

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id FloodlightActivity.floodlightActivityId  pole.
common_data.name FloodlightActivity.displayName  pole.
common_data.active FloodlightActivity.servingStatus  pole.
common_data.integration_code Niedostępne.
advertiser_id FloodlightActivity.advertiserIds zawiera listę wszystkich reklamodawców, którzy mają dostęp do aktywności Floodlight w ramach danego partnera.
partner_id Podane przez użytkownika podczas wysyłania żądania do usługi floodlightGroups.floodlightActivities.
remarketing_enabled Pole FloodlightActivity.remarketingConfigs zawiera tę konfigurację dla każdego reklamodawcy, który ma dostęp do aktywności Floodlight w ramach danego partnera.
ssl_required FloodlightActivity.sslRequired  pole.

InsertionOrder

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id InsertionOrder.insertionOrderId  pole.
common_data.name InsertionOrder.displayName  pole.
common_data.active InsertionOrder.entityStatus  pole.
common_data.integration_code InsertionOrder.integrationDetails.integrationCode  pole.
advertiser_id InsertionOrder.advertiserId  pole.
campaign_id InsertionOrder.campaignId  pole.
overall_budget Niedostępne. Można je obliczyć na podstawie zawartości pola InsertionOrder.budget.budgetSegments .
scheduled_segments InsertionOrder.budget.budgetSegments .
frequency_cap InsertionOrder.frequencyCap .
default_partner_costs InsertionOrder.partnerCosts  pole.
default_target_list Można pobrać za pomocą metody advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

InventorySource

Nazwa pola ERFDostępność interfejsu API w DV360
id InventorySource.inventorySourceId  pole.
niesklasyfikowany Niedostępne.
inventory_name InventorySource.displayName .
exchange_id InventorySource.exchange .
accessing_advertisers InventorySource.readWriteAccessors i InventorySource.readAdvertiserIds
external_id InventorySource.dealId .
min_cpm_micros InventorySource.rateDetails.rate.nanos , w zależności od wartości pola InventorySource.rateDetails.inventorySourceRateType .
min_cpm_currency_code InventorySource.rateDetails.rate.currencyCode  pole.

LineItem

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id LineItem.lineItemId  pole.
common_data.name LineItem.displayName  pole.
common_data.active LineItem.entityStatus  pole.
common_data.integration_code LineItem.integrationDetails.integrationCode  pole.
line_item_type LineItem.lineItemType .
insertion_order_id LineItem.insertionOrderId  pole.
creative_ids LineItem.creativeIds  pole.
max_cpm_advertiser_micros LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros lub LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros pola, w zależności od schematu strategii.
performance_goal LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType lub LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType pola, w zależności od schematu strategii.
goal_advertiser_micros LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros  pole.
partner_revenue_model LineItem.partnerRevenueModel  pole.
cost_tracking_pixels LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec LineItem.flight.dateRange.startDate  pole.
budget.end_time_usec LineItem.flight.dateRange.endDate  pole.
budget.max_impressions LineItem.budget.maxAmount , jeśli LineItem.budget.budgetUnit to BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros LineItem.budget.maxAmount , jeśli LineItem.budget.budgetUnit to BUDGET_UNIT_CURRENCY .
budget.pacing_type LineItem.pacing.pacingPeriod  pole.
budget.pacing_max_impressions LineItem.pacing.dailyMaxImpressions  pole.
budget.pacing_max_spend_advertiser_micros LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution LineItem.pacing.pacingType .
frequency_cap LineItem.frequencyCap  pole.
partner_costs LineItem.partnerCosts  pole.
target_list Można pobierać za pomocą metody advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

Nazwa pola ERFDostępność interfejsu API w DV360
id NegativeKeywordList.negativeKeywordListId  pole.
nazwa NegativeKeywordList.displayName .
advertiser_id NegativeKeywordList.advertiserId  pole.

Partner

Nazwa pola ERFDostępność interfejsu DV360 API
common_data.id Partner.partnerId  pole.
common_data.name Partner.displayName  pole.
common_data.active Partner.entityStatus  pole.
common_data.integration_code Niedostępne.
currency_code Partner.generalConfig.currencyCode  pole.
exchange_settings Partner.exchangeConfig.enabledExchanges  pole.
default_partner_costs Niedostępne.
default_partner_revenue Niedostępne.
default_target_list Niedostępne.

Pixel

W interfejsie API Display & Video 360 nie ma odpowiednich zasobów ani pól.

UniversalChannel

Nazwa pola ERFDostępność interfejsu API w DV360
id Channel.channelId  pole.
nazwa Channel.displayName  pole.
site_ids Można je odzyskać za pomocą metod advertisers.channels.sites.list i partners.channels.sites.list , w zależności od typu owner .
accessing_advertisers Niedostępne.
is_deleted Niedostępne.
is_brand_safe_channel Niedostępne.

UserList

Nazwa pola ERFDostępność interfejsu API w DV360
id FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId .
nazwa FirstAndThirdPartyAudience.displayName .
data_partner_id Niedostępne.
accessing_advertisers Niedostępne.
partner_pricing Niedostępne.
advertiser_pricings Niedostępne.