Pliki odczytu elementu (ERF) to reprezentacje JSON obiektów kampanii partnera, które na żądanie są generowane codziennie i udostępniane w Google Cloud Storage.
Funkcje ERF zostały wycofane w czerwcu 2021 r. Od 31 października 2024 r. funkcje ERF zostaną oficjalnie wycofane i przestaną być generowane. Zachęcamy wszystkich obecnych użytkowników plików odczytu elementu do przejścia na interfejs Display & Video 360 API, co pozwoli na dalsze pobieranie zasobów Display & Video 360.
Z tego przewodnika dowiesz się, jak przejść z plików odczytu encji na interfejs Display & Video 360 API. Dowiesz się z niego, jak:
- omówienie różnic między tymi dwoma interfejsami;
- Porównanie tabel ERF z usługami interfejsów API
- Udzielanie wskazówek dotyczących pobierania encji za pomocą interfejsu API
- Poznawanie obecnych luk w danych
- Mapowanie wszystkich pól FUNKCJA.BŁ na pola porównywalnych zasobów interfejsu API
Przegląd
Podczas migracji z FF do interfejsu Display & Video 360 API musisz wziąć pod uwagę kilka kluczowych różnic:
- Częstotliwość aktualizacji danych. Funkcje ERF są generowane codziennie i zbiorczo, podczas gdy interfejs API pobiera najbardziej aktualną wersję zasobów.
- 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ą korzystać z innej przestrzeni identyfikatorów.
- Metoda pobierania. Interfejs Display & Video 360 API umożliwia pobieranie zasobów tylko pojedynczo, z list podzielonych na strony lub przez transfer danych BigQuery. W przeciwieństwie do nieprzetworzonych plików JSON udostępnianych przez ERF.
- Zakres. W przeciwieństwie do zasobów ERF, których zakres obejmuje identyfikator partnera, większość zasobów interfejsu API ma zakres odpowiadający identyfikatorowi reklamodawcy. Zasoby zawarte w odpowiedziach są ograniczone do zasobów w tym zakresie.
Reprezentowanie danych ERF w interfejsie API
Pliki odczytu elementu są podzielone na tabele „Publiczne” i „Prywatne”. Tabele publiczne zawierają informacje dostępne dla wszystkich użytkowników, takie jak wartości kierowania. Tabele prywatne zawierają dane charakterystyczne dla partnera, np. zasoby kreacji lub elementu zamówienia.
Interfejs Display & Video 360 API nie stosuje tej dychotomii. Zamiast tego umożliwia pobieranie wszystkich tych informacji za pomocą różnych usług i różnych struktur JSON. W tej sekcji porównamy informacje dostępne w publicznych i prywatnych tabelach FUNKCJA.BŁ z informacjami udostępnianymi za pomocą zasobów i usług interfejsu Display & Video 360 API.
Informacje publiczne
Publiczne tabele dotyczące funkcji FUNKCJA.BŁ zawierają materiały referencyjne, z których użytkownicy mogą korzystać podczas interpretowania ustawień kierowania pobranych zasobów prywatnych i przypisywania kierowania za pomocą podzbioru wersji plików uporządkowanych danych (SDF) przesłanych przez interfejs użytkownika. Materiały referencyjne są takie same dla wszystkich użytkowników i składają się z identyfikatora liczbowego, który służy do mapowania, oraz bardziej szczegółowych informacji, takich jak wyświetlana nazwa.
Jeśli korzystasz z interfejsu Display & Video 360 API, informacje referencyjne dotyczące kierowania można pobierać za pomocą usługi targetingTypes.targetingOptions
. Podobnie jak tabele publiczne, ta usługa podaje identyfikatory i szczegóły opcji kierowania związanych z określonym typem kierowania. Na naszej istniejącej stronie Ustaw kierowanie znajdziesz przykład kodu pokazujący pobieranie identyfikatora opcji kierowania.
Tabele publiczne i pliki SDF
Przed plikami SDF w wersji 7 pliki odczytu elementu i pliki uporządkowanych danych używają tej samej przestrzeni identyfikatorów na potrzeby ustawień kierowania. Jeśli używasz plików SDF w publicznych tabelach do interpretowania lub przypisywania ustawień kierowania za pomocą plików SDF, możesz zamiast tego pobrać ten materiał referencyjny w formacie CSV za pomocą interfejsu 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ć plik SDF od plików ERF i dostosować się do interfejsu Display & Video 360 API. Więcej informacji znajdziesz w przewodniku po migracji do wersji 7 i w dokumentacji referencyjnej.
Zasoby prywatne
Tabele prywatne FUNKCJA.BŁ zawierają dzienny zrzut bieżących ustawień zasobów prywatnych należących do partnera. Z powodu ogromnej ilości zasobów, które można utworzyć w ramach jednego partnera, pliki te mogą być bardzo duże oraz trudne do pobrania i przetworzenia.
W interfejsie API każda tabela prywatna ma odpowiednią usługę, która udostępnia punkty końcowe do pobierania zasobów tego typu i zarządzania nimi. Zasoby można pobierać zbiorczo, korzystając z osobnej metody listy w każdej usłudze. Struktura JSON poszczególnych zasobów jest inna w interfejsie API niż ERF, wykorzystując inne nazwy pól i udostępnione zasoby.
Niektóre informacje dostępne w reprezentacji zasobu w ERF, takie jak przypisane ustawienia kierowania zasobu lub witryny kanału, są reprezentowane w interfejsie API jako elementy podrzędne pierwotnego zasobu i trzeba je pobrać za pomocą dodatkowych żądań do interfejsu API.
Pobieranie encji w interfejsie API
Zasoby Display & Video 360 można pobierać za pomocą bezpośrednich żądań do interfejsu API lub automatycznych importów do BigQuery.
Bezpośrednie żądania do interfejsu API
Każdy typ zasobów można pobierać za pomocą innej usługi interfejsu API. Zasoby można pobierać pojedynczo lub zbiorczo przy użyciu metody „get” lub „list” odpowiedniej usługi. Ważne właściwości metod list w interfejsie Display & Video 360 API:
- Wymagany zakres. W odróżnieniu od funkcji FUNKS, których zakres obejmuje partner, większość zasobów w interfejsie API ma zakres ograniczony przez reklamodawcę. Pobieranie wszystkich typów zasobów, np. elementów zamówienia, w ramach partnera może wymagać przesłania osobnego żądania listy dla każdego reklamodawcy podrzędnego tego partnera. Wyjątkiem są bezpośrednie elementy podrzędne partnera, np. reklamodawców i kanałów należących do partnera.
- Podział na strony. Metody list interfejsów API korzystają z podziału na strony, aby zagwarantować, że odpowiedzi mieszczą się w rozsądnym rozmiarze, co ogranicza większość odpowiedzi na poszczególne żądania (czyli liczbę stron) do 100 zasobów. Jeśli liczba odpowiednich zasobów przekracza rozmiar strony, do pobrania kolejnych stron pełnej odpowiedzi z listy wymagane są kolejne wywołania listy. Przykładowy kod, który zawiera informacje na temat pobierania dostępnych opcji kierowania w odpowiedzi na listę stronicowania, znajdziesz w sekcji przewodnika po kierowaniu reklam .
- Wymagane są dodatkowe żądania dotyczące pobierania kierowania. Ustawienia kierowania zasobu nie są uwzględniane w jego obiekcie JSON interfejsu API. Są to zasoby podrzędne nazywane przypisanymi opcjami kierowania. Te zasoby podrzędne należy pobierać za pomocą osobnego żądania. Na przykład w przypadku każdego elementu zamówienia pobranego za pomocą żądania
advertisers.lineItems.list
należy wysłać osobne żądanieadvertisers.lineItems.bulkListAssignedTargetingOptions
w celu pobrania wszystkich informacji o kierowaniu.
Optymalizacja pobierania zasobów
Interfejs Display & Video 360 API może wymagać wielu żądań w celu pobrania tej samej ilości informacji, które są dostępne w pojedynczym pliku odczytu elementu. Optymalizacja sposobu pobierania zasobów może pomóc wydajniej pobierać potrzebne dane:
- Wysyłanie żądań równoczesnych do interfejsu API. Interfejs Display & Video 360 API chroni infrastrukturę za pomocą ograniczeń liczby żądań na reklamodawcę na poziomie projektu. Taka struktura limitów umożliwia wdrożenie rozwiązania wielowątkowego dla wielu reklamodawców, co skróci łączny czas potrzebny na pobranie wszystkich niezbędnych zasobów. Chociaż podział na strony wymaga, aby wszystkie zasoby danego typu w danym zakresie były pobierane za pomocą kolejnych wywołań, pobieranie zasobów z innego zakresu lub innego typu może odbywać się jednocześnie.
- Używaj filtrów i porządkuj według parametrów w wywołaniach listy, aby pobierać tylko istotne 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
metodyadvertisers.lineItems.list
, aby zwracać tylko te elementy zamówienia, których wartośćupdateTime
jest większa od podanej sygnatury czasowej. W ten sposób możesz znacznie zmniejszyć liczbę potrzebnych próśb. - Regularnie używane identyfikatory w pamięci podręcznej, aby uniknąć niepotrzebnych żądań do interfejsu API. Niektóre informacje referencyjne, np. identyfikatory opcji kierowania i identyfikatory odbiorców Google, są stosunkowo stabilne i można je bezpiecznie przechowywać, aby uniknąć konieczności pobierania ich przy każdym użyciu. Wartości w pamięci podręcznej należy jednak sprawdzać co tydzień, aby uwzględnić rzadkie zmiany lub przypadki wycofania.
Więcej informacji o efektywnym dostępie do interfejsu Display & Video 360 API znajdziesz w naszym przewodniku po optymalizacji limitów.
Importowanie do BigQuery
Oprogramowanie sprzęgające BigQuery interfejsu API Display & Video 360 umożliwia codzienne automatyczne importowanie konfiguracji zasobów Display & Video 360 bezpośrednio do BigQuery. Konfiguracje są przechowywane w BigQuery z wykorzystaniem projektu 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 z interfejsem Display & Video 360 API znajdziesz w dokumentacji chmurowej:
- Czym jest BigQuery Data Transfer Service?
- Planowanie przeniesienia z Display & Video 360
- Transformacja danych w Display & Video 360
Znane luki w danych interfejsu API
Podczas migracji z FERF do Display & Video 360 API możesz napotkać zauważalne luki w danych, takie jak:
- Zamówienia reklamowe typu sekwencja. Zamówień reklamowych typu sekwencja nie można pobrać przez interfejs API. Należy je pobierać przy użyciu interfejsu Display & Video 360.
- Podzbiór pól zasobów. Niewielka liczba pól zasobów obecnych w obiektach ERF nie jest dostępna w odpowiadających im zasobach pobranych za pomocą interfejsu Display & Video 360 API.
Dodatek: mapowanie pól ERF do interfejsu API
Mapowanie tabeli publicznej
Poniższe tabele mapują pola tabel publicznych ERF na istniejące typy kierowania i pola opcji kierowania w interfejsie Display & Video 360 API. Chociaż wartość jednego pola może być zmapowana na inne, nie gwarantuje to, że będzie używać tego samego typu danych, wartości wyliczeniowych czy przestrzeni identyfikatorów.
Zbieranie aplikacji
Można pobierać w ramach typu kierowania TARGETING_TYPE_APP_CATEGORY
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
nazwa |
TargetingOption.appCategoryDetails.displayName
.
|
Przeglądarka
Można pobierać z typem kierowania TARGETING_TYPE_BROWSER
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
is_mobile | Niedostępne. |
nazwa |
TargetingOption.browserDetails.displayName
.
|
DataPartner
W interfejsie Display & Video 360 API nie ma odpowiedników takich zasobów ani pól.
DeviceCriteria
Można go pobrać w ramach typów kierowania TARGETING_TYPE_OPERATING_SYSTEM
, TARGETING_TYPE_DEVICE_MAKE_MODEL
i TARGETING_TYPE_DEVICE_TYPE
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
lub wyliczenie
DeviceType
.
|
is_mobile | Niedostępne. |
nazwa |
W zależności od typu kierowania pole
TargetingOption.operatingSystemDetails.displayName
,
TargetingOption.deviceMakeModelDetails.displayName
lub
wyliczenie
DeviceType
.
|
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 pobierać z typem kierowania TARGETING_TYPE_GEO_REGION
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
canonical_name |
TargetingOption.geoRegionDetails.displayName
.
|
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ć z typem kierowania TARGETING_TYPE_CARRIER_AND_ISP
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
is_mobile | Niedostępne. |
nazwa |
TargetingOption.carrierAndIspDetails.displayName
.
|
secondary_criteria_id |
TargetingOption.targetingOptionId
.
|
Język
Można pobierać z typem kierowania TARGETING_TYPE_LANGUAGE
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
.
|
nazwa | Niedostępne. Pełna nazwa wyświetlana w przypadku danego języka jest dostępna w polu
TargetingOption.languageDetails.displayName
.
|
SiteToPlacementId
W interfejsie Display & Video 360 API nie ma odpowiedników takich zasobów ani pól.
SupportedExchange
Można pobierać z typem kierowania TARGETING_TYPE_EXCHANGE
.
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
Wyliczenie
Exchange
.
|
nazwa |
Wyliczenie
Exchange
.
|
UniversalSite
W interfejsie Display & Video 360 API nie ma odpowiedników takich zasobów ani pól. Możesz kierować reklamy bezpośrednio na poszczególne witryny i aplikacje w ramach typów kierowania TARGETING_TYPE_URL
i TARGETING_TYPE_APP
.
W Display & Video 360 można kierować reklamy na dowolną aplikację lub adres URL, ale nie wszystkie aplikacje i adresy URL mogą być objęte raportowaniem. Jeśli chcesz usunąć z budżetu aplikacje i adresy URL, których nie można raportować, postępuj zgodnie z instrukcjami w Centrum pomocy DV360.
Mapowanie pola tabeli prywatnej
Poniższe tabele mapują pola tabel prywatnych ERF na istniejące pola lub usługi w interfejsie Display & Video 360 API. Chociaż wartość jednego pola może być mapowana na inne, nie gwarantuje to, że będzie używać tego samego typu danych, wartości wyliczeniowych lub przestrzeni identyfikatorów.
Reklamodawca
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
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 | Można pobierać za pomocą metody
advertisers.channels.list
.
|
blacklist_channel_id | Można pobierać za pomocą metody
advertisers.targetingTypes.assignedtargetingOptions.list
w ramach typu kierowania
TARGETING_TYPE_CHANNEL
. Jeśli parametr
AssignedTargetingOption.channelDetails.negative
ma wartość prawda, na kanał ma kierowanie wykluczające.
|
dcm_configuration | Niedostępne. |
dcm_network_id |
Advertiser.adServerConfig.cmHybridConfig.cmAccountId
.
|
dcm_advertiser_id |
Pole
Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds
zawiera listę identyfikatorów reklamodawców CM360, które mają konfigurację Floodlight CM360.
|
dcm_floodlight_group_id |
Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId
.
|
dcm_syncable_site_ids |
Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds
.
|
enable_oba_tags | Niedostępne. |
Kampania
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
common_data.id |
Campaign.campaignId
.
|
common_data.name |
Campaign.displayName
.
|
common_data.active |
Campaign.entityStatus
.
|
common_data.integration_code | Niedostępne. |
advertiser_id |
Campaign.advertiserId
.
|
budżet |
Campaign.campaignFlight
i
Campaign.campaignBudgets
.
|
frequency_cap |
Campaign.frequencyCap
.
|
default_target_list | Można pobierać 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
.
|
wskaźnik |
Campaign.campaignGoal.performanceGoal.performanceGoalType
.
|
objective_description |
Campaign.campaignGoal.performanceGoal.performanceGoalString
.
|
metric_amount_micros |
Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros
.
|
Kreacja
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
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
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
CustomList.customListId
.
|
nazwa |
CustomList.displayName
.
|
opis | Niedostępne. |
advertiser_id | Niedostępne. |
FloodlightActivity
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
common_data.id |
FloodlightActivity.floodlightActivityId
.
|
common_data.name |
FloodlightActivity.displayName
.
|
common_data.active |
FloodlightActivity.servingStatus
.
|
common_data.integration_code | Niedostępne. |
advertiser_id |
W polu
FloodlightActivity.advertiserIds
znajduje się lista wszystkich reklamodawców z dostępem do aktywności Floodlight w ramach danego partnera.
|
partner_id | Podane przez użytkownika podczas przesyłania żądania do usługi floodlightGroups.floodlightActivities . |
remarketing_enabled |
Pole
FloodlightActivity.remarketingConfigs
zawiera tę konfigurację dla każdego reklamodawcy z dostępem do aktywności Floodlight w ramach danego partnera.
|
ssl_required |
FloodlightActivity.sslRequired
.
|
InsertionOrder
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
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 | Niedostępne. Można ją obliczyć na podstawie zawartości pola
InsertionOrder.budget.budgetSegments
.
|
scheduled_segments |
InsertionOrder.budget.budgetSegments
.
|
frequency_cap |
InsertionOrder.frequencyCap
.
|
default_partner_costs |
InsertionOrder.partnerCosts
.
|
default_target_list | Można pobierać za pomocą metody
advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions
.
|
InventorySource
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
InventorySource.inventorySourceId
.
|
niesklasyfikowane | 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
.
|
LineItem
NegativeKeywordList
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
NegativeKeywordList.negativeKeywordListId
.
|
nazwa |
NegativeKeywordList.displayName
.
|
advertiser_id |
NegativeKeywordList.advertiserId
.
|
Partner
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
common_data.id |
Partner.partnerId
.
|
common_data.name |
Partner.displayName
.
|
common_data.active |
Partner.entityStatus
.
|
common_data.integration_code | Niedostępne. |
currency_code |
Partner.generalConfig.currencyCode
.
|
exchange_settings |
Partner.exchangeConfig.enabledExchanges
.
|
default_partner_costs | Niedostępne. |
default_partner_revenue | Niedostępne. |
default_target_list | Niedostępne. |
Pixel
W interfejsie Display & Video 360 API nie ma odpowiedników takich zasobów ani pól.
UniversalChannel
Nazwa pola FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
Channel.channelId
.
|
nazwa |
Channel.displayName
.
|
site_ids | Można pobierać 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 FUNKCJA | Dostępność interfejsu DV360 API |
---|---|
id |
FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId
.
|
nazwa |
FirstAndThirdPartyAudience.displayName
.
|
data_partner_id | Niedostępne. |
accessing_advertisers | Niedostępne. |
partner_pricing | Niedostępne. |
advertiser_pricings | Niedostępne. |