Panduan ini mencakup referensi pemecahan masalah RTB, yang memungkinkan Anda mengakses secara terprogram
metrik kampanye bidding real-time yang juga ditampilkan melalui
alat Perincian RTB yang dapat ditemukan di
UI Authorized Buyers. Ini termasuk bidders.filterSets
, bidders.accounts.filterSets
, dan semua resource di bawahnya secara hierarkis.
Dengan metrik dari referensi pemecahan masalah RTB, Anda dapat memperoleh insight tentang peluang yang terlewatkan untuk memenangkan tayangan yang dapat membantu Anda mengoptimalkan kampanye bidding real-time.
Penyesuaian pada struktur dan gaya API
Referensi pemecahan masalah RTB memperkenalkan beberapa perubahan untuk secara eksplisit menunjukkan kepemilikan dan akses, memberikan kontrol yang lebih terperinci atas data yang ditampilkan oleh API, dan lebih selaras dengan praktik desain Google API.
Resource tingkat bidder dan tingkat akun
Materi disusun menurut bidders
dan bidders.accounts
. Hal ini memungkinkan Anda menentukan
apakah panggilan API menargetkan bidder (juga dikenal sebagai akun induk) dan semua akun
turunan terkait, atau akun Authorized Buyers individual. Dalam konteks Pemecahan Masalah RTB, resource yang terstruktur di bagian bidders.filterSets
akan menampilkan metrik gabungan untuk bidder yang ditentukan dan semua akun turunan yang terkait. Sebaliknya, pengguna yang berada di bawah
bidders.accounts.filterSets
hanya akan menampilkan metrik untuk akun yang ditentukan, terlepas dari
apakah akun tersebut merupakan bidder atau akun turunan.
Catatan: Akun yang mendelegasikan bidding mereka ke pembeli lain bukan akun bidder, dan
akibatnya tidak dapat mengakses resource tingkat bidder. Selain itu, akun non-bidder tidak dapat
mengakses resource impressionMetrics
, filteredBidResponses
, bidResponseErrors
, dan
bidResponsesWithoutBids
tingkat akun.
Memperkenalkan nama resource sebagai ID unik
Nama resource digunakan sebagai ID unik, bukan ID bilangan bulat atau string. Saat membuat instance baru dari jenis resource tertentu, kini Anda harus menetapkan nama resource relatif menggunakan jalur URI resource yang diikuti dengan ID resource yang dipilih. Berikut adalah contoh nama yang relevan untuk referensi Pemecahan Masalah RTB:
Resource | Contoh nama |
---|---|
bidders.filterSets | bidders/12345678/filterSets/fset_1 |
bidders.accounts.filterSets | bidders/12345678/accounts/87654321/filterSets/fset_2 |
Catatan: ID resource yang ditentukan untuk bidders
dalam nama harus berupa ID akun
Authorized Buyers milik bidder. Untuk accounts
, ID resource harus berupa ID akun bidder atau akun turunan yang dikelola oleh bidder tersebut. Jika tidak mengetahui akun Authorized Buyers
yang terkait dengan Akun Google Anda, Anda dapat menggunakan metode
accounts.list untuk menemukannya.
Kumpulan filter
Kumpulan filter adalah representasi opsi pemfilteran yang tersedia, dan dapat dibuat di tingkat bidder atau akun. Parameter ini digunakan untuk memfilter hasil daftar resource Pemecahan Masalah RTB yang mengambil metrik untuk kampanye bidding real-time Anda.
Filter yang diterapkan saat mengambil metrik adalah titik potong dari setiap filter dalam kumpulan filter yang ditentukan. Filter daftar, seperti platforms
, ditafsirkan sebagai gabungan setiap item dalam daftar.
Kumpulan filter bidder dan tingkat akun berbeda dan hanya dapat diakses dari tingkat pembuatannya—terlepas dari akun yang digunakan untuk membuatnya. Kumpulan filter berbagi akun bidder dan akun turunan yang dibuat di tingkat akun, sedangkan hanya bidder yang dapat mengakses resource di tingkat bidder. Tabel berikut merangkum cara akun turunan dan bidder dapat mengakses resource di kedua tingkat:
bidders.filterSets | bidders.accounts.filterSets | |
---|---|---|
Akun Bidder | Panggilan API hanya memengaruhi kumpulan filter tingkat bidder. | Panggilan API hanya memengaruhi kumpulan filter tingkat akun. |
Akun Anak | Panggilan API ini akan menampilkan respons error. | Panggilan API hanya memengaruhi kumpulan filter tingkat akun. |
Buat kumpulan filter
Saat membuat kumpulan filter, Anda harus menentukan rentang waktu sebagai relativeDateRange
,
absoluteDateRange
, atau realtimeTimeRange
. Saat mengambil metrik, perilaku default-nya adalah semua data akan disediakan selama rentang waktu tersebut. Jika ingin menerima perincian deret waktu selama rentang waktu tertentu, Anda dapat menentukan timeSeriesGranularity
untuk menunjukkan interval HOURLY
atau DAILY
.
Jika hanya memerlukan filter yang ditetapkan untuk jangka waktu yang singkat, Anda dapat menetapkan parameter kueri isTransient
ke true
. Hal ini akan menunjukkan bahwa kumpulan filter bersifat sementara, yang berarti kumpulan filter tidak akan dipertahankan tanpa batas waktu. Kumpulan filter sementara akan tersedia setidaknya selama satu jam setelah pembuatannya, tetapi pada akhirnya akan dihapus. Secara default, kumpulan filter tidak bersifat sementara.
Contoh tingkat bidder
Untuk membuat kumpulan filter tingkat bidder baru, kirim permintaan POST
ke URI resource bidders.filterSets
, yang memiliki format berikut:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets
Peringatan: Kumpulan filter tingkat bidder tidak dapat memfilter menurut ID materi iklan atau transaksi. Jika menentukan filter ini saat membuat kumpulan filter tingkat bidder, Anda akan menerima respons error.
PermintaanBerikut adalah contoh permintaan POST
yang membuat kumpulan filter tingkat bidder non-sementara yang baru:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }Respons
Jika permintaan berhasil, server akan merespons dengan kode status 200 OK. Isi respons akan menyertakan resource kumpulan filter yang dibuat, yang akan sama dengan kumpulan filter yang dikirimkan dalam permintaan.
Contoh tingkat akun
Untuk membuat kumpulan filter tingkat akun baru, kirim permintaan POST
ke URI resource bidders.accounts.filterSets
, yang memiliki format berikut:
https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets
Catatan: ID resource yang ditentukan untuk accounts
dapat
berupa ID akun milik setiap akun Authorized Buyers yang dapat diakses oleh akun bidder
yang ditentukan di URI, termasuk akun bidder itu sendiri.
Berikut adalah contoh permintaan POST
yang membuat kumpulan filter tingkat akun non-sementara yang baru:
POST https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets Authorization: Bearer access token here Content-Type: application/json { "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }Respons
Jika permintaan berhasil, server akan merespons dengan kode status 200 OK. Isi respons akan menyertakan resource kumpulan filter yang dibuat, yang akan sama dengan kumpulan filter yang dikirimkan dalam permintaan.
Dapatkan kumpulan filter
Metode get hanya bisa mendapatkan kumpulan filter pada tingkat yang sama dengan saat dibuat. Misalnya, akun bidder
harus menggunakan bidders.accounts.filterSets.get
untuk mengambil kumpulan filter yang dibuat di tingkat
akun, bukan metode bidders.filterSets.get
.
Tingkat bidder
Anda dapat mengambil filter tingkat bidder dengan mengirimkan permintaan HTTP GET ke URI resource bidders.filterSets
, yang memiliki format berikut:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Permintaan
Berikut contohnya:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fsRespons
Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK
dan kumpulan filter yang diambil:
{ "name": "bidders/12345678/filterSets/bidder-fs", "format": "DISPLAY", "environment": "APP", "platforms": ["TABLET", "MOBILE"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
Tingkat akun
Anda dapat mengambil kumpulan filter tingkat akun dengan mengirimkan permintaan HTTP GET
ke URI resource bidders.accounts.filterSets
, yang memiliki format berikut:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Permintaan
Berikut contohnya:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fsRespons
Jika permintaan berhasil, server akan merespons dengan kode status HTTP 200 OK
dan kumpulan filter yang diambil:
{ "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "format": "VIDEO", "environment": "WEB", "platforms": ["DESKTOP"], "absoluteDateRange": { "startDate": { "month": 11, "day": 26, "year": 2017 }, "endDate": { "month": 12, "day": 3, "year": 2017 } }, "timeSeriesGranularity": "DAILY" }
Mencantumkan kumpulan filter
Metode daftar hanya akan menampilkan kumpulan filter yang dapat diakses dari tingkat yang dipanggil.
Misalnya, akun bidder tidak akan melihat kumpulan filter yang dibuat untuk dirinya sendiri melalui
bidders.accounts.filterSets.create
saat memanggil bidders.filterSets.list
.
Tingkat bidder
Anda dapat mengambil semua kumpulan filter tingkat bidder untuk bidder tertentu dengan mengirimkan permintaan HTTP GET
ke URI resource bidders.filtersets
, yang memiliki format berikut:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSetsPermintaan
Berikut adalah contoh yang mencantumkan semua kumpulan filter tingkat bidder untuk bidder dengan ID akun 12345678:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSetsRespons
{ "filterSets": [{ "filterSetId": "99994", "name": "bidders/12345678/filterSets/test-b-1", "relativeDateRange": { "durationDays": 30 } }, { "realtimeTimeRange": { "startTimeStamp": "2017-11-15T12:30:30.072831583Z" }, "filterSetId": "99995", "name": "bidders/12345678/filterSets/test-b-2", "timeSeriesGranularity": "HOURLY" }, { "absoluteDateRange": { "endDate": { "day": 12, "month": 3, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99996", "name": "bidders/12345678/filterSets/bidder-fs", "timeSeriesGranularity": "DAILY", "platforms": ["TABLET", "MOBILE"], "environment": "APP", "format": "DISPLAY" } ] }
Tingkat akun
Anda dapat mengambil semua kumpulan filter tingkat akun untuk akun tertentu dengan mengirimkan permintaan HTTP GET
ke URI resource bidders.accounts.filtersets
, yang memiliki format berikut:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSetsPermintaan
Berikut adalah contoh yang mencantumkan semua kumpulan filter tingkat akun untuk akun turunan dengan ID akun 87654321:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSetsJawaban
{ "filterSets": [{ "realtimeTimeRange": { "startTimeStamp": "2017-11-19T04:24:43.252893487Z" }, "filterSetId": "99997", "name": "bidders/12345678/accounts/87654321/filterSets/test-a-1", "timeSeriesGranularity": "DAILY" }, { "absoluteDateRange": { "endDate": { "day": 3, "month": 12, "year": 2017 }, "startDate": { "day": 26, "month": 11, "year": 2017 } }, "filterSetId": "99998", "name": "bidders/12345678/accounts/87654321/filterSets/account-fs", "timeSeriesGranularity": "DAILY", "platforms": ["DESKTOP"], "environment": "WEB", "format": "VIDEO" } ] }
Menghapus kumpulan filter
Anda dapat menggunakan metode delete
untuk menghapus kumpulan filter non-sementara yang tidak
diperlukan lagi. Filter hanya dapat menghapus kumpulan filter yang dapat diakses dari tingkat pemanggilannya;
misalnya, akun bidder tidak dapat menghapus kumpulan filter yang dibuat dengan bidders.accounts.filterSets.create
dengan bidders.filterSets.delete
.
Tingkat bidder
Anda dapat menghapus kumpulan filter tingkat bidder untuk akun tertentu dengan mengirimkan permintaan HTTP DELETE
ke URI resource bidders.filtersets
, yang memiliki format berikut:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}Permintaan
Berikut adalah contoh penghapusan kumpulan filter tingkat bidder:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/test-b-2Respons
Jika berhasil, isi permintaan akan kosong. Kumpulan filter yang ditentukan tidak akan dapat diakses lagi.
Tingkat akun
Anda dapat menghapus kumpulan filter tingkat akun untuk akun tertentu dengan mengirimkan permintaan HTTP DELETE
ke URI resource bidders.accounts.filtersets
, yang memiliki format berikut:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}Permintaan
Berikut adalah contoh penghapusan kumpulan filter tingkat akun:
DELETE https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/test-a-1Respons
Jika berhasil, isi permintaan akan kosong. Kumpulan filter yang ditentukan tidak akan dapat diakses lagi.
Mengambil metrik pemecahan masalah RTB
Semua resource pemecahan masalah RTB yang digunakan untuk menerima metrik beroperasi dengan cara yang serupa, yaitu memiliki satu metode guna mencantumkan metrik untuk kumpulan filter yang ditentukan melalui parameter jalur filterSetName
. Kumpulan filter yang ditentukan akan menentukan filter dan setelan yang akan diterapkan saat membuat kueri metrik. Memanggil resource ini dari tingkat bidder akan menampilkan metrik gabungan dari akun bidder dan semua akun turunan yang terkait, sedangkan panggilan dari tingkat akun hanya akan menampilkan metrik untuk akun perorangan.
Metrik Bid
Resource bidMetrics
digunakan untuk mengambil metrik yang diukur dalam
jumlah bid. Misalnya, Anda dapat menggunakannya untuk menentukan jumlah total bid selama
rentang waktu tertentu, dan jumlah bid yang tidak difilter dari lelang, memenangkan tayangan,
dll. Seperti semua resource pemecahan masalah RTB lainnya yang digunakan untuk mengumpulkan metrik, resource ini hanya memiliki metode list
.
Mencantumkan metrik bid tingkat bidder
Anda dapat mencantumkan metrik bid tingkat bidder untuk filter tertentu yang ditetapkan dengan mengirimkan permintaan HTTP GET
ke URI resource bidders.filtersets.bidMetrics
, yang memiliki format berikut:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/filterSets/{filter set resource ID}/bidMetricsPermintaan
Berikut contoh yang mencantumkan metrik bid tingkat bidder:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/filterSets/bidder-fs/bidMetricsRespons
Jika permintaan berhasil, server akan merespons dengan kode status 200 OK
dan isi yang berisi baris metrik untuk dimensi dan perincian yang ditentukan.
{ "bidMetricsRows": [{ "bids": { "value": "6160" }, "bidsInAuction": { "value": "5698" }, "billedImpressions": { "value": "1196" }, "impressionsWon": { "value": "2920" }, "measurableImpressions": { "value": "1160" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-29T08:00:00Z", "startTime": "2017-11-28T08:00:00Z" } }, "viewableImpressions": { "value": "683" } }, { "bids": { "value": "104288" }, "bidsInAuction": { "value": "94016" }, "billedImpressions": { "value": "99" }, "impressionsWon": { "value": "125" }, "measurableImpressions": { "value": "94" }, "rowDimensions": { "timeInterval": { "endTime": "2017-11-30T08:00:00Z", "startTime": "2017-11-29T08:00:00Z" } }, "viewableImpressions": { "value": "87" } }, { "bids": { "value": "3999" }, "bidsInAuction": { "value": "3631" }, "billedImpressions": { "value": "618" }, "impressionsWon": { "value": "1819" }, "measurableImpressions": { "value": "604" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "369" } }, { "bids": { "value": "15" }, "bidsInAuction": { "value": "3" }, "billedImpressions": {}, "impressionsWon": { "value": "3" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
Catatan: Setiap kolom yang ditetapkan ke 0 untuk metrik tertentu tidak akan muncul dalam respons.
Metrik billedImpressions
dan measurableImpressions
yang kosong di atas
menunjukkan bahwa nilai dan varians untuk keduanya ditetapkan ke 0.
Peringatan: Untuk perincian data dalam respons, respons tidak akan menyertakan baris jika tidak berisi setidaknya satu metrik bukan nol. Misalnya, saat timeSeriesGranularity
ditentukan, respons tidak akan menyertakan baris untuk timeInterval
apa pun selama rentang waktu yang ditentukan oleh kumpulan filter saat semua metriknya bernilai nol.
Mencantumkan metrik bid tingkat akun
Anda dapat mencantumkan metrik bid tingkat akun untuk filter tertentu yang ditetapkan dengan mengirimkan permintaan HTTP GET
ke URI resource bidders.accounts.filtersets.bidMetrics
, yang memiliki
format berikut:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/{bidder resource ID}/accounts/{account resource ID}/filterSets/{filter set resource ID}/bidMetricsPermintaan
Berikut adalah contoh yang mencantumkan metrik bid tingkat akun:
GET https://adexchangebuyer.googleapis.com/v2beta1/bidders/12345678/accounts/87654321/filterSets/account-fs/bidMetricsRespons
Jika permintaan berhasil, server akan merespons dengan kode status 200 OK
dan isi yang berisi baris metrik untuk dimensi dan perincian yang ditentukan.
{ "bidMetricsRows": [{ "bids": { "value": "1748" }, "bidsInAuction": { "value": "1421" }, "billedImpressions": { "value": "301" }, "impressionsWon": { "value": "915" }, "measurableImpressions": { "value": "298" }, "rowDimensions": { "timeInterval": { "endTime": "2017-12-01T08:00:00Z", "startTime": "2017-11-30T08:00:00Z" } }, "viewableImpressions": { "value": "172" } }, { "bids": { "value": "6" }, "bidsInAuction": { "value": "2" }, "billedImpressions": {}, "impressionsWon": { "value": "1" }, "measurableImpressions": {}, "rowDimensions": { "timeInterval": { "endTime": "2017-12-02T08:00:00Z", "startTime": "2017-12-01T08:00:00Z" } }, "viewableImpressions": {} } ] }
Catatan: Setiap kolom yang ditetapkan ke 0 untuk metrik tertentu tidak akan muncul dalam respons. Metrik
billedImpressions
dan measurableImpressions
yang kosong di atas menunjukkan
bahwa nilai dan varian untuk keduanya ditetapkan ke 0.
Peringatan: Untuk perincian data dalam respons, respons tidak akan menyertakan baris jika tidak berisi setidaknya satu metrik bukan nol. Misalnya, saat timeSeriesGranularity
ditentukan, respons tidak akan menyertakan baris untuk timeInterval
apa pun selama rentang waktu yang ditentukan oleh kumpulan filter saat semua metriknya bernilai nol.