Pliki odczytu elementu (ERF) to reprezentacje w formacie JSON obiektów kampanii partnera udostępnione za pomocą 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 odczytu entyfikacji do interfejsu Display & Video 360 API, aby:
- przedstawienie różnic między tymi interfejsami;
- Porównanie tabel ERF z usługami interfejsu API
- Podawanie wskazówek dotyczących pobierania jednostek 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 ERF do interfejsu Display & Video 360 API należy wziąć pod uwagę kilka kluczowych różnic, m.in.:
- Aktualność danych. Raporty ERF są generowane codziennie i komputerowo, a interfejs API pobiera najnowszą wersję zasobu.
- Struktura zasobów. Interfejs API używa innych struktur JSON niż interfejs ERF do reprezentowania tych samych typów zasobów. Niektóre zasoby, np. ustawienia kierowania na publiczne, mogą używać innej przestrzeni identyfikatorów.
- Metoda odzyskiwania. Interfejs Display & Video 360 API umożliwia pobieranie zasobów tylko indywidualnie, w listach pogrupowanych 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 ERF, które są ograniczone do identyfikatora partnera, większość zasobów interfejsu API jest ograniczona do 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”. Publiczne tabele zawierają informacje, które są dostępne i przydatne 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 za pomocą 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 interpretacji 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 bardziej szczegółowych informacji, 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 w przypadku tabel publicznych, ta usługa udostępnia identyfikatory i szczegóły opcji kierowania na potrzeby określonego typu kierowania. Przykład kodu, który demonstruje pobieranie identyfikatora opcji kierowania, znajdziesz na stronie Ustaw kierowanie.
Publiczne tabele i pliki SDF
Przed wersją 7 plików SDF pliki odczytującą istotę i pliki uporządkowanych danych używają tej samej przestrzeni identyfikatorów w ustawieniach kierowania. Jeśli używasz pliku SDF i tabel publicznych ERF do interpretowania lub przypisywania ustawień kierowania za pomocą pliku SDF, możesz zamiast tego pobrać ten materiał referencyjny w formacie CSV w interfejsie Display & Video 360.
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 7 i dokumentacji referencyjnej.
Zasoby prywatne
Tabele prywatne ERF zawierają codzienny podgląd bieżących ustawień zasobów prywatnych 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 pobierać zbiorczo, korzystając z odpowiedniej metody listy w poszczególnych usługach. Struktura JSON każdego zasobu jest w interfejsie API inna niż w interfejsie ERF. Wykorzystuje ona inne nazwy pól i zasoby współdzielone.
Niektóre informacje dostępne w reprezentacji ERF zasobu, takie jak przypisane ustawienia kierowania zasobu lub witryny kanału, są reprezentowane w interfejsie API jako elementy podrzędne pierwotnego zasobu i muszą być pobierane za pomocą dodatkowych żądań interfejsu API.
Pobieranie elementów 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ą innego interfejsu 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, ograniczając większość odpowiedzi na poszczególne żądania (czyli strony) do 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 na stronie poświęconej pobieraniu dostępnych opcji kierowania .
- Dodatkowe żądania wymagane do pobrania danych kierowania Ustawienia kierowania zasobu nie są uwzględnione w obiekcie JSON interfejsu API, ale są to zasoby podrzędne, czyli przypisane opcje kierowania. Te zasoby podrzędne należy pobrać za pomocą osobnego żądania. Na przykład w przypadku każdego elementu zamówienia pobieranego za pomocą żądania
advertisers.lineItems.list
należy przesłać oddzielne żądanieadvertisers.lineItems.bulkListAssignedTargetingOptions
, aby pobrać wszystkie informacje kierowania.
Optymalizacja pobierania zasobów
Interfejs Display & Video 360 API może wymagać wysłania kilku żądań, aby pobrać tę samą ilość informacji, która jest dostępna w pojedynczym pliku odczytu entyfikacji. 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 projekt i liczba żądań na reklamodawcę na projekt. Ta struktura limitów pozwala wdrożyć rozwiązanie wielowątkowe dla wielu reklamodawców, co skróci łączny czas potrzebny do pobrania wszystkich niezbędnych zasobów. Chociaż pobieranie za pomocą stronyacji wymaga, aby wszystkie zasoby danego typu w określonym zakresie były pobierane za pomocą kolejnych wywołań, 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 np. interesują Cię tylko elementy zamówienia, które zostały zaktualizowane w ostatnim dniu, możesz użyć parametru
filter
metodyadvertisers.lineItems.list
, aby zwrócić tylko elementy zamówienia zupdateTime
większą niż podany sygnatura czasowa. Może to znacznie zmniejszyć liczbę żądań. - Zachowaj w pamięci podręcznej często używane identyfikatory, aby uniknąć zbędnych żądań 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 Display & Video 360 API BigQuery umożliwia automatyczne codzienne importowanie konfiguracji zasobów Display & Video 360 bezpośrednio do BigQuery. Konfiguracje są przechowywane w BigQuery za pomocą interfejsu API Display & Video 360 w ramach projektu zasobów. Obsługiwany jest podzbiór zasobów interfejsu API.
Więcej informacji o używaniu interfejsu Display & Video 360 API BigQuery Connector znajdziesz w tej dokumentacji Google Cloud:
- Czym jest BigQuery Data Transfer Service?
- Zaplanuj przeniesienie danych z Display & Video 360
- Transformacja danych w Display & Video 360
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 odpowiednich zasobach pobieranych za pomocą interfejsu Display & Video 360 API.
Załącznik: mapowanie pól ERF na interfejs API
Mapowanie tabel publicznych
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 ERF | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
pole.
|
nazwa |
TargetingOption.appCategoryDetails.displayName
pole.
|
Przeglądarka
Można je pobrać w ramach typu kierowania TARGETING_TYPE_BROWSER
.
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
pole.
|
is_mobile | Niedostępne. |
nazwa |
TargetingOption.browserDetails.displayName
pole.
|
DataPartner
W interfejsie API Display & Video 360 nie ma odpowiednich zasobów ani pól.
DeviceCriteria
Dostępne w typach kierowania TARGETING_TYPE_OPERATING_SYSTEM
, TARGETING_TYPE_DEVICE_MAKE_MODEL
i TARGETING_TYPE_DEVICE_TYPE
.
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
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
pole.
|
operating_system_id | Niedostępne. |
mobile_brand_name | Niedostępne. |
mobile_model_name | Niedostępne. |
mobile_make_model_id | Niedostępne. |
device_type |
DeviceType
wyliczenie.
|
GeoLocation
Można je pobrać w ramach typu kierowania TARGETING_TYPE_GEO_REGION
.
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
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 je pobrać w ramach typu kierowania TARGETING_TYPE_CARRIER_AND_ISP
.
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
id |
TargetingOption.targetingOptionId
pole.
|
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 ERF | Dostępność interfejsu DV360 API |
---|---|
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 je pobrać w ramach typu kierowania TARGETING_TYPE_EXCHANGE
.
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
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_URL
i TARGETING_TYPE_APP
.
W Display & Video 360 możesz kierować reklamy na dowolną aplikację lub dowolny adres URL, ale nie na każdą aplikację lub każdy adres URL można sporządzić raport. Jeśli chcesz usunąć z wydatków 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
Tabele poniżej mapują 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 ERF | Dostę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
pole.
|
partner_id |
Advertiser.partnerId
pole.
|
currency_code |
Advertiser.generalConfig.currencyCode
pole.
|
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 go pobrać za pomocą metody
advertisers.targetingTypes.assignedtargetingOptions.list
w typie kierowania
TARGETING_TYPE_CHANNEL
. Jeśli
AssignedTargetingOption.channelDetails.negative
jest ustawione na „prawda”, kanał jest kierowany negatywnie.
|
dcm_configuration | Niedostępne. |
dcm_network_id |
Advertiser.adServerConfig.cmHybridConfig.cmAccountId
pole.
|
dcm_advertiser_id |
Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds
zawiera listę identyfikatorów reklamodawców CM360, którzy 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 ERF | Dostępność interfejsu DV360 API |
---|---|
common_data.id |
Campaign.campaignId
pole.
|
common_data.name |
Campaign.displayName
pole.
|
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 | Niedostępne |
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
pole.
|
objective_description |
Campaign.campaignGoal.performanceGoal.performanceGoalString
pole.
|
metric_amount_micros |
Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros
pole.
|
Kreacje
Nazwa pola ERF | Dostę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
pole.
|
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 ERF | Dostępność interfejsu DV360 API |
---|---|
id |
CustomList.customListId
pole.
|
nazwa |
CustomList.displayName
pole.
|
opis | Niedostępne. |
advertiser_id | Niedostępne. |
FloodlightActivity
Nazwa pola ERF | Dostę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 | Podany 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 ERF | Dostę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
pole.
|
frequency_cap |
InsertionOrder.frequencyCap
pole.
|
default_partner_costs |
InsertionOrder.partnerCosts
pole.
|
default_target_list | Niedostępne. |
InventorySource
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
id |
InventorySource.inventorySourceId
pole.
|
niesklasyfikowany | Niedostępne. |
inventory_name |
InventorySource.displayName
pole.
|
exchange_id |
InventorySource.exchange
pole.
|
accessing_advertisers |
InventorySource.readWriteAccessors
i
InventorySource.readAdvertiserIds
|
external_id |
InventorySource.dealId
pole.
|
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
NegativeKeywordList
Nazwa pola ERF | Dostępność interfejsu DV360 API |
---|---|
id |
NegativeKeywordList.negativeKeywordListId
pole.
|
nazwa |
NegativeKeywordList.displayName
pole.
|
advertiser_id |
NegativeKeywordList.advertiserId
pole.
|
Partner
Nazwa pola ERF | Dostę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 ERF | Dostępność interfejsu DV360 API |
---|---|
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 ERF | Dostępność interfejsu DV360 API |
---|---|
id |
FirstPartyAndPartnerAudience.firstPartyAndPartnerAudienceId
pole.
|
nazwa |
FirstPartyAndPartnerAudience.displayName
pole.
|
data_partner_id | Niedostępne. |
accessing_advertisers | Niedostępne. |
partner_pricing | Niedostępne. |
advertiser_pricings | Niedostępne. |