Bermigrasi dari File Baca Entity

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, 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 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 metode advertisers.lineItems.list untuk hanya menampilkan item baris dengan updateTime 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:

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 ERFKetersediaan DV360 API
id Kolom TargetingOption.targetingOptionId .
name Kolom TargetingOption.appCategoryDetails.displayName .

Browser

Dapat diambil kembali di bagian jenis penargetan TARGETING_TYPE_BROWSER.

Nama Kolom ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan DV360 API
id Kolom CustomList.customListId .
name Kolom CustomList.displayName .
deskripsi Tidak tersedia.
advertiser_id Tidak tersedia.

FloodlightActivity

Nama Kolom ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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

Nama Kolom ERFKetersediaan DV360 API
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 DV360 API
id Kolom NegativeKeywordList.negativeKeywordListId .
name Kolom NegativeKeywordList.displayName .
advertiser_id Kolom NegativeKeywordList.advertiserId .

Partner

Nama Kolom ERFKetersediaan 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 ERFKetersediaan 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 ERFKetersediaan 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.