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

Bu kılavuzda, işletme verileri yönetimi için 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ılavuzu kullanabilirsiniz. Merchant API ve alt API'leri 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 Geliştirici Kaydı yöntemini kullanarak aşağıdaki şekilde 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 kıyasla 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 daha gelişmiş özellikler sunar.

Temel kullanım alanları:

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

Geliştirilmesi gereken önemli alanlar:

Neler değişti?

  • Maksimum pageSize, API çağrısı başına 250'den 1.000 satıra çıkarıldı.
  • DataSources oluşturulduktan sonra ürün ekleme, promosyonlar, ürün yorumları ve satıcı yorumları için oluşan gecikme düzeltildi.
  • Reporting alt API'si altındaki productView tablosunda clickPotentialRank için güncellenmiş bir tanım kullanıma sunuldu:
    • Ürünlerin clickPotential metriğine göre sıralaması, 1 ile 1.000 arasındaki değerlere normalleştirilir.
  • AccountRelationship kaynağındaki AccountIdAlias, karmaşık hesap yapılarının daha iyi yönetilmesini sağlar. Örneğin, pazar yerleri satıcının dahili kimliği (ör. hesap kimliği) yerine kullanıcı tarafından tanımlanan bir takma ad kullanır.

gRPC desteği

Merchant API, gRPC ve REST'i destekler. Merchant API için gRPC'yi ve Content API for Shopping için 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 v2.1 products uygulamanızla birlikte kullanabilirsiniz. Content API for Shopping'i kullanarak yeni bir yerel ürün yükleyebilir (yerel bir mağazada sattığınız) ve ardından Merchant Inventories API LocalInventory kaynağını kullanarak bu ürünün mağaza içi bilgilerini yönetebilirsiniz.

Content API'de yapısal iyileştirmeler

Merchant API, Content API'ye kıyasla aşağıdaki alanlarda daha iyidir:

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ı kullanır. Modüler tasarımı, ihtiyacınız olan alt API'lere odaklanmanıza olanak tanıyarak kullanım kolaylığını artırır ve gelecekte daha yeni sürümlere daha kolay geçiş yapmanızı sağlar. Sürüm oluşturma, istek URL'lerinizle uygulanır. Bu 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. Buna kaynak, sürüm, ad (tanımlayıcılar) ve yöntem (standart olmayan yöntemler) dahildir. Bu konu hakkında daha fazla bilgi için Hesap ve ürün tanımlayıcıları ve örnekler başlıklı makaleleri inceleyin.

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

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

{name} tanımlayıcısı, kaynak tanımlayıcısını ve üst öğesini (veya potansiyel olarak birden fazla üst öğesini) içerir. Böylece {name}, accounts/{account}/products/{product} değerine eşit olur.

Tüm okuma ve yazma çağrıları, kaynak tanımlayıcı 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, bir kaynaktan name değerini almak için getName() yöntemini uygulayın ve name değerini satıcı ve kaynak kimliklerinden kendiniz oluşturmak yerine çıkışı değişken olarak depolayın.

Aşağıda, çağrılarınızda name alanını nasıl kullanacağınıza dair bir örnek verilmiştir:

   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 olan hesaptan 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/en~US~1234

{name}, accounts/4321/products/en~US~1234 değerine eşit. 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 ürün adındaki sınırlayıcı iki nokta üst üste (:) ile gösterilirken Merchant API'de bu işlev için yaklaşık işareti (~) kullanılır. Merchant API 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'de şu şekilde olur:

contentLanguage~feedLabel~offerId.

Alt kaynaklar için üst alanlar

Merchant API'de tüm alt kaynaklar parent alanına sahiptir. Üst kaynağın tamamını iletmek yerine, alt öğenin ekleneceği kaynağın {name} değerini belirtmek için parent alanını kullanabilirsiniz. parent alanını list ile de kullanabilirsiniz.

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

    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 istek şu şekilde görünür:

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

Üst öğe: accounts/{account}/products/{product}. Bu durumda, hesap ürün kaynağının üst öğesi olduğundan localInventories kaynağının ad tanımlayıcısına iki üst öğe (accounts/ ve products/) dahil edilir.

Sık kullanılan enum'lar

Ortak enum'ların kullanılması daha fazla tutarlılık sağlar.

Destination.DestinationEnum alanı, kaynaklarınızın gösterileceği yüzeyleri belirtir. DestinationEnum, hedefleme için kullanılabilen tüm değerleri listeler ve alt API'ler arasında (ör. promosyon özellikleri için) birleştirilir.

ReportingContext.ReportingContextEnum alanı, hesabınız ve ürün sorunlarınızın geçerli olduğu bağlamı temsil eder. Bu alan, raporlama yöntemlerinde (ör. 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 bölümüne 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

gRPC, Merchant API ile entegrasyon için önerilen yeni yöntemdir.

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

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

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

Geçişinizi hızlandırmak için istemci kitaplıklarını kullanmanızı öneririz.

Merchant API, Content API for Shopping'de bulunan customBatch yöntemini desteklemez. Bunun yerine, Aynı anda birden fazla istek gönderme bölümüne bakın veya çağrılarınızı eşzamansız olarak yürütün.

başlıklı makaleyi inceleyin.

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.api.gax.grpc.ChannelPoolSettings;
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()
            .setChannelPoolSettings(ChannelPoolSettings.staticallySized(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);
  }
}

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

Ayrıcalıklı özellikler

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

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

  • Reviews API. Ü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 sayfalarını inceleyin.
  • Bildirimler: Hesap ve ürün verilerindeki değişikliklerle ilgili push bildirimleri almak için kaydolun.

Fiyat

Merchant Common paketinde Price için 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 birim cinsinden kaydedilir. 1 milyon mikro birim, para biriminizin standart birimine eşdeğerdir.

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

value olan tutar alanı adı amountMicros olarak değiştirildi

currency olan para birimi alan adı 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 bir alt API'ye özel sürüm notlarına bakın. Merchant API ile ilgili daha düzenli ve toplu güncellemeler için en son güncellemelerimizi inceleyin.

Daha ayrıntılı bilgi edinmek ve Merchant API hakkında daha fazla bilgi edinmek için geliştirici sitemizdeki genel bakış bölümünü ve genel geçiş kılavuzunu inceleyin.

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

Sonraki
Start your migration