Bermigrasi dari Bid Manager API v1.1 ke v2

Pada Maret 2022, kami merilis Bid Manager API versi 2. Mengingat rilis versi baru ini, kami berencana untuk segera mengumumkan tanggal penghentian penggunaan v1.1. Sebaiknya Anda memulai migrasi dari v1.1 ke v2 sesegera mungkin.

Memigrasikan aplikasi Anda

Bermigrasi dari v1.1 ke v2 memerlukan pembaruan URL endpoint untuk memanggil v2, dan memperbarui aplikasi untuk memperhitungkan perubahan yang merusak.

Memperbarui panggilan API dari v1.1 ke v2

Untuk menggunakan v2, bukan v1.1, Anda harus mengupdate permintaan untuk menggunakan endpoint v2 baru.

Mengidentifikasi metode yang setara

Untuk memperbarui panggilan API dari penggunaan v1.1 ke v2, Anda harus mengidentifikasi metode v1.1 yang setara di v2 terlebih dahulu.

Nama semua layanan dan metode berikut telah sedikit berubah antara v1.1 dan v2:

• Layanan Queries dan Reports di v1.1 dikenal sebagai queries dan queries.reports di v2.
• Metode telah diganti namanya sebagai berikut di v2:

  Nama metode v1.1	Metode v2 yang setara
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

Perbarui ke endpoint baru

Setelah mengidentifikasi metode yang setara, Anda perlu memperbarui permintaan. Misalnya, untuk memanggil metode queries.getquery dengan v1.1, Anda akan menggunakan URL berikut:

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

Untuk memanggil metode yang setara di v2, yang dikenal sebagai queries.get, perbarui URL ke yang berikut:

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

Jika Anda menggunakan library klien untuk membuat permintaan ke API, gunakan library klien versi terbaru dan perbarui konfigurasi Anda untuk menggunakan v2.

Membuat perubahan yang diperlukan

Kami memperkenalkan sejumlah perubahan yang dapat menyebabkan gangguan di v2. Tinjau petunjuk berikut dan lakukan perubahan yang diperlukan yang relevan dengan penggunaan Bid Manager API yang ada.

Memperbarui panggilan ke layanan queries

• Kolom berikut dalam resource Query yang awalnya diwakili oleh objek bertingkat umum telah berubah untuk menggunakan jenis objek berikut:

  Kolom v1.1	Jenis objek v2 yang setara
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Dihapus
  params.options.pathQueryOptions.channelGrouping	Dihapus
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Dihapus
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Dihapus
  schedule	QuerySchedule

• Kolom berikut dalam resource Query yang awalnya diwakili oleh objek daftar umum telah diubah menjadi daftar jenis objek baru berikut:

  Kolom daftar v1.1	Jenis objek v2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Dihapus
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Dihapus
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Dihapus
  params.options.pathQueryOptions.pathFilters[]	Dihapus
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Dihapus

• Kolom berikut dalam resource Query, yang awalnya direpresentasikan oleh string,direpresentasikan oleh jenis enum di v2, dan mencakup perubahan berikut:
  • metadata.dataRange yang setara dengan v2 kini menggunakan enum Range. Saat dikonversi ke enum ini, nilai PREVIOUS_HALF_MONTH telah dihapus dan nilai TYPE_NOT_SUPPORTED diubah menjadi RANGE_UNSPECIFIED.
  • metadata.format kini menggunakan enum Format. Dalam mengonversi ke enum ini, nilai EXCEL_CSV telah dihapus dan nilai FORMAT_UNSPECIFIED telah ditambahkan.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match dan params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match sekarang menggunakan enum Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition sekarang menggunakan enum PathMatchPosition. Dalam mengonversi ke enum ini, nilai PATH_MATCH_POSITION_UNSPECIFIED telah ditambahkan.
  • schedule.frequency kini menggunakan enum Frequency. Saat mengonversi ke enum ini, nilai FREQUENCY_UNSPECIFIED telah ditambahkan.
  • params.type kini menggunakan enum ReportType. Saat mengonversi ke enum ini, perubahan berikut telah dilakukan:
  • Nilai berikut tidak digunakan lagi:
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • Nilai yang tersisa telah diperbarui untuk lebih mencerminkan nilai setara di UI:

    Nilai v1.1	Nilai ReportType yang setara
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• Kolom metadata.dataRange, reportDataStartTimeMs, dan reportDataEndTimeMs telah diganti dengan kolom range, customStartDate, dan customEndDate. Kolom tanggal baru menggunakan objek Date dan bukan milidetik sejak Epoch Unix. Kolom pengganti ini telah dipindahkan ke objek DataRange yang ditetapkan ke kolom dataRange dalam objek QueryMetadata.
• Kolom schedule.startTimeMs dan schedule.endTimeMs telah diganti dengan kolom startDate dan endDate dalam objek QuerySchedule. Kolom tanggal baru menggunakan objek Date dan bukan milidetik sejak Epoch Unix.
• Kolom metadata.running, metadata.reportCount, metadata.googleCloudStoragePathForLatestReport, metadata.googleDrivePathForLatestReport, dan metadata.latestReportRunTimeMs telah dihapus. Informasi mengenai laporan terbaru yang dihasilkan dari kueri harus diambil menggunakan metode queries.reports.list dengan parameter kueri orderBy “key.reportId desc” untuk memastikan bahwa permintaan mencantumkan laporan terbaru terlebih dahulu.
• Kolom kind, timezoneCode, metadata.locale, params.includeInviteData, dan schedule.nextRunMinuteOfDay telah dihapus.
• queries.create tidak lagi otomatis menjalankan kueri setelah pembuatan dan parameter kueri asynchronous telah dihapus. Panggil queries.run setelah queries.create untuk membuat laporan untuk kueri baru.
• Metode queries.run telah diperbarui dengan cara berikut:
  • Parameter kueri asynchronous telah diganti dengan parameter kueri synchronous. Parameter kueri baru beroperasi dengan logika terbalik dan dianggap salah jika tidak ditentukan. Mengingat hal ini, queries.run menghasilkan laporan secara asinkron secara default di v2, bukan secara sinkron, yang merupakan default di v1.1.
  • Isi permintaan telah diperbarui untuk menghapus kolom timezoneCode dan mengganti kolom dataRange, reportDataStartTimeMs, reportDataEndTimeMs dengan objek DataRange yang ditetapkan ke kolom dataRange.
  • Metode ini menampilkan objek Report yang dihasilkan, bukan isi respons kosong.
• Kolom kind di isi respons queries.list telah dihapus.

Memperbarui panggilan ke layanan reports

• Kolom berikut dalam resource Report yang awalnya diwakili oleh objek bertingkat umum telah berubah untuk menggunakan jenis objek berikut:

  Kolom v1.1	Jenis objek v2 yang setara
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	Dihapus
  params.options.pathQueryOptions.channelGrouping	Dihapus
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	Dihapus
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	Dihapus

• Kolom berikut dalam resource Report yang awalnya diwakili oleh objek daftar umum telah diubah menjadi daftar jenis objek baru berikut:

  Kolom daftar v1.1	Jenis objek v2
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	Dihapus
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	Dihapus
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	Dihapus
  params.options.pathQueryOptions.pathFilters[]	Dihapus
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	Dihapus

• Kolom berikut dalam resource Report yang awalnya direpresentasikan oleh string telah berubah sehingga kolom yang setara di v2 direpresentasikan oleh jenis enum baru dan mencakup perubahan pada nilai yang dapat diterima:
  • metadata.status.format kini menggunakan enum Format. Saat mengonversi ke enum ini, nilai EXCEL_CSV telah dihapus dan FORMAT_UNSPECIFIED telah ditambahkan.
  • metadata.status.state kini menggunakan enum State. Saat mengonversi ke enum ini, nilai QUEUED dan STATE_UNSPECIFIED telah ditambahkan.
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match dan params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match sekarang menggunakan enum Match.
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition sekarang menggunakan enum PathMatchPosition. Dalam mengonversi ke enum ini, nilai PATH_MATCH_POSITION_UNSPECIFIED telah ditambahkan.
  • params.type kini menggunakan enum ReportType. Dalam mengonversi ke enum ini, banyak perubahan telah dilakukan dan tercantum secara mendetail di bagian sebelumnya terkait panggilan layanan kueri yang diperbarui.
• Kolom metadata.reportDataStartTimeMs dan metadata.reportDataEndTimeMs telah diganti dengan kolom reportDataStartDate dan reportDataEndDate dalam objek ReportMetadata. Kolom baru menggunakan objek Date, bukan milidetik sejak Epoch Unix.
• metadata.status.finishTimeMs telah diganti dengan kolom finishTime dalam objek ReportStatus. Kolom waktu baru ini merepresentasikan tanggal dan waktu sebagai stempel waktu dalam format RFC3339 UTC "Zulu", bukan dalam milidetik sejak Epoch Unix.
• Kolom metadata.status.failure dan params.includeInviteData telah dihapus.
• Kolom kind di isi respons reports.list telah dihapus.

Memperbarui logika penanganan error

Pesan error di seluruh API telah diperbarui di v2. Pesan error baru ini lebih spesifik dan, dalam beberapa kasus, memberikan informasi tentang nilai dalam permintaan API yang menyebabkan error ditampilkan. Jika logika penanganan error yang ada mengandalkan teks pesan error tertentu, generalisasikan penanganan error Anda sebelum bermigrasi ke v2.