از Content API برای خرید به Merchant API مهاجرت کنید

این راهنما فرآیند انتقال از Content API for Shopping به Merchant API برای مدیریت داده های کسب و کار را توضیح می دهد.

می‌توانید از این راهنما برای انتقال Content API موجود برای اجرای خرید به Merchant API استفاده کنید. برای اطلاعات بیشتر درباره جزئیات Merchant API و APIهای فرعی آن، به طراحی Merchant API مراجعه کنید.

شروع کنید

برای شروع استفاده از Merchant API، URL های درخواستی خود را به فرمت زیر تغییر دهید:

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

برای اطلاعات بیشتر، راهنمای شروع سریع و مرجع Merchant API را ببینید.

آخرین به‌روزرسانی‌ها را در Merchant API (بتا) ببینید.

بهبود در Content API برای خرید

Merchant API به شما امکان می‌دهد گردش‌های کاری را در Merchant Center خودکار و ساده کنید و قابلیت‌های پیشرفته‌تری را در Content API برای خرید ارائه می‌دهد.

موارد استفاده کلیدی:

  • مدیریت خودکار حساب
  • مدیریت خودکار محصول
  • مدیریت خودکار موجودی
  • گزارش سفارشی

زمینه های کلیدی بهبود:

چه چیزی تغییر کرده است:

  • حداکثر pageSize از 250 به 1000 ردیف در هر تماس API افزایش یافت.
  • تاخیری که برای درج محصول، تبلیغات، بررسی محصول و بازبینی تاجر پس از ایجاد DataSources رفع شد.

چه چیزی در راه است:

  • منسوخ شدن و حذف فیلد کانال در آینده برای DataSources و محصولات.
  • راه اندازی یک تعریف به روز شده برای clickPotentialRank در جدول productView در زیر API گزارش : * رتبه بندی محصولات بر اساس clickPotential به مقادیر بین 1 تا 1000 عادی می شود.
    • محصولات با clickPotentialRank پایین همچنان بیشترین پتانسیل کلیک را در میان محصولات تاجری که شرایط درخواست جستجو را برآورده می‌کنند، دارند. این یک تغییر غیرقابل شکست است که ممکن است در 1 ژوئیه 2025 راه اندازی شود.
  • AccountIdAlias ​​در منبع AccountRelationship ، مدیریت بهتر ساختارهای پیچیده حساب را ممکن می سازد. به عنوان مثال، بازارها از یک نام مستعار تعریف شده توسط کاربر به جای شناسه داخلی تاجر، مانند شناسه حساب، استفاده می کنند.

پشتیبانی از gRPC

Merchant API از gRPC و REST پشتیبانی می کند. می‌توانید همزمان از gRPC برای Merchant API و REST برای Content API برای خرید استفاده کنید.

کتابخانه های مشتری API Merchant به gRPC نیاز دارند.

برای اطلاعات بیشتر، به نمای کلی gRPC مراجعه کنید.

سازگاری

این راهنما تغییرات کلی را که برای کل Merchant API اعمال می شود، توضیح می دهد.

Merchant API طوری طراحی شده است که در کنار Content API موجود برای ویژگی‌های خرید کار کند.

برای مثال، می‌توانید از Merchant Inventories API در کنار Content API موجود برای اجرای products خرید استفاده کنید. ممکن است از Content API برای خرید برای آپلود یک محصول محلی جدید (که در یک فروشگاه محلی می فروشید) استفاده کنید، سپس از منبع Merchant Inventories API LocalInventory برای مدیریت اطلاعات موجود در فروشگاه برای آن محصول استفاده کنید.

درخواست های دسته ای

Merchant API از روش customBatch که در Content API برای خرید ارائه شده است پشتیبانی نمی کند. درعوض، به ارسال چندین درخواست به صورت همزمان مراجعه کنید یا تماس های خود را به صورت ناهمزمان اجرا کنید.

نمونه زیر نحوه درج ورودی های محصول را به صورت ناهمزمان نشان می دهد.

جاوا 

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

اگر از customBatch در Content API برای خرید استفاده می‌کنید و به این ویژگی برای Merchant API نیاز دارید، دلیل آن را در بازخورد خود به ما بگویید.

شناسه ها

برای همسویی با اصول بهبود API Google، برخی از تغییرات را در شناسه‌های منابع Merchant API ایجاد کرده‌ایم.

استفاده از IDENTIFIER نشان می دهد که یک فیلد در پیام منبع برای شناسایی منبع استفاده می شود. به فیلد نام وصل شده است، فیلدهایی را که نشان دهنده نام منابع هستند ، ببینید.

مقدار IDENTIFIER نشان می‌دهد که فیلد به‌عنوان ورودی (یعنی OUTPUT_ONLY ) در زمینه یک متد ایجاد پذیرفته نمی‌شود، در حالی که IMMUTABLE در نظر گرفته می‌شود و به‌عنوان ورودی برای روش‌های جهش پذیرفته می‌شود که منبع را به عنوان نمونه ورودی اولیه می‌پذیرند: به‌روزرسانی استاندارد .

نام جایگزین شناسه می شود

همه منابع Merchant API از فیلد name به عنوان شناسه منحصر به فرد خود استفاده می کنند.

در اینجا مثالی از نحوه استفاده از فیلد name در تماس های خود آورده شده است:

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

جایی که name برابر است accounts/4321/products/online~en~US~1234 .

این فیلد name جدید به عنوان شناسه منبع برای همه تماس‌های خواندن و نوشتن در Merchant API برگردانده می‌شود.

به عنوان مثال، یک متد getName() برای بازیابی name از یک منبع پیاده سازی کنید و خروجی را به عنوان یک متغیر ذخیره کنید به جای اینکه خودتان name از شناسه های کسب و کار و منبع بسازید.

تعیین کننده ها

Merchant API از tildes به جای دو نقطه به عنوان جداکننده استفاده می کند.

جدول زیر شناسه محصول را برای Content API for Shopping و Merchant API مقایسه می کند:

Content API برای خرید Merchant API
channel:contentLanguage:feedLabel:offerId . به عنوان مثال، online:en:US:sku123 channel~contentLanguage~feedLabel~offerId . به عنوان مثال، online~en~US~sku123

فیلدهای والد برای منابع فرزند

در Merchant API، همه منابع فرزند دارای فیلد parent هستند. می توانید از فیلد parent برای تعیین name منبع برای درج فرزند به جای ارسال کل منبع والد استفاده کنید. همچنین می‌توانید از فیلد parent با روش‌های list برای فهرست کردن منابع فرزند آن parent استفاده کنید.

به عنوان مثال، برای فهرست کردن موجودی‌های محلی برای یک محصول معین، name محصول را در فیلد parent برای روش list مشخص کنید. در این حالت، product داده شده، parent منابع LocalInventory بازگشتی است.

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

برای بازیابی تمام موجودی های محلی برای محصول online~en~US~1234 و حساب 4321 ، درخواست به این صورت خواهد بود:

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

جایی که والد برابر است با حساب‌ها/{account}/products/{product}. توجه داشته باشید که در این مورد، موجودی‌های محلی دارای دو والدین هستند که در شناسه نام (حساب‌ها/و محصولات/) گنجانده شده‌اند، زیرا حساب، منبع منبع محصول است.

انواع رایج

در اینجا برخی از انواع رایج مشترک در میان APIهای فرعی Merchant API آورده شده است.

Destination.DestinationEnum

از قسمت Destination.DestinationEnum برای کنترل سطوحی که منابع شما باید نمایش داده شوند استفاده کنید. فیلد DestinationEnum تمام مقادیر موجود را برای هدف گذاری مقصد فهرست می کند. APIها DestinationEnum در چندین زیرمجموعه API، به عنوان مثال برای ویژگی‌های تبلیغاتی ، متحد می‌کنند.

ReportingContext.ReportingContextEnum

قسمت ReportingContext.ReportingContextEnum زمینه ای را نشان می دهد که مشکلات حساب و محصول شما برای آن اعمال می شود. این فیلد در روش های گزارش دهی (مانند IssueSeverityPerReportingContext ) استفاده می شود.

قیمت

این چیزی است که برای Price در بسته Merchant Common تغییر کرده است:

Content API برای خرید Merchant API
فیلد مقدار value:string amountMicros:int64
فیلد ارز currency:string currencyCode:string

مقدار Price اکنون بر حسب میکرو ثبت می شود، که در آن 1 میلیون میکرو معادل واحد استاندارد ارز شما است.

در Content API برای خرید، Price یک عدد اعشاری به شکل یک رشته بود.

نام فیلد مقدار از value به amountMicros تغییر کرده است

نام فیلد ارز از currency به currencyCode تغییر کرده است. فرمت به عنوان ISO 4217 باقی می ماند.

قبلی
Quickstart
بعدی
Migrate account management