Migracja z plików odczytu elementu

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 7dokumentacji 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 żądanie advertisers.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 metody advertisers.lineItems.list, aby zwrócić tylko elementy zamówienia z updateTime 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:

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 ERFDostę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 ERFDostę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_MODELTARGETING_TYPE_DEVICE_TYPE.

Nazwa pola ERFDostę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 ERFDostę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 ERFDostę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 ERFDostę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 ERFDostę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_URLTARGETING_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 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  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 ERFDostę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 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  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 ERFDostępność interfejsu DV360 API
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 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 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  pole.
frequency_cap InsertionOrder.frequencyCap  pole.
default_partner_costs InsertionOrder.partnerCosts  pole.
default_target_list Niedostępne.

InventorySource

Nazwa pola ERFDostę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

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  pole.
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  pole.
budget.start_time_usec LineItem.flight.dateRange.startDate  pole.
budget.end_time_usec LineItem.flight.dateRange.endDate  pole.
budget.max_impressions LineItem.budget.maxAmount pole, jeśli LineItem.budget.budgetUnit jest BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros LineItem.budget.maxAmount pole, jeśli LineItem.budget.budgetUnit jest 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  pole.
budget.pacing_distribution LineItem.pacing.pacingType  pole.
frequency_cap LineItem.frequencyCap  pole.
partner_costs LineItem.partnerCosts  pole.
target_list Można pobierać za pomocą metody advertisers.lineItems.bulkListAssignedTargetingOptions .

NegativeKeywordList

Nazwa pola ERFDostępność interfejsu DV360 API
id NegativeKeywordList.negativeKeywordListId  pole.
nazwa NegativeKeywordList.displayName  pole.
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 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 ERFDostę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.