Halaman ini diterjemahkan oleh Cloud Translation API.

Bermigrasi dari Content API for Shopping ke Merchant API

Panduan ini menjelaskan proses migrasi dari Content API for Shopping ke Merchant API untuk pengelolaan data bisnis.

Anda dapat menggunakan panduan ini untuk memigrasikan penerapan Content API for Shopping yang ada ke Merchant API. Untuk mengetahui informasi selengkapnya tentang detail Merchant API dan sub-API-nya, lihat Desain Merchant API.

Mulai

Untuk mulai menggunakan Merchant API, ubah URL permintaan Anda ke format berikut:

https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…

Untuk menggunakan Merchant API, Anda harus menautkan akun Merchant Center dan project Google Cloud menggunakan metode Pendaftaran Developer, sebagai berikut:

POST https://merchantapi.googleapis.com/accounts/v1beta/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  developer_email:"example-email@example.com"
}

Untuk mengetahui informasi selengkapnya, lihat panduan memulai cepat dan referensi Merchant API.

Lihat update terbaru di Merchant API (beta).

Peningkatan dibandingkan Content API for Shopping

Merchant API memungkinkan Anda mengotomatiskan dan menyederhanakan alur kerja di Merchant Center serta menawarkan kemampuan yang lebih baik daripada Content API for Shopping.

Kasus penggunaan utama:

Pengelolaan akun otomatis
Pengelolaan produk otomatis
Pengelolaan inventaris otomatis
Pelaporan kustom

Area peningkatan utama:

Sub-API dengan fitur baru, termasuk:
- Pelacakan pesanan mendukung histori pelacakan pesanan bisnis untuk memberikan estimasi pengiriman yang tepat dan akurat kepada pelanggan. Sinyalnya juga memungkinkan listingan yang ditingkatkan dengan pengiriman gratis dan cepat.
- Penyelesaian masalah memberikan akses ke konten diagnostik dan tindakan dukungan dengan cara yang sama seperti yang tersedia di UI Merchant Center.
- Product Studio (ALPHA) memanfaatkan AI generatif untuk membuat dan mengoptimalkan judul dan deskripsi produk. Anda harus menandatangani formulir ini untuk meminta akses.
- Resource baru di Accounts sub-API.
- OmnichannelSettings mengelola konfigurasi akun untuk penayangan omnichannel, seperti Listingan Lokal Gratis (FLL) dan Iklan Inventaris Lokal (LIA).
- LfpProviders terhubung ke partner Kemitraan Feed Lokal (LFP) untuk data inventaris.
- GbpAccounts terhubung ke akun Google Profil Bisnis untuk data toko lokal.
- OnlineReturnPolicy memberikan kemampuan untuk membuat, menghapus, dan memperbarui kebijakan online Anda.
Metode baru untuk inventaris, data produk, dan API lainnya, termasuk:
- Metode baru di sub-API Produk.
- ProductsUpdate memungkinkan Anda memperbarui produk satu per satu tanpa perlu memberikan semua kolom yang diperlukan untuk ProductInput.
Kemampuan untuk membuat tidak hanya sumber data utama, tetapi juga beberapa sumber data seperti:
Memperkenalkan upload ulasan produk dan ulasan penjual
Dengan Merchant API, Anda dapat mengaktifkan notifikasi untuk perubahan pada data akun

Apa saja yang berubah:

Jumlah maksimum pageSize ditingkatkan dari 250 menjadi 1.000 baris per panggilan API.
Penundaan yang terjadi untuk penyisipan produk, promosi, ulasan produk, dan ulasan penjual setelah pembuatan DataSources telah diperbaiki.

Yang akan hadir:

Penghentian penggunaan dan penghapusan kolom saluran untuk DataSources dan produk pada masa mendatang.
Peluncuran definisi yang diperbarui untuk clickPotentialRank di tabel productView di bagian sub-API Pelaporan: * Peringkat produk berdasarkan clickPotential dinormalisasi ke nilai antara 1 dan 1000.
- Produk dengan clickPotentialRank rendah masih memiliki potensi klik tertinggi di antara produk penjual yang memenuhi kondisi kueri penelusuran. Ini adalah perubahan yang tidak merusak dan mungkin diluncurkan pada 1 Juli 2025.
AccountIdAlias di resource AccountRelationship memungkinkan pengelolaan struktur akun yang kompleks menjadi lebih baik. Misalnya, marketplace menggunakan alias yang ditentukan pengguna, bukan ID internal penjual, seperti ID akun.

Dukungan gRPC

Merchant API mendukung gRPC dan REST. Anda dapat menggunakan gRPC untuk Merchant API dan REST untuk Content API for Shopping secara bersamaan.

Library klien Merchant API memerlukan gRPC.

Untuk mengetahui informasi selengkapnya, lihat Ringkasan gRPC.

Kompatibilitas

Panduan ini menjelaskan perubahan umum yang berlaku untuk seluruh Merchant API.

Merchant API dirancang untuk bekerja bersama fitur Content API for Shopping yang ada.

Misalnya, Anda dapat menggunakan Merchant Inventories API bersama dengan implementasi Content API for Shopping v2.1 products yang ada. Anda dapat menggunakan Content API for Shopping untuk mengupload produk lokal baru (yang Anda jual di toko lokal), lalu menggunakan resource Merchant Inventories API LocalInventory untuk mengelola informasi di toko untuk produk tersebut.

Peningkatan dibandingkan Content API

Merchant API lebih baik daripada Content API di area berikut:

Sub-API dengan fitur baru untuk integrasi unik Anda
Metode baru untuk inventaris, data produk, dan API lainnya
Kemampuan untuk membuat tidak hanya sumber data utama, tetapi juga beberapa sumber data, seperti:
Memperkenalkan upload ulasan produk dan ulasan penjual
Dengan Merchant API, Anda dapat mengaktifkan notifikasi untuk perubahan pada data akun.
Memperkenalkan kemampuan pemfilteran untuk resource Accounts

Pertimbangkan perubahan ini secara lebih mendetail.

Pembuatan versi dan sub-API

Merchant API memperkenalkan konsep pembuatan versi dan sub-API. Desain modularnya meningkatkan kemudahan penggunaan, karena Anda dapat berfokus pada sub-API yang diperlukan dan memungkinkan migrasi yang lebih mudah ke versi yang lebih baru pada masa mendatang. Pemberian versi akan diterapkan dengan URL permintaan Anda.Strateginya mirip dengan pengalaman Google Ads API.

Permintaan yang lebih kuat

Permintaan URL Merchant API memerlukan lebih banyak parameter untuk memanggil Merchant API. Hal ini mencakup resource, versi, nama (ID), dan metode (metode non-standar). Untuk mengetahui informasi selengkapnya tentang hal ini, lihat ID Akun dan Produk dan contoh.

Prinsip AIP untuk ID

Meskipun Content API for Shopping menggunakan ID untuk mengidentifikasi resource (misalnya, merchantId, productId), Merchant API menggunakan name ID untuk disesuaikan dengan AIP (lihat prinsip peningkatan API).

ID {name} mencakup ID resource dan induknya (atau beberapa induk), sehingga {name} sama dengan accounts/{account}/products/{product}

Semua panggilan baca dan tulis menampilkan kolom name sebagai ID resource.

{name} juga mencakup ID koleksi accounts/ dan products/.

Merchant API menggunakan {account} untuk merujuk ke ID Merchant Center dan {product} untuk merujuk ke kode produk.

Misalnya, terapkan metode getName() untuk mengambil name dari resource, dan simpan output sebagai variabel, bukan membuat name dari ID penjual dan ID resource sendiri.

Berikut adalah contoh cara menggunakan kolom name dalam panggilan Anda:

   POST https://merchantapi.googleapis.com/inventories/v1beta/{PARENT}/regionalInventories:insert

Tabel ini menunjukkan perubahan permintaan products.get Content API for Shopping:

Content API for Shopping	Merchant API
`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`GET https://merchantapi.googleapis.com/products/v1beta/{name}`

Untuk mengetahui detail selengkapnya, tinjau Perubahan ID.

Sebagai contoh lain, mengambil produk dengan ID online~en~US~1234 dari ID Merchant Center 4321 menggunakan Merchant API akan terlihat seperti berikut:

    GET
    https://merchantapi.googleapis.com/products/v1beta/accounts/4321/products/online~en~US~1234

dengan {name} sama dengan accounts/4321/products/online~en~US~1234. Kolom nama baru ini ditampilkan sebagai ID resource untuk semua panggilan baca dan tulis di Merchant API.

Di Content API for Shopping, titik dua (:) menunjukkan pemisah dalam nama produk, sedangkan di Merchant API, tilde (~) menjalankan fungsi ini.

Misalnya, ID produk di Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

di Merchant Center API menjadi sebagai berikut:

channel~contentLanguage~feedLabel~offerId.

Kolom induk untuk resource turunan

Di Merchant API, semua resource turunan memiliki kolom parent. Anda dapat menggunakan kolom parent untuk menentukan {name} resource yang akan disisipkan turunan, alih-alih meneruskan seluruh resource induk. Anda juga dapat menggunakan kolom parent dengan list

Misalnya, untuk mencantumkan inventaris lokal untuk produk tertentu, tentukan name produk di kolom parent untuk metode list. Dalam hal ini, product yang diberikan adalah parent dari LocalInventory yang ditampilkan.

    GET
    https://merchantapi.googleapis.com/inventories/v1beta/{parent}/localInventories

Untuk mengambil semua inventaris lokal untuk produk online~en~US~1234' dan akun 4321, permintaan akan terlihat seperti

    GET
    https://merchantapi.googleapis.com/inventories/v1beta/accounts/4321/products/online~en~US~1234/localInventories</code>

Induknya adalah accounts/{account}/products/{product}. Perhatikan bahwa dalam kasus ini, resource localInventories memiliki dua induk yang disertakan dalam ID nama (accounts/ dan products/), karena akun adalah induk dari resource produk.

Enum umum

Penggunaan enum umum memberikan lebih banyak konsistensi.

Kolom Destination.DestinationEnum menentukan platform tempat resource Anda akan ditampilkan. DestinationEnum mencantumkan semua nilai yang tersedia untuk penargetan tujuan dan disatukan di seluruh sub-API, misalnya untuk atribut promosi.

Kolom ReportingContext.ReportingContextEnum mewakili konteks yang berlaku untuk masalah akun dan produk Anda. Kolom ini digunakan di seluruh metode pelaporan (misalnya, untuk IssueSeverityPerReportingContext).

Kompatibilitas mundur

Saat Anda mulai menggunakan Merchant API, integrasi Content API for Shopping yang ada akan terus berfungsi tanpa gangguan. Untuk mengetahui informasi selengkapnya, lihat Kompatibilitas.

Setelah memigrasikan sub-API ke Merchant API, sebaiknya Anda hanya menggunakan Merchant API untuk sub-API yang dimigrasikan.

Ketersediaan remote procedure call (gRPC)

gRPC adalah cara baru yang direkomendasikan untuk berintegrasi dengan Merchant API.

Keunggulannya meliputi:

Tidak bergantung pada bahasa
Mengandalkan buffer protokol
Menggunakan HTTP/2 untuk menyediakan solusi skalabel berperforma tinggi (referensi RPC)

Jika Anda menggunakan library klien atau contoh kode kami, gRPC adalah mekanisme transportasi default.

Untuk mengetahui informasi selengkapnya tentang gRPC, lihat artikel berikut:
- Panduan gRPC
- menggunakan gRPC

Batching kustom menjadi batching bawaan

Batching bekerja lebih efisien saat Anda menggunakan panggilan asinkron. Pelajari lebih lanjut cara menggunakan panggilan paralel untuk mencapai batching di Merchant API dan cara Memfaktorkan ulang kode untuk permintaan serentak.

Untuk membantu mempercepat migrasi Anda, sebaiknya gunakan pustaka klien.

Merchant API tidak mendukung metode customBatch yang ditampilkan di Content API for Shopping. Sebagai gantinya, lihat Mengirim beberapa permintaan sekaligus atau jalankan panggilan secara asinkron.

Contoh Java berikut menunjukkan cara memasukkan input produk.

   import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1beta.Attributes;
import com.google.shopping.merchant.products.v1beta.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1beta.ProductInput;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1beta.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1beta.Shipping;
import com.google.shopping.type.Channel.ChannelEnum;
import com.google.shopping.type.Price;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to insert a product input */
public class InsertProductInputAsyncSample {

  private static String getParent(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  private static String generateRandomString() {
    String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
    Random random = new Random();
    StringBuilder sb = new StringBuilder(8);
    for (int i = 0; i < 8; i++) {
      sb.append(characters.charAt(random.nextInt(characters.length())));
    }
    return sb.toString();
  }

  private static ProductInput createRandomProduct() {
    Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();

    Shipping shipping =
        Shipping.newBuilder().setPrice(price).setCountry("GB").setService("1st class post").build();

    Shipping shipping2 =
        Shipping.newBuilder().setPrice(price).setCountry("FR").setService("1st class post").build();

    Attributes attributes =
        Attributes.newBuilder()
            .setTitle("A Tale of Two Cities")
            .setDescription("A classic novel about the French Revolution")
            .setLink("https://exampleWebsite.com/tale-of-two-cities.html")
            .setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
            .setAvailability("in stock")
            .setCondition("new")
            .setGoogleProductCategory("Media > Books")
            .addGtin("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setChannel(ChannelEnum.ONLINE)
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setAttributes(attributes)
        .build();
  }

  public static void asyncInsertProductInput(Config config, String dataSource) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify where to insert the product.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (ProductInputsServiceClient productInputsServiceClient =
        ProductInputsServiceClient.create(productInputsServiceSettings)) {

      // Creates five insert product input requests with random product IDs.
      List<InsertProductInputRequest> requests = new ArrayList<>(5);
      for (int i = 0; i < 5; i++) {
        InsertProductInputRequest request =
            InsertProductInputRequest.newBuilder()
                .setParent(parent)
                // You can only insert products into datasource types of Input "API", and of Type
                // "Primary" or "Supplemental."
                // This field takes the `name` field of the datasource.
                .setDataSource(dataSource)
                // If this product is already owned by another datasource, when re-inserting, the
                // new datasource will take ownership of the product.
                .setProductInput(createRandomProduct())
                .build();

        requests.add(request);
      }

      System.out.println("Sending insert product input requests");
      List<ApiFuture<ProductInput>> futures =
          requests.stream()
              .map(
                  request ->
                      productInputsServiceClient.insertProductInputCallable().futureCall(request))
              .collect(Collectors.toList());

      // Creates callback to handle the responses when all are ready.
      ApiFuture<List<ProductInput>> responses = ApiFutures.allAsList(futures);
      ApiFutures.addCallback(
          responses,
          new ApiFutureCallback<List<ProductInput>>() {
            @Override
            public void onSuccess(List<ProductInput> results) {
              System.out.println("Inserted products below");
              System.out.println(results);
            }

            @Override
            public void onFailure(Throwable throwable) {
              System.out.println(throwable);
            }
          },
          MoreExecutors.directExecutor());

    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    // Identifies the data source that will own the product input.
    String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{datasourceId}";

    asyncInsertProductInput(config, dataSource);
  }
}InsertProductInputAsyncSample.java

Jika Anda menggunakan customBatch di Content API, dan memerlukan fitur ini untuk Merchant API, beri tahu kami alasannya dalam masukan Anda.

Fitur eksklusif

Fitur mendatang hanya akan muncul di Merchant API. (Akan ada beberapa pengecualian, seperti spesifikasi feed tahunan 2025.)

Fitur eksklusif untuk Merchant API mencakup

Reviews API. Gunakan Ulasan untuk menerapkan dan mengelola rating produk dan toko Anda. Untuk mengetahui informasi selengkapnya, lihat Ulasan Penjual dan Ulasan Produk.
Notifikasi: Mendaftar untuk menerima notifikasi push tentang perubahan pada data produk akun.

Harga

Berikut perubahan yang terjadi pada Price dalam paket Merchant Common:

	Content API for Shopping	Merchant API
Kolom jumlah	`value:string`	`amountMicros:int64`
Kolom mata uang	`currency:string`	`currencyCode:string`

Jumlah Price kini dicatat dalam mikro, dengan 1 juta mikro setara dengan satuan standar mata uang Anda.

Di Content API for Shopping, Price adalah bilangan desimal dalam bentuk string.

Nama kolom jumlah telah diubah dari value menjadi amountMicros

Nama kolom mata uang telah berubah dari currency menjadi currencyCode. Formatnya tetap ISO 4217.

Info dan pengumuman terbaru

Untuk mengetahui update yang lebih terperinci, lihat catatan rilis khusus untuk setiap sub-API. Untuk pembaruan Merchant API gabungan yang lebih rutin, tinjau pembaruan terbaru kami.

Untuk mengetahui detail yang lebih spesifik dan mempelajari Merchant API lebih lanjut, lihat ringkasan situs developer kami dan panduan migrasi secara keseluruhan untuk mengetahui detail selengkapnya.

Lihat Desain Merchant API untuk mengetahui detail tentang Merchant API dan sub-API-nya.

Sebelumnya

Quickstart

Berikutnya

Migrate from accountstatuses to Account Issues