Memilih antara feed file dan Merchant API

Anda dapat mengupload data produk ke Merchant Center menggunakan feed berbasis file, Merchant API, atau kombinasi keduanya:

  • Feed produk berbasis file: Upload file CSV, TSV, atau file XML menggunakan SFTP, Google Cloud Storage, Google Spreadsheet, atau pengambilan terjadwal.
  • Merchant API: Kirim permintaan terprogram langsung dari backend Anda untuk update inkremental saat data produk berubah, bersama dengan sinkronisasi katalog lengkap secara berkala.

Panduan ini membandingkan kedua pendekatan, menjelaskan kapan harus menggunakan salah satunya (atau keduanya), dan memberikan playbook migrasi langkah demi langkah jika Anda memutuskan untuk memindahkan beberapa atau semua produk dari feed file ke API.

Memilih pendekatan sumber data Anda

Evaluasi volatilitas katalog, arsitektur backend, dan alur kerja operasional Anda untuk memutuskan apakah akan menggunakan Merchant API, feed file, atau penyiapan hybrid.

Kapan harus menggunakan Merchant API

Gunakan sumber data utama API jika:

  • Integrasi terprogram langsung: Anda lebih memilih memanggil API langsung dari backend daripada membuat file dan mengelola pipeline transfer file (seperti SFTP atau Google Cloud Storage).
  • Volatilitas harga dan inventaris yang tinggi: Harga produk atau tingkat stok Anda sering berubah sepanjang hari.
  • Pembaruan langsung saat data berubah: Anda ingin mengirim perubahan produk ke Google segera setelah terjadi di backend, daripada menunggu pembuatan file dan upload terjadwal berikutnya.
  • Pembaruan katalog inkremental: Anda ingin menyisipkan, memperbarui, atau menghapus produk satu per satu saat produk tersebut berubah, tanpa mengupload ulang seluruh katalog setiap saat.
  • Pembaruan atribut parsial: Anda ingin memperbarui kolom tertentu dari produk (seperti price atau availability menggunakan productInputs.patch) tanpa mengirim ulang payload produk lengkap.

Kapan harus menggunakan feed file

Gunakan sumber data utama berbasis file jika:

  • Katalog statis: Data produk Anda jarang berubah (misalnya, sekali sehari atau kurang).
  • Backend khusus snapshot tanpa pelacakan delta: Backend Anda hanya mengekspor snapshot katalog lengkap dan tidak dapat melacak perubahan tingkat item atau penghapusan produk secara eksplisit.
  • Alur kerja berbasis spreadsheet: Tim non-teknis mengumpulkan atau mengganti data produk langsung di file Google Spreadsheet atau CSV.
  • Operasi dengan pemeliharaan rendah: Anda lebih memilih ekspor file terjadwal, dengan Merchant Center menangani pengambilan dan pemrosesan snapshot, daripada mengoperasikan integrasi API dengan pengaturan kecepatan permintaan, penanganan percobaan ulang, dan sinkronisasi katalog lengkap secara berkala.

Kapan harus menggunakan keduanya

Anda dapat menggabungkan feed file dan Merchant API di akun Merchant Center yang sama dalam skenario berikut:

  • Katalog produk yang dipartisi: Anda menggunakan Merchant API untuk produk yang berubah dengan cepat (seperti flash sale atau inventaris dengan perputaran tinggi) dan feed file untuk segmen katalog statis atau lini produk terpisah. Pastikan setiap produk hanya diupload oleh satu sumber data utama (lihat Penggunaan paralel dan kepemilikan sumber data utama).
  • Data utama API dengan feed tambahan berbasis file: Anda mengelola data produk inti melalui sumber data utama API, sementara tim non-teknis atau partner pihak ketiga menyediakan atribut tambahan melalui feed tambahan berbasis file (seperti Google Spreadsheet atau file CSV) yang digabungkan dengan aturan atribut, atau sebaliknya.
  • Migrasi parsial atau bertahap: Anda mentransisikan pasar, kategori, atau sub-akun tertentu ke API sambil mempertahankan sisa katalog Anda di feed file.

Jika Anda memutuskan untuk memindahkan beberapa atau semua produk dari feed file ke Merchant API, ikuti Playbook migrasi langkah demi langkah.

Perbedaan arsitektur utama

Feed file dan Merchant API berbasis push berbeda dalam cara Google memproses dan mengelola data produk:

Konsep Feed File Merchant API
Model Integrasi Dump file offline: Anda mengekspor katalog ke file dan mentransfernya menggunakan SFTP, Google Cloud Storage, Google Spreadsheet, atau pengambilan terjadwal. Integrasi terprogram langsung: Backend Anda mengirimkan permintaan langsung ke endpoint API.
Perincian Mutasi Pemrosesan massal: Mengubah satu item biasanya memerlukan pemrosesan ulang seluruh file. Transaksi terperinci: Anda dapat menyisipkan, mem-patch, atau menghapus hanya produk yang berubah.
Waktu Sinkronisasi Sinkronisasi batch: Perubahan menunggu di backend Anda hingga siklus ekspor dan transfer file terjadwal berikutnya. Panggilan langsung atau terjadwal: Anda dapat mengirim perubahan inkremental segera setelah terjadi, bersama dengan sinkronisasi penuh berkala.
Perilaku Penghapusan Implisit (Snapshot): Setiap file adalah snapshot lengkap; menghapus baris dari file utama akan menghapus produk. Eksplisit: Tidak ada konsep snapshot; panggil productInputs.delete untuk menghapus produk yang dihentikan.
Representasi Resource Satu Negara Bagian: Baris file Anda mewakili input mentah. Memisahkan data mentah dan data yang diproses: API membagi data menjadi ProductInput (input mentah Anda) dan Product (status akhir yang diproses).
Aturan Atribut (Feed) Diterapkan ke kolom file mentah di UI Merchant Center. Didukung di UI Merchant Center. Diperlukan saat menggabungkan data API dengan file tambahan pihak ketiga; opsional untuk transformasi sumber tunggal jika ditangani di backend Anda.

Penggunaan paralel dan kepemilikan sumber data utama ("update terakhir menang")

Meskipun Anda dapat menggunakan feed file dan API di akun Merchant Center yang sama, sebaiknya gunakan hanya satu metode untuk memasukkan produk tertentu.

Merchant Center beroperasi dengan model "update terakhir yang berlaku". Sumber data utama (API atau feed file) yang mengirimkan penyisipan produk terbaru akan mendapatkan kepemilikan utama atas data produk tersebut:

  • Jika sumber data file memiliki produk: Menghilangkan produk dari upload file berikutnya akan memicu penghapusan implisit, sehingga menghapus produk dari Merchant Center.
  • Jika sumber data API memiliki produk: Menghilangkan produk dari upload file tidak akan berpengaruh karena feed file tidak lagi memiliki produk tersebut. Anda harus memanggil accounts.productInputs.delete untuk menghapusnya.
  • Risiko kepemilikan ulang yang tidak disengaja: Jika feed file yang diperbarui berjalan setelah push API dan berisi produk, sumber data file akan mendapatkan kembali kepemilikan. Penghapusan berikutnya dari file akan menghapus produk secara tidak terduga.

Untuk menghindari penghapusan yang tidak terduga atau hilangnya pembaruan API, jangan melakukan pembaruan serentak pada produk yang sama menggunakan sumber data utama API dan file.

Pertimbangan API utama

Pahami perilaku Merchant API yang penting ini sebelum memulai implementasi:

Sumber data yang fleksibel (tanpa bahasa atau label)

Tidak seperti feed file yang mengharuskan Anda menentukan label feed target dan bahasa tertentu di awal, Merchant API memungkinkan Anda membuat sumber data utama tanpa menentukan feedLabel atau contentLanguage.

  • Upload fleksibel: Dengan opsi ini, Anda dapat mengupload produk dengan kombinasi bahasa atau label feed apa pun ke satu sumber data.
  • Pengelolaan yang disederhanakan: Anda tidak perlu membuat dan mengelola sumber data terpisah untuk setiap target pasar. Catatan: Untuk mengetahui detail selengkapnya tentang cara memilih strategi sumber data, lihat Memilih strategi sumber data.

Strategi dan kuota sinkronisasi

Tidak seperti feed file tempat Anda mengupload seluruh katalog dalam satu batch, rancang integrasi Merchant API Anda berdasarkan update inkremental dan sinkronisasi penuh yang bertahap:

  • Gabungkan update inkremental dengan sinkronisasi penuh berkala: Kirim permintaan productInputs.insert atau productInputs.patch saat atribut produk berubah di backend Anda. Karena hanya mengandalkan update inkremental dapat menyebabkan data Anda tidak sinkron seiring waktu, jalankan juga sinkronisasi penuh secara berkala untuk menyesuaikan katalog dengan sumber kebenaran (yang juga memperbarui masa berlaku produk 30 hari). Frekuensi menjalankan sinkronisasi penuh bergantung pada ukuran katalog dan kuota API yang tersedia.
  • Atur kecepatan permintaan untuk mematuhi kuota API: Jangan panggil API untuk semua produk Anda sekaligus. Meskipun perubahan inkremental dapat dikirim saat terjadi, sebarkan permintaan sinkronisasi penuh secara merata sepanjang hari agar tetap berada dalam kuota panggilan metode per menit dan harian Anda. Untuk mengetahui detailnya, lihat Kuota dan batas serta Membuat pembaruan rutin pada produk Anda.

Menguji integrasi Anda

Validasi logika integrasi Anda di lingkungan yang aman sebelum beralih ke produksi.

Menggunakan akun pengujian

Sebelum melakukan perubahan dalam produksi, sebaiknya jalankan langkah-langkah awal migrasi di akun pengujian dengan sandbox:

  1. Buat akun pengujian: Siapkan akun pengujian terisolasi untuk bereksperimen dengan aman tanpa memengaruhi iklan aktif atau listingan gratis.
  2. Membuat sumber data API: Berlatihlah membuat sumber data utama API.
  3. Menguji aturan atribut: Memverifikasi transformasi data dan penggabungan feed tambahan.
  4. Validasi payload dan kunci produk: Kirim contoh produk untuk memverifikasi penulisan huruf, encoding, dan penanganan error SKU.

Untuk mengetahui detailnya, lihat Langkah 1: Buat akun pengujian dan panduan Akun Pengujian.

Memvalidasi penyelarasan kunci produk

Pastikan kunci produk payload terprogram sama persis dengan SKU feed file Anda. Google mengidentifikasi produk dengan menggabungkan:

  • offerId (disebut id di feed file, peka huruf besar/kecil)
  • contentLanguage (misalnya, en)
  • feedLabel (misalnya, US)

Karakter khusus dan encoding

Jika kode produk Anda berisi karakter seperti /, %, atau ~, gunakan Format yang Dienkode (encoding base64url tanpa padding) dalam panggilan API Anda. Untuk mengetahui informasi selengkapnya, lihat ProductInput.name

Kontrol konkurensi

Dalam integrasi real-time, update dapat tiba tidak berurutan karena latensi jaringan. Untuk mencegah update lama menimpa data yang lebih baru, gunakan kolom versionNumber di resource ProductInput.

Playbook migrasi langkah demi langkah

Jika Anda memutuskan untuk memindahkan beberapa atau semua produk dari feed file ke Merchant API, ikuti playbook ini untuk mentransisikan produk tanpa kehilangan tayangan iklan atau histori penayangan.

1. Melatih migrasi di akun pengujian

Sebelum membuat perubahan dalam produksi, buat akun pengujian dengan sandbox menggunakan metode accounts.createTestAccount (lihat panduan Akun Pengujian). Akun pengujian menyediakan lingkungan terisolasi tempat penawaran disetujui secara default, verifikasi domain tidak diperlukan, dan data tidak pernah ditayangkan secara publik.

Gunakan akun pengujian untuk mencerminkan penyiapan produksi dan berlatih migrasi secara menyeluruh:

  1. Duplikasi penyiapan feed file Anda: Buat sumber data utama file (dan sumber data tambahan) di akun pengujian, lalu upload sampel file feed produksi Anda.
  2. Membuat sumber data dan aturan API pengujian: Buat sumber data utama API dan konfigurasikan aturan atribut atau penggabungan feed tambahan yang diperlukan.
  3. Menguji pengambilalihan kepemilikan dan penyelarasan kunci: Kirim permintaan productInputs.insert untuk produk contoh dan verifikasi bahwa sumber data API mengambil kepemilikan item yang ada tanpa membuat produk duplikat.
  4. Verifikasi update dan penghapusan: Uji update parsial dengan productInputs.patch dan penghapusan dengan productInputs.delete, lalu periksa resource yang dihasilkan dengan products.get.

2. Membuat sumber data API produksi

Sebelum mengirim data, buat sumber data utama berjenis API di akun Anda.

Membuat sumber data utama API

Untuk membuat sumber data yang menerima push API, kirim permintaan POST ke endpoint dataSources. Untuk mengetahui detail selengkapnya, lihat Membuat sumber data produk utama.

3. Mentransisikan aturan atribut khusus

Aturan atribut kustom terikat ke sumber data tertentu dan tidak otomatis ditransfer dari sumber data file ke sumber data API baru Anda.

Cara Anda mentransisikan aturan atribut bergantung pada tujuannya:

  • Penggabungan lintas sumber dan feed tambahan pihak ketiga: Jika Anda menggabungkan data API utama dengan sumber data tambahan eksternal (seperti file pemasok pihak ketiga, spreadsheet inventaris, atau feed promosi), Anda harus membuat ulang aturan atribut di UI Merchant Center dan melampirkannya ke sumber data API baru. Pra-pemrosesan sisi klien tidak dapat menggantikan aturan yang menggabungkan data di beberapa sumber independen.
  • Transformasi data sumber tunggal: Untuk pembersihan sumber tunggal, nilai default, atau pemformatan string pada data katalog utama Anda, pilih antara:
    • Transformasi backend (Direkomendasikan): Terapkan transformasi di sistem Anda sendiri sebelum memanggil API. Hal ini memberi Anda kontrol terprogram yang lebih besar, pengujian yang lebih mudah, dan proses debug yang lebih sederhana.
    • Aturan atribut Merchant Center: Buat ulang aturan transformasi untuk sumber data API baru di UI Merchant Center jika Anda ingin Merchant Center terus mengelolanya secara otomatis.

4. Mengaktifkan integrasi API

Aktifkan integrasi Products API produksi untuk mulai menyisipkan, memperbarui, dan menghapus produk di sumber data utama API baru:

  • Menyisipkan dan memperbarui produk (pengambilalihan kepemilikan): Kirim permintaan productInputs.insert dan productInputs.patch dari integrasi Anda. Saat Anda menyisipkan produk menggunakan API dengan kunci yang sama (offerId, contentLanguage, feedLabel) seperti produk feed file yang ada, sumber data API akan mengambil kepemilikan produk tersebut dan mempertahankan histori penayangannya. Untuk panduan selengkapnya, lihat Menyisipkan produk dan Menambahkan dan mengelola produk.

  • Menghapus produk yang tidak lagi diproduksi: Konfigurasikan integrasi Anda untuk secara eksplisit memanggil productInputs.delete setiap kali produk dihapus dari katalog Anda.

  • Deploy secara bertahap: Untuk katalog besar, aktifkan integrasi Anda satu per satu sub-akun Merchant Center atau satu per satu sumber data.

  • Konfigurasi konkurensi: Jika mengirim banyak permintaan, konfigurasikan klien Anda untuk menangani permintaan serentak dan mengelola beberapa koneksi. Lihat panduan Merefaktorisasi kode untuk permintaan serentak.

5. Menjeda pembaruan sumber data file

Setelah integrasi API aktif, hentikan pembaruan file sebelum jadwal eksekusi file berikutnya agar sumber data file tidak menimpa pembaruan API Anda:

  1. Berhenti mengupload file baru ke lokasi SFTP/FTP, Google Cloud Storage, atau Google Spreadsheet.
  2. Di UI Merchant Center, buka sumber data file Anda dan jeda pengambilan terjadwalnya.
  3. Produk yang ada dan dimiliki oleh sumber data file akan tetap aktif hingga 30 hari sampai integrasi API Anda menyisipkannya.

6. Menunggu hingga migrasi selesai dan memverifikasi

Tunggu hingga semua produk aktif dimigrasikan dari sumber data file ke sumber data API. Meskipun update inkremental memigrasikan produk saat berubah, menjalankan sinkronisasi katalog lengkap secara bertahap melalui integrasi reguler akan mempercepat migrasi seluruh katalog Anda (lihat Strategi dan kuota sinkronisasi).

Selama fase ini:

  1. Di UI Merchant Center, pantau jumlah item. Tunggu hingga jumlah sumber data file berkurang menjadi 0 dan jumlah sumber data API sesuai dengan katalog aktif Anda.
  2. Gunakan products.get untuk memverifikasi bahwa atribut dan aturan atribut kustom digabungkan seperti yang diharapkan.
  3. Pantau alat diagnostik API di UI Merchant Center untuk melacak rasio error dan performa API.

7. Menonaktifkan sumber data file

Setelah transisi selesai dan jumlah item feed file adalah 0:

  1. Pastikan pembaruan ditampilkan secara real-time.
  2. Hapus sumber data file lama di UI Merchant Center untuk mencegah pembaruan berbasis file yang tidak disengaja menimpa data API Anda.
Sebelumnya
Migrate Local Inventory Ads settings