Bermigrasi dari File Baca Entity

File Baca Entity (ERF) adalah representasi JSON dari objek kampanye partner yang tersedia melalui Google Cloud Storage.

ERF tidak digunakan lagi pada Juni 2021 dan dihentikan pada 31 Oktober 2024. ERF tidak lagi dihasilkan. Gunakan Display & Video 360 API untuk mengambil resource Display & Video 360.

Panduan ini membahas cara bermigrasi dari File Baca Entitas ke Display & Video 360 API dengan:

  • Memberikan ringkasan perbedaan antara kedua antarmuka
  • Membandingkan tabel ERF dengan layanan API
  • Memberikan panduan tentang pengambilan entitas melalui API
  • Mengakui kesenjangan data yang ada
  • Menampilkan pemetaan semua kolom ERF ke kolom resource API yang sebanding

Ringkasan

Saat bermigrasi dari ERF ke Display & Video 360 API, ada sejumlah perbedaan utama yang perlu dipertimbangkan, termasuk:

  • Keaktualan data. ERF dibuat setiap hari dan secara massal saat API mengambil versi resource terbaru.
  • Struktur resource. API menggunakan struktur JSON yang berbeda dari ERF untuk mewakili jenis resource yang sama. Beberapa resource, seperti setelan penargetan publik, dapat menggunakan ruang ID yang berbeda.
  • Metode pengambilan. Display &Video 360 API hanya memungkinkan pengambilan resource satu per satu, dalam daftar yang diberi nomor halaman, atau melalui transfer data BigQuery, berbeda dengan file JSON mentah yang disediakan oleh ERF.
  • Cakupan. Tidak seperti ERF, yang dicakup oleh ID partner, sebagian besar resource API dicakup oleh ID pengiklan. Resource yang disertakan dalam respons terbatas pada resource dalam cakupan tersebut.

Representasi data ERF di API

File Baca Entitas dipisahkan menjadi tabel "Publik" dan "Pribadi". Tabel publik menyediakan informasi yang tersedia dan berlaku untuk semua pengguna, seperti nilai penargetan. Tabel pribadi memberikan data yang spesifik untuk partner, seperti materi iklan atau resource item baris.

Display & Video 360 API tidak menggunakan dikotomi ini, tetapi membuat semua informasi ini dapat diambil melalui berbagai layanan dan menggunakan struktur JSON yang berbeda. Bagian ini membandingkan informasi yang diberikan melalui tabel ERF publik dan pribadi dengan informasi yang tersedia melalui resource dan layanan Display & Video 360 API.

Informasi publik

Tabel publik ERF menyediakan materi referensi yang dapat digunakan pengguna saat menafsirkan setelan penargetan dari resource pribadi yang diambil dan menetapkan penargetan melalui subset versi File Data Terstruktur (SDF) yang diupload melalui UI. Materi referensi ini sama untuk semua pengguna dan terdiri dari ID numerik, yang digunakan untuk pemetaan, dan detail deskriptif lainnya, seperti nama tampilan.

Saat menggunakan Display & Video 360 API, informasi referensi penargetan dapat diambil melalui layanan targetingTypes.targetingOptions. Serupa dengan tabel publik, layanan ini menyediakan ID dan detail opsi penargetan untuk jenis penargetan tertentu. Lihat halaman Menetapkan Penargetan yang ada untuk melihat contoh kode yang menunjukkan pengambilan ID opsi penargetan.

Tabel dan SDF publik

Sebelum SDF v7, File Baca Entitas dan File Data Terstruktur menggunakan ruang ID yang sama untuk setelan penargetan. Jika Anda adalah pengguna SDF yang menggunakan tabel publik ERF untuk menafsirkan atau menetapkan setelan penargetan menggunakan SDF, Anda dapat mendownload materi referensi ini dalam format CSV melalui UI Display &Video 360.

Mulai versi 7, ruang ID yang digunakan oleh sebagian kolom File Data Terstruktur telah diperbarui untuk memisahkan SDF dari ERF dan lebih selaras dengan Display & Video 360 API. Lihat panduan migrasi v7 dan dokumentasi referensi untuk mengetahui informasi selengkapnya.

Referensi pribadi

Tabel pribadi ERF memberikan ringkasan harian tentang setelan resource pribadi saat ini yang dimiliki oleh partner. Karena banyaknya resource yang dapat dibuat di bawah satu partner, file ini dapat menjadi sangat besar dan sulit didownload serta diproses.

Di API, setiap tabel pribadi memiliki layanan yang sesuai yang menyediakan endpoint untuk pengambilan dan pengelolaan jenis resource tersebut. Resource dapat diambil secara massal menggunakan metode daftar masing-masing layanan. Struktur JSON untuk setiap resource berbeda di API dibandingkan dengan ERF, yang menggunakan nama kolom dan resource bersama yang berbeda.

Informasi tertentu yang tersedia dalam representasi ERF resource, seperti setelan penargetan yang ditetapkan resource atau situs saluran, diwakili dalam API sebagai turunan dari resource asli dan harus diambil melalui permintaan API tambahan.

Pengambilan entitas di API

Resource Display & Video 360 dapat diambil melalui permintaan API langsung atau impor otomatis ke BigQuery.

Permintaan API langsung

Setiap jenis resource dapat diambil melalui layanan API yang berbeda. Resource dapat diambil satu per satu atau secara massal menggunakan metode get atau list layanan yang sesuai. Properti penting dari metode daftar Display &Video 360 API meliputi:

  • Cakupan yang diperlukan. Tidak seperti ERF, yang dicakup oleh partner, sebagian besar resource di API dicakup oleh pengiklan. Mengambil semua jenis resource, seperti item baris, di bawah partner mungkin memerlukan permintaan daftar individual untuk setiap pengiklan turunan partner tersebut. Pengecualian mencakup turunan langsung dari partner, seperti pengiklan dan channel milik partner.
  • Penomoran halaman. Metode daftar API menggunakan penomoran halaman untuk menjamin bahwa respons berada dalam ukuran yang wajar, yang membatasi sebagian besar respons permintaan individual, atau halaman, hingga 100 resource. Jika jumlah resource yang relevan lebih besar dari ukuran halaman, panggilan daftar berturut-turut diperlukan untuk mengambil halaman berikutnya dari respons daftar lengkap. Contoh kode yang membuat paging respons daftar diberikan di bagian halaman Panduan penargetan kami terkait pengambilan opsi penargetan yang tersedia .
  • Permintaan tambahan diperlukan untuk pengambilan penargetan. Setelan penargetan resource tidak disertakan dalam objek JSON API-nya, tetapi merupakan resource turunan yang dikenal sebagai opsi penargetan yang ditetapkan. Resource turunan ini harus diambil melalui permintaan terpisah. Misalnya, untuk setiap item baris yang diambil melalui permintaan advertisers.lineItems.list, permintaan advertisers.lineItems.bulkListAssignedTargetingOptions terpisah harus dibuat untuk mengambil semua informasi penargetan.

Mengoptimalkan pengambilan resource

Display & Video 360 API mungkin memerlukan beberapa permintaan untuk mengambil jumlah informasi yang sama yang tersedia dalam satu File Baca Entitas. Mengoptimalkan cara Anda mengambil resource dapat membantu mengambil data yang Anda perlukan secara lebih efisien:

  • Buat permintaan serentak ke API. Display & Video 360 API melindungi infrastruktur menggunakan batas kapasitas permintaan per pengiklan per project. Struktur kuota ini memungkinkan Anda menerapkan solusi multi-thread di beberapa pengiklan yang akan mengurangi total waktu yang diperlukan untuk mengambil semua resource yang diperlukan. Meskipun penomoran halaman mengharuskan semua resource jenis dalam cakupan tertentu diambil melalui panggilan berturut-turut, pengambilan resource dalam cakupan lain atau jenis lain dapat dilakukan secara serentak.
  • Gunakan filter dan urutkan menurut parameter dalam panggilan daftar untuk hanya mengambil resource yang relevan. Misalnya, jika Anda hanya tertarik dengan item baris yang telah diperbarui di hari terakhir, Anda dapat menggunakan parameter filter dari metode advertisers.lineItems.list agar hanya menampilkan item baris dengan updateTime lebih besar dari stempel waktu tertentu. Hal ini dapat mengurangi jumlah permintaan yang perlu dibuat secara signifikan.
  • Cache data yang digunakan secara rutin untuk menghindari permintaan API yang tidak perlu. Informasi referensi tertentu, seperti ID opsi penargetan dan ID Audiens Google, relatif stabil dan dapat disimpan dengan aman untuk menghindari kebutuhan pengambilan pada setiap penggunaan. Namun, nilai yang di-cache harus diperiksa setiap minggu untuk memperhitungkan perubahan atau penghentian yang jarang terjadi.

Lihat Panduan Pengoptimalan Kuota untuk mengetahui informasi selengkapnya tentang cara mengakses Display & Video 360 API secara efisien.

Impor ke BigQuery

Konektor BigQuery Display &Video 360 API memungkinkan Anda mengimpor konfigurasi resource Display &Video 360 secara otomatis langsung ke BigQuery setiap hari. Konfigurasi disimpan di BigQuery menggunakan desain resource Display & Video 360 API. Subkumpulan resource API didukung.

Lihat dokumentasi cloud berikut untuk mengetahui informasi selengkapnya tentang cara menggunakan Konektor BigQuery Display & Video 360 API:

Kesenjangan data API yang diketahui

Ada kesenjangan data yang signifikan yang mungkin Anda temui saat bermigrasi dari ERF ke Display & Video 360 API, seperti:

  • Pesanan pemasangan iklan cerita. Pesanan pemasangan iklan kisah tidak dapat diambil melalui API dan harus diambil melalui UI Display & Video 360.
  • Subkumpulan kolom resource. Sejumlah kecil kolom resource yang ada dalam objek ERF tidak tersedia di resource yang sesuai yang diambil melalui Display & Video 360 API.

Lampiran: Memetakan Kolom ERF ke API

Pemetaan tabel publik

Tabel di bawah memetakan kolom tabel publik ERF ke jenis penargetan dan kolom opsi penargetan yang ada di Display & Video 360 API. Meskipun nilai satu kolom mungkin dipetakan ke kolom lain, hal itu tidak menjamin bahwa kolom tersebut menggunakan jenis data, nilai enum, atau ruang ID yang sama.

Koleksi Aplikasi

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_APP_CATEGORY.

Nama Kolom ERFKetersediaan API DV360
id Kolom TargetingOption.targetingOptionId .
nama Kolom TargetingOption.appCategoryDetails.displayName .

Browser

Dapat diambil kembali bagian jenis penargetan TARGETING_TYPE_BROWSER.

Nama Kolom ERFKetersediaan API DV360
id Kolom TargetingOption.targetingOptionId .
is_mobile Tidak tersedia.
nama Kolom TargetingOption.browserDetails.displayName .

DataPartner

Tidak ada resource atau kolom yang setara yang tersedia di Display &Video 360 API.

DeviceCriteria

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_OPERATING_SYSTEM, TARGETING_TYPE_DEVICE_MAKE_MODEL, dan TARGETING_TYPE_DEVICE_TYPE.

Nama Kolom ERFKetersediaan API DV360
id Kolom TargetingOption.targetingOptionId atau enum DeviceType .
is_mobile Tidak tersedia.
nama Kolom TargetingOption.operatingSystemDetails.displayName , TargetingOption.deviceMakeModelDetails.displayName , atau DeviceType enum, bergantung pada jenis penargetan.
criteria_type Kolom TargetingOption.targetingType .
operating_system_id Tidak tersedia.
mobile_brand_name Tidak tersedia.
mobile_model_name Tidak tersedia.
mobile_make_model_id Tidak tersedia.
device_type DeviceType enum.

GeoLocation

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_GEO_REGION.

Nama Kolom ERFKetersediaan API DV360
id Kolom TargetingOption.targetingOptionId .
canonical_name Kolom TargetingOption.geoRegionDetails.displayName .
geo_name Tidak tersedia.
country_code Tidak tersedia.
region_code Tidak tersedia.
city_name Tidak tersedia.
postal_name Tidak tersedia.
dma_code Tidak tersedia.

Isp

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_CARRIER_AND_ISP.

Nama Kolom ERFKetersediaan API DV360
id Kolom TargetingOption.targetingOptionId .
is_mobile Tidak tersedia.
nama Kolom TargetingOption.carrierAndIspDetails.displayName .
secondary_criteria_id Kolom TargetingOption.targetingOptionId .

Bahasa

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_LANGUAGE.

Nama Kolom ERFKetersediaan API DV360
id Kolom TargetingOption.targetingOptionId .
nama Tidak tersedia. Nama tampilan lengkap untuk bahasa tersedia di kolom TargetingOption.languageDetails.displayName .

SiteToPlacementId

Tidak ada resource atau kolom yang setara yang tersedia di Display &Video 360 API.

SupportedExchange

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_EXCHANGE.

Nama Kolom ERFKetersediaan API DV360
id Exchange enum.
nama Exchange .

UniversalSite

Tidak ada resource atau kolom yang setara yang tersedia di Display &Video 360 API. Setiap situs dan aplikasi dapat ditargetkan secara langsung berdasarkan jenis penargetan TARGETING_TYPE_URL dan TARGETING_TYPE_APP. Di Display & Video 360, aplikasi atau URL apa pun dapat ditargetkan, tetapi tidak semua aplikasi atau URL dapat dilaporkan. Jika Anda ingin menghapus aplikasi dan URL yang tidak dapat dilaporkan dari pembelanjaan, ikuti petunjuk di Pusat Bantuan DV360.

Pemetaan kolom tabel pribadi

Tabel di bawah memetakan kolom tabel pribadi ERF ke kolom atau layanan yang ada di Display & Video 360 API. Meskipun nilai satu kolom dapat dipetakan ke kolom lain, hal itu tidak menjamin bahwa kolom tersebut menggunakan jenis data, nilai enum, atau ruang ID yang sama.

Pengiklan

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom Advertiser.advertiserId .
common_data.name Kolom Advertiser.displayName .
common_data.active Kolom Advertiser.entityStatus .
common_data.integration_code Kolom Advertiser.integrationDetails.integrationCode .
partner_id Kolom Advertiser.partnerId .
currency_code Kolom Advertiser.generalConfig.currencyCode .
timezone_code Kolom Advertiser.generalConfig.timeZone .
landing_page_url Kolom Advertiser.generalConfig.domainUrl .
available_channel_ids Dapat diambil melalui metode advertisers.channels.list .
blacklist_channel_id Dapat diambil melalui metode advertisers.targetingTypes.assignedtargetingOptions.list pada jenis penargetan TARGETING_TYPE_CHANNEL . Jika AssignedTargetingOption.channelDetails.negative bernilai benar, channel tersebut ditargetkan secara negatif.
dcm_configuration Tidak tersedia.
dcm_network_id Kolom Advertiser.adServerConfig.cmHybridConfig.cmAccountId .
dcm_advertiser_id Kolom Advertiser.adServerConfig.cmHybridConfig.cmAdvertiserIds mencantumkan ID Pengiklan CM360 yang menggunakan konfigurasi Floodlight CM360.
dcm_floodlight_group_id Kolom Advertiser.adServerConfig.cmHybridConfig.cmFloodlightConfigId .
dcm_syncable_site_ids Kolom Advertiser.adServerConfig.cmHybridConfig.cmSyncableSiteIds .
enable_oba_tags Tidak tersedia.

Kampanye

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom Campaign.campaignId .
common_data.name Kolom Campaign.displayName .
common_data.active Kolom Campaign.entityStatus .
common_data.integration_code Tidak tersedia.
advertiser_id Kolom Campaign.advertiserId .
anggaran Kolom Campaign.campaignFlight dan Campaign.campaignBudgets .
frequency_cap Kolom Campaign.frequencyCap .
default_target_list Dapat diambil melalui metode advertisers.campaigns.bulkListCampaignAssignedTargetingOptions .
uses_video_creatives Tidak tersedia.
uses_display_creatives Tidak tersedia.
uses_audio_creatives Tidak tersedia.
tujuan Kolom Campaign.campaignGoal.campaignGoalType .
metrik Kolom Campaign.campaignGoal.performanceGoal.performanceGoalType .
objective_description Kolom Campaign.campaignGoal.performanceGoal.performanceGoalString .
metric_amount_micros Kolom Campaign.campaignGoal.performanceGoal.performanceGoalAmountMicros .

Materi iklan

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom Creative.creativeId .
common_data.name Kolom Creative.displayName .
common_data.active Kolom Creative.entityStatus .
common_data.integration_code Kolom Creative.integrationCode .
advertiser_id Kolom Creative.advertiserId .
dcm_placement_id Kolom Creative.cmPlacementId .
width_pixels Kolom Creative.dimensions.widthPixels .
height_pixels Kolom Creative.dimensions.heightPixels .
approval_status Kolom Creative.reviewStatus .
expanding_direction Kolom Creative.expandingDirection .
creative_type Kolom Creative.creativeType .

CustomAffinity

Nama Kolom ERFKetersediaan API DV360
id Kolom CustomList.customListId .
nama Kolom CustomList.displayName .
deskripsi Tidak tersedia.
advertiser_id Tidak tersedia.

FloodlightActivity

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom FloodlightActivity.floodlightActivityId .
common_data.name Kolom FloodlightActivity.displayName .
common_data.active Kolom FloodlightActivity.servingStatus .
common_data.integration_code Tidak tersedia.
advertiser_id Kolom FloodlightActivity.advertiserIds mencantumkan semua pengiklan yang memiliki akses ke aktivitas Floodlight di bawah partner tertentu.
partner_id Diberikan oleh pengguna saat membuat permintaan ke layanan floodlightGroups.floodlightActivities.
remarketing_enabled Kolom FloodlightActivity.remarketingConfigs mencantumkan konfigurasi ini untuk setiap pengiklan yang memiliki akses ke aktivitas floodlight di bawah partner tertentu.
ssl_required Kolom FloodlightActivity.sslRequired .

InsertionOrder

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom InsertionOrder.insertionOrderId .
common_data.name Kolom InsertionOrder.displayName .
common_data.active Kolom InsertionOrder.entityStatus .
common_data.integration_code Kolom InsertionOrder.integrationDetails.integrationCode .
advertiser_id Kolom InsertionOrder.advertiserId .
campaign_id Kolom InsertionOrder.campaignId .
overall_budget Tidak tersedia. Dapat dihitung menggunakan konten kolom InsertionOrder.budget.budgetSegments .
scheduled_segments Kolom InsertionOrder.budget.budgetSegments .
frequency_cap Kolom InsertionOrder.frequencyCap .
default_partner_costs Kolom InsertionOrder.partnerCosts .
default_target_list Dapat diambil melalui metode advertisers.insertionOrders.bulkListInsertionOrderAssignedTargetingOptions .

InventorySource

Nama Kolom ERFKetersediaan API DV360
id Kolom InventorySource.inventorySourceId .
tidak diklasifikasikan Tidak tersedia.
inventory_name Kolom InventorySource.displayName .
exchange_id Kolom InventorySource.exchange .
accessing_advertisers Kolom InventorySource.readWriteAccessors dan InventorySource.readAdvertiserIds .
external_id Kolom InventorySource.dealId .
min_cpm_micros Kolom InventorySource.rateDetails.rate.nanos , bergantung pada nilai kolom InventorySource.rateDetails.inventorySourceRateType .
min_cpm_currency_code Kolom InventorySource.rateDetails.rate.currencyCode .

ItemBaris

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom LineItem.lineItemId .
common_data.name Kolom LineItem.displayName .
common_data.active Kolom LineItem.entityStatus .
common_data.integration_code Kolom LineItem.integrationDetails.integrationCode .
line_item_type Kolom LineItem.lineItemType .
insertion_order_id Kolom LineItem.insertionOrderId .
creative_ids Kolom LineItem.creativeIds .
max_cpm_advertiser_micros Kolom LineItem.bidStrategy.maximizeSpendAutoBid.maxAverageCpmBidAmountMicros atau LineItem.bidStrategy.performanceGoalAutoBid.maxAverageCpmBidAmountMicros , bergantung pada skema strategi yang digunakan.
performance_goal Kolom LineItem.bidStrategy.maximizeSpendAutoBid.performanceGoalType atau LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalType , bergantung pada skema strategi yang digunakan.
goal_advertiser_micros Kolom LineItem.bidStrategy.performanceGoalAutoBid.performanceGoalAmountMicros .
partner_revenue_model Kolom LineItem.partnerRevenueModel .
cost_tracking_pixels Kolom LineItem.conversionCounting.floodlightActivityConfigs .
budget.start_time_usec Kolom LineItem.flight.dateRange.startDate .
budget.end_time_usec Kolom LineItem.flight.dateRange.endDate .
budget.max_impressions Kolom LineItem.budget.maxAmount jika LineItem.budget.budgetUnit adalah BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros Kolom LineItem.budget.maxAmount jika LineItem.budget.budgetUnit adalah BUDGET_UNIT_CURRENCY .
budget.pacing_type Kolom LineItem.pacing.pacingPeriod .
budget.pacing_max_impressions Kolom LineItem.pacing.dailyMaxImpressions .
budget.pacing_max_spend_advertiser_micros Kolom LineItem.pacing.dailyMaxMicros .
budget.pacing_distribution Kolom LineItem.pacing.pacingType .
frequency_cap Kolom LineItem.frequencyCap .
partner_costs Kolom LineItem.partnerCosts .
target_list Dapat diambil melalui metode advertisers.lineItems.bulkListLineItemAssignedTargetingOptions .

NegativeKeywordList

Nama Kolom ERFKetersediaan API DV360
id Kolom NegativeKeywordList.negativeKeywordListId .
nama Kolom NegativeKeywordList.displayName .
advertiser_id Kolom NegativeKeywordList.advertiserId .

Partner

Nama Kolom ERFKetersediaan API DV360
common_data.id Kolom Partner.partnerId .
common_data.name Kolom Partner.displayName .
common_data.active Kolom Partner.entityStatus .
common_data.integration_code Tidak tersedia.
currency_code Kolom Partner.generalConfig.currencyCode .
exchange_settings Kolom Partner.exchangeConfig.enabledExchanges .
default_partner_costs Tidak tersedia.
default_partner_revenue Tidak tersedia.
default_target_list Tidak tersedia.

Pixel

Tidak ada resource atau kolom yang setara yang tersedia di Display & Video 360 API.

UniversalChannel

Nama Kolom ERFKetersediaan API DV360
id Kolom Channel.channelId .
nama Kolom Channel.displayName .
site_ids Dapat diambil melalui metode advertisers.channels.sites.list dan partners.channels.sites.list , bergantung pada jenis owner .
accessing_advertisers Tidak tersedia.
is_deleted Tidak tersedia.
is_brand_safe_channel Tidak tersedia.

UserList

Nama Kolom ERFKetersediaan API DV360
id Kolom FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId .
nama Kolom FirstAndThirdPartyAudience.displayName .
data_partner_id Tidak tersedia.
accessing_advertisers Tidak tersedia.
partner_pricing Tidak tersedia.
advertiser_pricings Tidak tersedia.