Entity Read Files (ERF) adalah representasi JSON dari objek kampanye partner yang, berdasarkan permintaan, dibuat setiap hari dan tersedia melalui Google Cloud Storage.
ERF tidak digunakan lagi pada Juni 2021. Mulai 31 Oktober 2024, ERF secara resmi akan dihentikan dan tidak dibuat lagi. Semua pengguna File Baca Entity yang sudah ada dianjurkan untuk bermigrasi ke Display & Video 360 API agar dapat terus mengambil resource Display & Video 360.
Panduan ini membahas cara bermigrasi dari Entity Read Files ke Display & Video 360 API dengan:
- Memberikan gambaran umum tentang perbedaan antara kedua antarmuka tersebut
- Membandingkan tabel ERF dengan layanan API
- Memberikan panduan terkait pengambilan entitas melalui API
- Mengakui kesenjangan data yang ada
- Menyajikan 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 dihasilkan setiap hari dan secara massal sementara API mengambil versi resource terbaru.
- Struktur resource. API ini menggunakan struktur JSON yang berbeda dengan ERF untuk merepresentasikan jenis resource yang sama. Beberapa resource, seperti setelan penargetan publik, mungkin menggunakan ruang ID yang berbeda.
- Metode pengambilan. Display & Video 360 API hanya memungkinkan pengambilan resource secara terpisah, dalam daftar yang diberi nomor halaman, atau melalui transfer data BigQuery, berbeda dengan file JSON mentah yang disediakan oleh ERF.
- Cakupan. Berbeda dengan ERF, yang dicakup oleh ID partner, sebagian besar resource API dibatasi menurut ID pengiklan. Resource yang disertakan dalam respons dibatasi pada resource dalam cakupan tersebut.
Representasi data ERF di API
File Baca Entity dipisahkan ke tabel "Publik" dan "Pribadi". Tabel publik memberikan informasi yang tersedia dan berlaku untuk semua pengguna, seperti nilai penargetan. Tabel pribadi menyediakan data yang khusus untuk partner, seperti materi iklan atau resource item baris.
Display & Video 360 API tidak menggunakan dikotomi ini, melainkan 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 yang tersedia melalui resource dan layanan Display & Video 360 API.
Informasi publik
Tabel publik ERF menyediakan materi referensi untuk digunakan pengguna saat menafsirkan setelan penargetan 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, 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 memberikan ID dan detail opsi penargetan
untuk jenis penargetan tertentu. Lihat halaman
Tetapkan Penargetan yang ada untuk contoh kode yang menunjukkan
pengambilan ID opsi penargetan.
Tabel publik dan SDF
Sebelum SDF v7, Entity Read Files dan Structured Data Files menggunakan ruang ID yang sama untuk setelan penargetan. Jika Anda 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 v7, 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 dari setelan resource pribadi saat ini yang dimiliki oleh partner. Karena besarnya volume resource yang dapat dibuat oleh satu partner, file ini dapat menjadi sangat besar serta sulit didownload dan diproses.
Di API, setiap tabel pribadi memiliki layanan terkait 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, karena menggunakan nama kolom dan resource bersama yang berbeda.
Informasi tertentu yang tersedia dalam representasi ERF resource, seperti setelan penargetan yang ditetapkan pada resource atau situs saluran, direpresentasikan dalam API sebagai turunan 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 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, pada partner mungkin memerlukan setiap permintaan daftar untuk setiap pengiklan turunan dari partner tersebut. Pengecualian mencakup turunan langsung dari partner, seperti pengiklan dan saluran milik partner.
- Penomoran halaman. Metode daftar API menggunakan penomoran halaman untuk menjamin bahwa respons memiliki ukuran yang wajar, sehingga membatasi sebagian besar respons permintaan individual, atau halaman, hingga 100 resource. Jika jumlah resource yang relevan lebih besar dari ukuran halaman, panggilan daftar berurutan diperlukan untuk mengambil halaman berikutnya dari respons daftar lengkap. Contoh kode yang memberi nomor 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
, permintaanadvertisers.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 dengan yang tersedia dalam satu File Operasi Pembacaan Entitas. Mengoptimalkan cara Anda mengambil resource dapat membantu mengambil data yang diperlukan dengan lebih efisien:
- Buat permintaan serentak ke API. Display & Video 360 API melindungi infrastruktur menggunakan permintaan per pengiklan per batas kapasitas project. Struktur kuota ini memungkinkan Anda menerapkan solusi multi-thread untuk beberapa pengiklan yang akan mengurangi total waktu yang diperlukan untuk mengambil semua resource yang diperlukan. Meskipun penomoran halaman mengharuskan semua resource suatu jenis dalam cakupan tertentu diambil melalui panggilan berturut-turut, pengambilan resource dalam cakupan lain atau dari jenis lain dapat dilakukan secara serentak.
- Gunakan filter dan urutkan berdasarkan parameter dalam panggilan daftar
untuk mengambil resource yang relevan saja. Misalnya, jika Anda hanya
tertarik dengan item baris yang telah diperbarui di hari terakhir, Anda dapat menggunakan
parameter
filter
dari metodeadvertisers.lineItems.list
untuk hanya menampilkan item baris denganupdateTime
yang lebih besar dari stempel waktu yang ditentukan. Hal ini dapat mengurangi jumlah permintaan yang perlu dibuat secara signifikan. - Cache ID 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 agar tidak perlu mengambil gambar setiap kali digunakan. Namun, nilai yang disimpan dalam cache harus diperiksa setiap minggu untuk memperhitungkan perubahan atau penghentian penggunaan yang jarang.
Lihat panduan Pengoptimalan Kuota kami untuk 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. Subset resource API didukung.
Lihat dokumentasi cloud berikut untuk informasi selengkapnya tentang penggunaan BigQuery Connector Display & Video 360 API:
- Apa itu BigQuery Data Transfer Service?
- Menjadwalkan transfer Display & Video 360
- Transformasi data Display & Video 360
Kesenjangan data API yang diketahui
Ada kesenjangan data penting yang mungkin Anda temui saat bermigrasi dari ERF ke Display & Video 360 API, seperti:
- Perjanjian pemasangan iklan cerita. Pesanan pemasangan iklan cerita tidak dapat diambil melalui API dan harus diambil melalui UI Display & Video 360.
- Subset kolom resource. Sejumlah kecil kolom resource yang ada dalam objek ERF tidak tersedia di resource terkait 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 tersebut tidak menjamin bahwa kolom tersebut menggunakan jenis data, nilai enum, atau ruang ID yang sama.
Koleksi Aplikasi
Dapat diambil di bagian jenis penargetan
TARGETING_TYPE_APP_CATEGORY
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
TargetingOption.targetingOptionId
.
|
name |
Kolom
TargetingOption.appCategoryDetails.displayName
.
|
Browser
Dapat diambil kembali di bagian jenis penargetan TARGETING_TYPE_BROWSER
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
TargetingOption.targetingOptionId
.
|
is_mobile | Tidak tersedia. |
name |
Kolom
TargetingOption.browserDetails.displayName
.
|
DataPartner
Tidak ada resource atau kolom setara yang tersedia di Display & Video 360 API.
DeviceCriteria
Dapat diambil di bagian jenis penargetan
TARGETING_TYPE_OPERATING_SYSTEM
,
TARGETING_TYPE_DEVICE_MAKE_MODEL
, dan
TARGETING_TYPE_DEVICE_TYPE
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
TargetingOption.targetingOptionId
atau enum
DeviceType
.
|
is_mobile | Tidak tersedia. |
name |
Kolom
TargetingOption.operatingSystemDetails.displayName
, kolom
TargetingOption.deviceMakeModelDetails.displayName
, atau enum
DeviceType
, 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
.
|
GeoLocation
Dapat diambil kembali di bagian jenis penargetan TARGETING_TYPE_GEO_REGION
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
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. |
IP
Dapat diambil kembali di bagian jenis penargetan TARGETING_TYPE_CARRIER_AND_ISP
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
TargetingOption.targetingOptionId
.
|
is_mobile | Tidak tersedia. |
name |
Kolom
TargetingOption.carrierAndIspDetails.displayName
.
|
secondary_criteria_id |
Kolom
TargetingOption.targetingOptionId
.
|
Bahasa
Dapat diambil kembali di bagian jenis penargetan TARGETING_TYPE_LANGUAGE
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
TargetingOption.targetingOptionId
.
|
name | Tidak tersedia. Nama tampilan lengkap untuk bahasa tersedia di kolom
TargetingOption.languageDetails.displayName
.
|
SiteToPlacementId
Tidak ada resource atau kolom setara yang tersedia di Display & Video 360 API.
SupportedExchange
Dapat diambil kembali di bagian jenis penargetan TARGETING_TYPE_EXCHANGE
.
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Exchange
.
|
name |
Exchange
.
|
UniversalSite
Tidak ada resource atau kolom setara yang tersedia di Display & Video 360 API. Masing-masing
situs dan aplikasi dapat ditargetkan langsung di bagian jenis penargetan
TARGETING_TYPE_URL
dan TARGETING_TYPE_APP
.
Di Display & Video 360, semua aplikasi atau URL dapat ditargetkan, tetapi tidak setiap 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 sudah ada di Display & Video 360 API. Meskipun nilai satu kolom dapat dipetakan ke kolom lain, hal tersebut tidak menjamin bahwa kolom tersebut menggunakan jenis data, nilai enum, atau ruang ID yang sama.
Pengiklan
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
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
di bagian jenis penargetan
TARGETING_TYPE_CHANNEL
. Jika
AssignedTargetingOption.channelDetails.negative
bernilai benar, saluran akan 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 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 DV360 API |
---|---|
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 ERF | Ketersediaan DV360 API |
---|---|
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 DV360 API |
---|---|
id |
Kolom
CustomList.customListId
.
|
name |
Kolom
CustomList.displayName
.
|
deskripsi | Tidak tersedia. |
advertiser_id | Tidak tersedia. |
FloodlightActivity
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
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
dalam partner tertentu.
|
partner_id | Disediakan 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 partner yang diberikan.
|
ssl_required |
Kolom
FloodlightActivity.sslRequired
.
|
InsertionOrder
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
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 ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
InventorySource.inventorySourceId
.
|
tidak terklasifikasi | 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 |
InventorySource.rateDetails.rate.nanos
, bergantung pada nilai kolom
InventorySource.rateDetails.inventorySourceRateType
.
|
min_cpm_currency_code |
Kolom
InventorySource.rateDetails.rate.currencyCode
.
|
LineItem
NegativeKeywordList
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
NegativeKeywordList.negativeKeywordListId
.
|
name |
Kolom
NegativeKeywordList.displayName
.
|
advertiser_id |
Kolom
NegativeKeywordList.advertiserId
.
|
Partner
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
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 setara yang tersedia di Display & Video 360 API.
UniversalChannel
Nama Kolom ERF | Ketersediaan DV360 API |
---|---|
id |
Kolom
Channel.channelId
.
|
name |
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 DV360 API |
---|---|
id |
Kolom
FirstAndThirdPartyAudience.firstAndThirdPartyAudienceId
.
|
name |
Kolom
FirstAndThirdPartyAudience.displayName
.
|
data_partner_id | Tidak tersedia. |
accessing_advertisers | Tidak tersedia. |
partner_pricing | Tidak tersedia. |
advertiser_pricings | Tidak tersedia. |