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 implementasi 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/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

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

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

Peningkatan dibandingkan Content API for Shopping

Merchant API memungkinkan Anda mengotomatiskan dan menyederhanakan alur kerja di Merchant Center serta menawarkan kemampuan yang ditingkatkan dibandingkan 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 perkiraan pengiriman yang akurat dan tepat 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 sub-API Akun.
    • 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 Produk sub-API.
    • ProductsUpdate memungkinkan Anda memperbarui produk individual 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:

  • `pageSize` maksimum pageSize ditingkatkan dari 250 menjadi 1.000 baris per panggilan API.
  • Penundaan yang ada untuk penyisipan produk, promosi, ulasan produk, dan ulasan penjual setelah DataSources pembuatan telah diperbaiki.
  • Peluncuran definisi yang diperbarui untuk clickPotentialRank di tabel productView dalam sub-API Pelaporan:
    • Peringkat produk berdasarkan clickPotential dinormalisasi ke nilai antara 1 dan 1.000.
  • AccountIdAlias di AccountRelationship resource memungkinkan pengelolaan struktur akun yang kompleks dengan 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 didesain untuk berfungsi bersama fitur Content API for Shopping yang ada.

Misalnya, Anda dapat menggunakan Merchant Inventories API bersama 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 Merchant Inventories API LocalInventory resource untuk mengelola informasi di toko untuk produk tersebut.

Peningkatan dibandingkan Content API

Merchant API ditingkatkan dibandingkan Content API di area berikut:

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, dengan memungkinkan Anda berfokus pada sub-API yang diperlukan dan memungkinkan migrasi yang lebih mudah ke versi yang lebih baru pada masa mendatang. Pembuatan 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, lihat ID dan contoh 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 agar selaras dengan AIP (lihat prinsip peningkatan API).

ID {name} mencakup ID resource dan induknya (atau mungkin 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 ID produk.

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

Berikut contoh cara menggunakan kolom name dalam panggilan Anda:

   POST https://merchantapi.googleapis.com/inventories/v1/{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/v1/{name}

Untuk mengetahui detail selengkapnya, tinjau Perubahan ID.

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

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

dengan {name} sama dengan accounts/4321/products/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, fungsi ini dilakukan oleh tilde (~). ID Merchant API tidak berisi bagian channel.

Misalnya, ID produk di Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

di Merchant API menjadi berikut:

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 tempat menyisipkan turunan, bukan meneruskan seluruh resource induk. Anda juga dapat menggunakan kolom parent dengan list

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

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

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

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

Induknya adalah accounts/{account}/products/{product}. Perhatikan bahwa dalam hal 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 menampilkan resource Anda. DestinationEnum mencantumkan semua nilai yang tersedia untuk penargetan tujuan dan disatukan di seluruh sub-API, misalnya untuk promosi atribut.

Kolom ReportingContext.ReportingContextEnum mewakili konteks tempat masalah akun dan produk Anda berlaku. 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 gunakan Merchant API saja untuk sub-API yang dimigrasikan.

Ketersediaan remote procedure call (gRPC)

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

Keuntungannya meliputi hal berikut:

Batching kustom menjadi batching bawaan

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

Untuk membantu mempercepat migrasi, sebaiknya gunakan client libraries.

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

Contoh Java berikut menunjukkan cara menyisipkan 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.api.gax.grpc.InstantiatingGrpcChannelProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1.Availability;
import com.google.shopping.merchant.products.v1.Condition;
import com.google.shopping.merchant.products.v1.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1.ProductAttributes;
import com.google.shopping.merchant.products.v1.ProductInput;
import com.google.shopping.merchant.products.v1.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1.Shipping;
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();

    ProductAttributes attributes =
        ProductAttributes.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(Availability.IN_STOCK)
            .setCondition(Condition.NEW)
            .setGoogleProductCategory("Media > Books")
            .addGtins("9780007350896")
            .addShipping(shipping)
            .addShipping(shipping2)
            .build();

    return ProductInput.newBuilder()
        .setContentLanguage("en")
        .setFeedLabel("CH")
        .setOfferId(generateRandomString())
        .setProductAttributes(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 a channel provider. This provider manages a pool of gRPC channels
    // to enhance throughput for bulk operations. Each individual channel in the pool
    // can handle up to approximately 100 concurrent requests.
    //
    // Channel: A single connection pathway to the service.
    // Pool: A collection of multiple channels managed by this provider.
    //   Requests are distributed across the channels in the pool.
    //
    // We recommend estimating the number of concurrent requests you'll make, divide by 50 (50%
    // utilization of channel capacity), and set the pool size to that number.
    InstantiatingGrpcChannelProvider channelProvider =
        InstantiatingGrpcChannelProvider.newBuilder().setPoolSize(30).build();

    // Creates service settings using the credentials retrieved above.
    ProductInputsServiceSettings productInputsServiceSettings =
        ProductInputsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .setTransportChannelProvider(channelProvider)
            .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);
  }
}

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 yang 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: Daftar untuk menerima notifikasi push untuk perubahan pada data produk akun.

Harga

Berikut perubahan untuk Price di 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 unit standar mata uang Anda.

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

Nama kolom jumlah telah berubah dari value menjadi amountMicros

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

Pengumuman dan update terbaru

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

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

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