Migracja z plików odczytu elementu

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 żądanie advertisers.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 metody advertisers.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:

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 FUNKCJADostępność interfejsu DV360 API
id TargetingOption.targetingOptionId .
nazwa TargetingOption.appCategoryDetails.displayName .

Przeglądarka

Można pobierać z typem kierowania TARGETING_TYPE_BROWSER.

Nazwa pola FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostępność interfejsu DV360 API
id CustomList.customListId .
nazwa CustomList.displayName .
opis Niedostępne.
advertiser_id Niedostępne.

FloodlightActivity

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

Nazwa pola FUNKCJADostępność interfejsu DV360 API
common_data.id LineItem.lineItemId .
common_data.name LineItem.displayName .
common_data.active LineItem.entityStatus .
common_data.integration_code LineItem.integrationDetails.integrationCode .
line_item_type LineItem.lineItemType .
insertion_order_id LineItem.insertionOrderId .
creative_ids LineItem.creativeIds .
max_cpm_advertiser_micros LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros lub LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , w zależności od zastosowanego schematu strategii.
performance_goal LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType lub LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , w zależności od zastosowanego schematu strategii.
goal_advertiser_micros LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros .
partner_revenue_model LineItem.partnerRevenueModel .
cost_tracking_pixels LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec LineItem.flight.dateRange.startDate .
budget.end_time_usec LineItem.flight.dateRange.endDate .
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 .
budget.pacing_max_impressions LineItem.pacing.dailyMaxImpressions .
budget.pacing_max_spend_advertiser_micros LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution LineItem.pacing.pacingType .
frequency_cap LineItem.frequencyCap .
partner_costs LineItem.partnerCosts .
target_list Można pobierać za pomocą metody advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

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

Partner

Nazwa pola FUNKCJADostę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 FUNKCJADostę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 FUNKCJADostę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.