Content API for Shopping'den Merchant API'ye geçiş yapma

Bu kılavuzda, Content API for Shopping'den Merchant API'ye geçiş süreci açıklanmaktadır.

Mevcut Content API for Shopping uygulamanızı Merchant API'ye taşımak için bu kılavuzdan yararlanabilirsiniz. Merchant API ve alt API'lerinin ayrıntıları hakkında daha fazla bilgi için Merchant API tasarımı başlıklı makaleyi inceleyin.

Başlayın

Merchant API'yi kullanmaya başlamak için istek URL'lerinizi aşağıdaki biçime değiştirin:

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

Merchant API'yi kullanmak için Merchant Center hesabınızı ve Google Cloud projenizi aşağıdaki gibi Geliştirici Kaydı yöntemini kullanarak bağlamanız gerekir:

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

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

Daha fazla bilgi için hızlı başlangıç kılavuzuna ve Merchant API referansına bakın.

Content API for Shopping'e göre iyileştirmeler

Merchant API, Merchant Center'daki iş akışlarını otomatikleştirmenize ve kolaylaştırmanıza olanak tanır. Ayrıca Content API for Shopping'e kıyasla gelişmiş özellikler sunar.

Temel kullanım alanları:

  • Otomatik hesap yönetimi
  • Otomatik ürün yönetimi
  • Otomatik envanter yönetimi
  • Özel raporlama

İyileştirilmesi gereken temel alanlar:

Değişiklikler:

  • Maksimum pageSize, API çağrısı başına 250 satırdan 1.000 satıra yükseltildi.
  • DataSources oluşturulduktan sonra ürün ekleme, promosyonlar, ürün yorumları ve satıcı yorumlarında yaşanan gecikme düzeltildi.

Sırada ne var?

  • productView tablosundaki clickPotentialRank için güncellenmiş bir tanımın kullanıma sunulması Reporting alt API'si altında: * clickPotential'ye göre ürünlerin sıralaması 1 ile 1.000 arasındaki değerlere normalleştirilir.
    • Düşük clickPotentialRank değerine sahip ürünler, arama sorgusu koşullarını karşılayan satıcının ürünleri arasında en yüksek tıklama potansiyeline sahiptir. Bu, 1 Temmuz 2025'te kullanıma sunulabilecek, uyumluluğu bozmayan bir değişikliktir.
  • AccountRelationship kaynağındaki AccountIdAlias, karmaşık hesap yapılarını daha iyi yönetmeyi mümkün kılar. Örneğin, pazar yerleri, satıcının dahili kimliği (ör. hesap kimliği) yerine kullanıcı tanımlı bir takma ad kullanır.

gRPC desteği

Merchant API, gRPC ve REST'i destekler. Merchant API için gRPC'yi, Content API for Shopping için ise REST'i aynı anda kullanabilirsiniz.

Merchant API istemci kitaplıkları için gRPC gerekir.

Daha fazla bilgi için gRPC'ye genel bakış başlıklı makaleyi inceleyin.

Uyumluluk

Bu kılavuzda, Merchant API'nin tamamı için geçerli olan genel değişiklikler açıklanmaktadır.

Merchant API, mevcut Content API for Shopping özellikleriyle birlikte çalışacak şekilde tasarlanmıştır.

Örneğin, Merchant Inventories API'yi mevcut Content API for Shopping 2.1 products uygulamanızla birlikte kullanabilirsiniz. Yeni bir yerel ürün yüklemek (yerel bir mağazada sattığınız) için Content API for Shopping'i kullanabilir, ardından bu ürünün mağaza içi bilgilerini yönetmek için Merchant Inventories API LocalInventory kaynağını kullanabilirsiniz.

Content API'ye kıyasla iyileştirmeler

Merchant API, Content API'ye kıyasla aşağıdaki alanlarda daha iyi performans gösterir:

Bu değişiklikleri daha ayrıntılı olarak inceleyelim.

Sürüm oluşturma ve alt API'ler

Merchant API, sürüm oluşturma ve alt API'ler kavramlarını sunar. Modüler tasarımı, ihtiyacınız olan alt API'lere odaklanmanıza olanak tanıyarak ve gelecekte daha yeni sürümlere geçişi kolaylaştırarak kullanım kolaylığını artırır. Sürüm oluşturma, istek URL'lerinizle birlikte uygulanır.Strateji, Google Ads API deneyimine benzer.

Daha sağlam istekler

Merchant API URL istekleri, Merchant API'yi çağırmak için daha fazla parametre gerektirir. Kaynak, sürüm, ad (tanımlayıcılar) ve yöntem (standart olmayan yöntemler) buna dahildir. Bu konuyla ilgili daha fazla bilgi ve örnek için Hesap ve ürün tanımlayıcıları başlıklı makaleyi inceleyin.

Tanımlayıcılar için AIP ilkeleri

Content API for Shopping, kaynakları tanımlamak için kimlikleri kullanırken (örneğin, merchantId, productId), Merchant API, AIP ile uyumlu olmak için name tanımlayıcısını kullanır (API geliştirme ilkelerine bakın).

{name} tanımlayıcısı, kaynak tanımlayıcıyı ve üst öğesini (veya muhtemelen birden fazla üst öğesini) içerir. Bu nedenle {name}, accounts/{account}/products/{product} değerine eşittir.

Tüm okuma ve yazma çağrıları, kaynak tanımlayıcısı olarak name alanını döndürür.

{name}, accounts/ ve products/ koleksiyon tanımlayıcılarını da içerir.

Merchant API, Merchant Center kimliğini belirtmek için {account}, ürün tanımlayıcılarını belirtmek için ise {product} kullanır.

Örneğin, name değerini bir kaynaktan almak için getName() yöntemini uygulayın ve satıcı ile kaynak kimliklerinden name değerini kendiniz oluşturmak yerine çıkışı değişken olarak saklayın.

Aramalarınızda name alanını kullanmayla ilgili örneği aşağıda bulabilirsiniz:

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

Tabloda, Content API for Shopping products.get isteğinin nasıl değiştiği gösterilmektedir:

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}

Daha fazla bilgi için Tanımlayıcı değişiklikleri başlıklı makaleyi inceleyin.

Başka bir örnek olarak, Merchant API'yi kullanarak Merchant Center kimliği 4321'den en~US~1234 tanımlayıcısına sahip bir ürünü alma işlemi aşağıdaki gibi görünür:

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

Burada {name}, accounts/4321/products/en~US~1234 değerine eşittir. Bu yeni ad alanı, Merchant API'deki tüm okuma ve yazma çağrıları için kaynak tanımlayıcı olarak döndürülür.

Content API for Shopping'de iki nokta üst üste (:), ürün adında sınırlayıcıyı belirtirken Merchant API'de bu işlevi tilda (~) görür. Satıcı API'si tanımlayıcısı channel bölümünü içermiyor.

Örneğin, Content API for Shopping'deki ürün kimliği:

channel:contentLanguage:feedLabel:offerId.

Merchant API'deki şu şekilde değişir:

contentLanguage~feedLabel~offerId.

Çocuk kaynakları için üst alanlar

Merchant API'de tüm alt kaynaklarda parent alanı bulunur. Tüm üst kaynağı iletmek yerine, alt öğenin ekleneceği kaynağın {name} değerini belirtmek için parent alanını kullanabilirsiniz. Ayrıca parent alanını list ile de kullanabilirsiniz.

Örneğin, belirli bir ürünün yerel envanterlerini listelemek için list yöntemiyle parent alanında ürünün name değerini belirtin. Bu durumda, verilen product, döndürülen LocalInventory kaynaklarının parent'idir.

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

en~US~1234' ürünü ve 4321 hesabı için tüm yerel envanterleri almak üzere gönderilecek istek şu şekilde görünür:

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

Üst öğe accounts/{account}/products/{product}. Bu durumda, hesabın ürün kaynağının üst öğesi olması nedeniyle localInventories kaynağının ad tanımlayıcısında iki üst öğe (accounts/ ve products/) bulunduğunu unutmayın.

Yaygın olarak kullanılan enumarasyonlar

Ortak numaralandırmaların kullanılması daha fazla tutarlılık sağlar.

Destination.DestinationEnum alanı, kaynaklarınızın gösterileceği yüzeyleri belirtir. DestinationEnum, hedef hedefleme için kullanılabilen tüm değerleri listeler ve alt API'ler arasında birleştirilmiştir. Örneğin, promotions attributes için.

ReportingContext.ReportingContextEnum alanı, hesap ve ürün sorunlarınızın geçerli olduğu bağlamı gösterir. Bu alan, raporlama yöntemlerinde (örneğin, IssueSeverityPerReportingContext için) kullanılır.

Geriye dönük uyumluluk

Merchant API'yi kullanmaya başladığınızda mevcut Content API for Shopping entegrasyonunuz kesintisiz olarak çalışmaya devam eder. Daha fazla bilgi için Uyumluluk başlıklı makaleye bakın.

Alt API'lerinizi Merchant API'ye taşıdıktan sonra, taşınan alt API'leriniz için yalnızca Merchant API'yi kullanmanızı öneririz.

Uzak prosedür çağrısı (gRPC) kullanılabilirliği

Merchant API ile entegrasyon için yeni ve önerilen yöntem gRPC'dir.

Bu yöntemin avantajları arasında şunlar yer alır:

Özel toplu işleme, yerleşik toplu işleme haline gelir

Toplu işleme, eşzamansız çağrıları kullandığınızda daha verimli çalışır. Merchant API'de toplu işleme elde etmek için paralel çağrıları kullanma ve eşzamanlı istekler için kodu yeniden düzenleme hakkında daha fazla bilgi edinin.

Taşıma işleminizi hızlandırmak için istemci kitaplıklarını kullanmanızı öneririz.

Merchant API, Content API for Shopping'de yer alan customBatch yöntemini desteklemez. Bunun yerine, Aynı anda birden fazla istek gönderme başlıklı makaleyi inceleyin veya çağrılarınızı eşzamansız olarak yürütün.

Aşağıdaki Java örneğinde, ürün girişinin nasıl ekleneceği gösterilmektedir.

   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.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 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

Content API'de customBatch kullanıyorsanız ve Merchant API için bu özelliğe ihtiyacınız varsa geri bildiriminizde nedenini belirtin.

Ayrıcalıklı özellikler

Gelecekteki özellikler yalnızca Merchant API'de yer alacaktır. (2025 yıllık feed özellikleri gibi birkaç istisna olacaktır.)

Merchant API'ye özel özellikler şunlardır:

  • Yorumlar API'si. Ürün ve mağaza puanlarınızı uygulamak ve yönetmek için yorumları kullanın. Daha fazla bilgi için Satıcı Yorumu ve Ürün Yorumu başlıklı makaleleri inceleyin.
  • Bildirimler: Bir hesabın ürün verilerinde yapılan değişikliklerle ilgili push bildirimleri almak için kaydolun.

Fiyat

Merchant Common paketinde Price ile ilgili yapılan değişiklikler:

Content API for Shopping Merchant API
Tutar alanı value:string amountMicros:int64
Para birimi alanı currency:string currencyCode:string

Price tutarı artık mikro cinsinden kaydediliyor. 1 milyon mikro, para biriminizin standart birimine eşittir.

Content API for Shopping'de Price, dize biçiminde bir ondalık sayıydı.

Tutar alanı adı value iken amountMicros olarak değiştirildi

Para birimi alanı adı currency iken currencyCode olarak değiştirildi. Biçim ISO 4217 olarak kalmaya devam eder.

En son güncellemeler ve duyurular

Daha ayrıntılı güncellemeler için her alt API'ye özel sürüm notlarına bakın. Daha düzenli toplu Merchant API güncellemeleri için en son güncellemelerimizi inceleyin.

Daha ayrıntılı bilgi edinmek ve Merchant API hakkında daha fazla şey öğrenmek için geliştirici sitemizdeki genel bakış ve genel geçiş kılavuzumuzu inceleyin.

Merchant API ve alt API'leri hakkında ayrıntılı bilgi için Merchant API tasarımı başlıklı makaleyi inceleyin.

Önceki
Quickstart
Sonraki
Migrate accountstatuses to Account Issues