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 entity 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 ini 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 secara terpisah, dalam daftar yang di-pagination, atau melalui transfer data BigQuery, berbeda dengan file JSON mentah yang disediakan oleh ERF.
• Cakupan. Tidak seperti ERF, yang cakupannya ditentukan oleh ID partner, sebagian besar resource API ditentukan cakupannya oleh ID pengiklan. Resource yang disertakan dalam respons terbatas pada resource dalam cakupan tersebut.

Representasi data ERF di API

File Baca Entri dipisahkan menjadi tabel "Publik" dan "Pribadi". Tabel publik memberikan 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 yang lebih deskriptif, 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 mengetahui 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.

Resource 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 mencakup:

• 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 partner, seperti pengiklan dan channel milik partner.
• Penomoran halaman. Metode daftar API menggunakan penomoran halaman untuk memastikan 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 project dan 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 memerlukan semua resource dari 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 pada item baris yang telah diperbarui dalam sehari terakhir, Anda dapat menggunakan parameter filter dari metode advertisers.lineItems.list untuk hanya menampilkan item baris dengan updateTime yang lebih besar dari stempel waktu tertentu. Hal ini dapat mengurangi jumlah permintaan yang perlu dibuat secara signifikan.
• Simpan ID yang digunakan secara rutin dalam cache 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.

Mengimpor 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:

• Apa yang dimaksud dengan BigQuery Data Transfer Service?
• Menjadwalkan transfer Display & Video 360
• Transformasi data Display & Video 360

Kesenjangan data API yang diketahui

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

• Perjanjian 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 ERF	Ketersediaan API DV360
id	Kolom TargetingOption.targetingOptionId .
nama	Kolom TargetingOption.appCategoryDetails.displayName .

Browser

Dapat diambil berdasarkan jenis penargetan TARGETING_TYPE_BROWSER.

Nama Kolom ERF	Ketersediaan 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 ERF	Ketersediaan 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 ERF	Ketersediaan 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 ERF	Ketersediaan 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 ERF	Ketersediaan 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 ERF	Ketersediaan API DV360
id	Exchange enum.
nama	Exchange enum.

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 ERF	Ketersediaan 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 memiliki konfigurasi Floodlight CM360 yang sama.
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 ERF	Ketersediaan 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	Tidak tersedia
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 ERF	Ketersediaan 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 ERF	Ketersediaan API DV360
id	Kolom CustomList.customListId .
nama	Kolom CustomList.displayName .
deskripsi	Tidak tersedia.
advertiser_id	Tidak tersedia.

FloodlightActivity

Nama Kolom ERF	Ketersediaan 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 ERF	Ketersediaan 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	Tidak tersedia.

InventorySource

Nama Kolom ERF	Ketersediaan 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 ERF	Ketersediaan 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	LineItem.budget.maxAmount jika LineItem.budget.budgetUnit adalah BUDGET_UNIT_IMPRESSIONS .
budget.max_spend_advertiser_micros	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.bulkListAssignedTargetingOptions .

NegativeKeywordList

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

Partner

Nama Kolom ERF	Ketersediaan 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 ERF	Ketersediaan 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 ERF	Ketersediaan API DV360
id	Kolom FirstPartyAndPartnerAudience.firstPartyAndPartnerAudienceId .
nama	Kolom FirstPartyAndPartnerAudience.displayName .
data_partner_id	Tidak tersedia.
accessing_advertisers	Tidak tersedia.
partner_pricing	Tidak tersedia.
advertiser_pricings	Tidak tersedia.