Bermigrasi dari v1beta ke v1

Panduan ini membantu Anda bermigrasi dari Merchant API v1beta ke v1, versi pertama untuk Ketersediaan Umum. Versi v1 memperkenalkan beberapa update dan beberapa perubahan yang mungkin memerlukan update kode. Perubahan ini dirancang untuk menyederhanakan API dan meningkatkan pengelolaan akun Merchant Center Anda.

Perbedaan utama

Berikut adalah perubahan terpenting yang perlu Anda ketahui saat bermigrasi dari v1beta ke v1:

  • Pendaftaran satu kali setidaknya satu developer API untuk menggunakan Merchant API: Anda harus memanggil metode registerGcp (hanya sekali untuk setiap project Google Cloud yang digunakan untuk autentikasi) untuk memberikan detail kontak Anda, yang memungkinkan Anda menggunakan API dan menerima update serta pengumuman terkait Merchant API. Anda tidak akan dapat menggunakan API v1 atau v1alpha hingga langkah ini selesai. Untuk mengetahui informasi selengkapnya tentang proses pendaftaran, lihat Pendaftaran.

  • Encoding nama produk: Kolom ProductInput.name dan Product.name mendukung encoding base64url tanpa padding (RFC 4648 Bagian 5). Ikuti panduan berikut:

    • Sebelum encoding, string harus mematuhi format contentLanguage~feedLabel~offerId.

    • Encoding wajib jika nama produk Anda berisi karakter yang digunakan oleh Merchant API atau karakter yang dicadangkan URL seperti:

      % . + / : ~ , ( * ! ) & ? = @ # $

    • Jika nama produk Anda mematuhi contentLanguage~feedLabel~offerId format dan tidak berisi karakter yang digunakan oleh Merchant API atau karakter yang dicadangkan URL, Anda dapat menggunakan format biasa, tanpa encoding.

    • Untuk memastikan penguraian yang konsisten dan benar, sebaiknya gunakan encoding base64url tanpa padding untuk semua nama produk.

  • Penghapusan informasi pajak tingkat produk: taxes dan taxCategory.

  • Product.attributes diganti namanya: Kolom Product.attributes telah diganti namanya menjadi Product.productAttributes.

  • Penghapusan informasi pajak tingkat produk: Kolom taxes dan taxCategory telah dihapus dari Product.productAttributes objek. Lihat artikel Bantuan Google Merchant Center tentang pajak untuk mengetahui informasi selengkapnya.

  • Perubahan pada kolom GTIN: Kolom gtin dalam objek Product.productAttributes telah diganti namanya menjadi gtins agar lebih mencerminkan bahwa kolom tersebut dapat menyimpan beberapa nilai. Kolom gtin dalam objek OrderTrackingSignals.lineItemDetails kini berupa array dan juga telah diganti namanya menjadi gtins.

  • Penghapusan kolom saluran: Kolom channel telah dihapus dari produk, input produk, dan sumber data. Kolom boolean baru, legacyLocal, telah diperkenalkan untuk menetapkan produk yang dijual secara eksklusif di toko fisik dengan jelas. Catatan: Kolom legacyLocal adalah kolom tambahan untuk membantu migrasi dan pada akhirnya akan dihentikan setelah metode pemasaran Online dan Lokal dapat ditargetkan sepenuhnya dengan satu sumber produk. Lihat tabel di bagian berikut untuk mengetahui informasi selengkapnya.

  • Kolom baru untuk atribut inventaris regional dan lokal:

    • Semua RegionalInventory kolom kecuali name, account dan region kini digabungkan dalam objek baru yang disebut regionalInventoryAttributes . Misalnya, atribut RegionalInventory.price kini berada di bagian RegionalInventory.regionalInventoryAttributes.price.
    • Semua LocalInventory kolom kecuali name, account dan storeCode kini digabungkan dalam objek baru yang disebut localInventoryAttributes . Misalnya, atribut LocalInventory.price kini berada di bagian LocalInventory.localInventoryAttributes.price.

  • Penghapusan customAttributes dari inventaris regional dan lokal: Kolom customAttributes telah dihapus dari resource RegionalInventory dan LocalInventory.

  • Pembuatan akun yang disempurnakan: Kolom users yang redundan telah dihapus dari CreateAndConfigureAccountRequest. Gunakan kolom user tunggal untuk mengaitkan pengguna awal dengan akun baru.

  • Jenis atribut tertentu diubah dari string menjadi enum: Beberapa kolom dalam Product dan Inventory resource dengan daftar nilai singkat yang ditentukan diubah dari jenis string menjadi jenis enum untuk validasi data yang lebih baik (misalnya, kolom Product.ProductAttributes.condition kini berupa enum).

  • Penghapusan metode update kebijakan pengembalian online: Metode onlineReturnPolicy.update dihapus di v1. Buat kebijakan pengembalian online menggunakan onlineReturnPolicy.create metode sebagai gantinya.

Cara melakukan migrasi

Versi v1beta Merchant API dijadwalkan untuk dihentikan pada 28 Februari 2026. Untuk mengetahui informasi selengkapnya tentang jadwal penghentian, lihat panduan pembuatan versi Merchant API.

  • Langkah pertama dalam migrasi adalah melakukan pendaftaran developer satu kali (Lihat Mendaftar sebagai developer. Anda harus memanggil metode registerGcp untuk setiap project Google Cloud yang Anda gunakan untuk autentikasi sebelum metode v1 dapat berfungsi.

  • Terlepas dari cara Anda memanggil API (dengan REST, gRPC, atau menggunakan library klien), Anda dapat bermigrasi secara bertahap. Artinya, Anda dapat mengupdate dan memigrasikan kode satu API dalam satu waktu (misalnya, memindahkan Products API ke v1 sambil mempertahankan Accounts API di v1beta) tanpa harus mengupdate seluruh integrasi Anda sekaligus.

Perubahan kolom mendetail

Tabel ini memberikan perbandingan mendetail tentang kolom yang telah berubah antara versi v1beta dan v1.

v1beta v1 Deskripsi
ProductInput.name ProductInput.name Unpadded base64url encoding didukung dan wajib untuk nama produk yang berisi karakter yang digunakan oleh Merchant API atau karakter yang dicadangkan URL.
Product.name Product.name Unpadded base64url encoding didukung dan wajib untuk nama produk yang berisi karakter yang digunakan oleh Merchant API atau karakter yang dicadangkan URL.
Product.gtin Product.gtins Kolom untuk GTIN telah diganti namanya.
Product.taxes Dihapus Kolom taxes telah dihapus
Product.taxCategory Dihapus Kolom taxCategory telah dihapus
Product.channel Dihapus Kolom channel telah dihapus. Gunakan kolom legacyLocal untuk kasus penggunaan lokal.
Product.attributes Product.productAttributes Kolom attributes telah diganti namanya menjadi productAttributes.
availability, condition, gender, includedDestinations, dan excludedDestinations di kolom Product direpresentasikan sebagai strings (atau array dari strings) Kolom ini sekarang berupa enums (atau array dari enums) Kolom dengan daftar nilai singkat yang ditentukan diubah dari jenis string menjadi enum.
price, salePrice, salePriceEffectiveDate, dan availability di RegionalInventory Dipindahkan ke RegionalInventory.regionalInventoryAttributes Kolom ini telah dipindahkan ke bagian regionalInventoryAttributes.
Kolom RegionalInventory.availability adalah string RegionalInventory.regionalInventoryAttributes.availability kini berupa enums Jenis ketersediaan diubah dari string menjadi enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla, dan instoreProductLocation di LocalInventory Dipindahkan ke LocalInventory.localInventoryAttributes Kolom ini telah dipindahkan ke bagian localInventoryAttributes.
Kolom LocalInventory.availability adalah string LocalInventory.localInventoryAttributes.availability kini berupa enums Jenis ketersediaan diubah dari string menjadi enum.
LocalInventory.customAttributes Dihapus Atribut kustom tidak lagi didukung untuk inventaris lokal.
RegionalInventory.customAttributes Dihapus Atribut kustom tidak lagi didukung untuk inventaris regional.
ProductInput.channel Dihapus Kolom channel telah dihapus. Gunakan kolom legacyLocal untuk kasus penggunaan lokal.
DataSource.channel Dihapus Kolom channel telah dihapus. Gunakan kolom legacyLocal untuk kasus penggunaan lokal.
Tidak tersedia ProductInput.legacyLocal Kolom boolean baru untuk menunjukkan bahwa produk hanya dapat menargetkan lokal metode pemasaran. ID resource produk akan memiliki awalan "local~".
Tidak tersedia Product.legacyLocal Kolom boolean baru untuk menunjukkan bahwa produk hanya dijual di toko lokal dan tidak tersedia untuk pembelian online.
Tidak tersedia DataSource.legacyLocal Kolom boolean baru untuk menunjukkan bahwa sumber data berisi produk dijual hanya di toko lokal.
OrderTrackingSignals.LineItemDetails.gtin OrderTrackingSignals.LineItemDetails.gtins Kolom gtin telah diganti namanya menjadi gtins dan kini berupa array string (bukan string).
CreateAndConfigureAccountRequest.users Dihapus Kolom users telah dihapus. Gunakan kolom user untuk menambahkan administrator awal ke akun.

Sebelumnya
Refactor code for concurrent requests
Berikutnya
Overview