انتقال از Content API ویژه Shopping به Merchant API

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

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

شروع کنید

برای شروع استفاده از Merchant API، نشانی‌های وب درخواستتان را به قالب زیر تغییر دهید:

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

برای استفاده از Merchant API، باید حساب Merchant Center و پروژه Google Cloud خود را بااستفاده از روش «ثبت‌نام توسعه‌دهنده» به‌صورت زیر پیوند دهید:

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

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

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

بهبودهای Content API ویژه Shopping

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

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

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

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

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

  • حداکثر pageSize از ۲۵۰ به ۱۰۰۰ ردیف در هر فراخوانی میانای برنامه‌سازی کاربردی افزایش یافت.
  • تأخیری که برای درج محصول، تبلیغات، مرورهای محصول، و مرورهای فروشنده پس‌از ایجاد DataSources وجود داشت برطرف شده است.
  • راه‌اندازی تعریف به‌روزشده برای clickPotentialRank در جدول productView زیر زیرمیانای برنامه‌سازی کاربردی گزارش‌دهی:
    • رتبه‌بندی محصولات براساس clickPotential به مقادیر بین ۱ و ۱۰۰۰ نرمال‌سازی می‌شود.
  • AccountIdAlias در منبع AccountRelationship مدیریت بهتر ساختارهای پیچیده حساب را ممکن می‌سازد. برای مثال، بازارها به‌جای شناسه داخلی فروشنده، مانند شناسه حساب، از نام مستعار تعریف‌شده توسط کاربر استفاده می‌کنند.

پشتیبانی gRPC

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

کتابخانه‌های کارخواه Merchant API به gRPC نیاز دارند.

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

سازگاری

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

«میانای برنامه‌سازی کاربردی بازرگان» به‌گونه‌ای طراحی شده است که درکنار ویژگی‌های موجود «میانای برنامه‌سازی کاربردی محتوا برای خرید» کار کند.

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

بهبودهای ساختاری نسبت به Content API

Merchant API در زمینه‌های زیر نسبت‌به Content API بهبود یافته است:

این تغییرات را با جزئیات بیشتر درنظر بگیرید.

نسخه‌بندی و زیرمیاناهای برنامه‌سازی کاربردی

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

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

درخواست‌های نشانی وب Merchant API برای فراخوانی Merchant API به پارامترهای بیشتری نیاز دارند. این شامل منبع، نسخه، نام (شناسه‌ها)، و روش (روش‌های غیراستاندارد) می‌شود. برای اطلاعات بیشتر درباره این موضوع، به شناسه‌های حساب و محصول و نمونه‌ها مراجعه کنید.

اصول AIP برای شناسه‌ها

درحالی‌که Content API for Shopping از شناسه‌ها برای شناسایی منابع (برای مثال، merchantId، productId) استفاده می‌کند، Merchant API از شناسه name برای هم‌راستایی با AIP استفاده می‌کند (به اصول بهبود API مراجعه کنید).

شناسه {name} شامل شناسه منبع و والد آن (یا احتمالاً چند والد) است، به‌طوری‌که {name} برابر است با accounts/{account}/products/{product}

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

{name} همچنین شامل شناسه‌های مجموعه accounts/ و products/ است.

Merchant API از {account} برای اشاره به شناسه Merchant Center و از {product} برای اشاره به شناسه‌های محصول استفاده می‌کند.

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

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

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

جدول نشان می‌دهد که درخواست products.get «میانای برنامه‌سازی کاربردی محتوا برای خرید» چگونه تغییر می‌کند:

Content API for Shopping میانای برنامه‌سازی کاربردی فروشنده
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/{name}

برای جزئیات بیشتر، تغییرات شناسه را مرور کنید.

به‌عنوان مثالی دیگر، بازیابی محصولی با شناسه en~US~1234 از شناسه Merchant Center 4321 بااستفاده از Merchant API به‌صورت زیر خواهد بود:

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

که در آن {name} برابر با accounts/4321/products/en~US~1234 است. این فیلد نام جدید به‌عنوان شناسه منبع برای همه تماس‌های خواندن و نوشتن در Merchant API برگردانده می‌شود.

در Content API ویژه Shopping، دونقطه (:) نشان‌دهنده جداکننده در نام محصول است درحالی‌که در Merchant API، مدک (~) این عملکرد را دارد. شناسه Merchant API حاوی بخش channel نیست.

برای مثال، شناسه محصول در Content API for Shopping:

channel:contentLanguage:feedLabel:offerId.

در Merchant API به این صورت می‌شود:

contentLanguage~feedLabel~offerId.

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

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

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

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

برای بازیابی همه سیاهه‌های محلی برای محصول en~US~1234 و حساب 4321 درخواست به‌صورت زیر خواهد بود

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

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

Common enums

استفاده از شمارش‌های رایج سازگاری بیشتری را فراهم می‌کند.

فیلد Destination.DestinationEnum سطوحی را که منابع شما در آن‌ها نمایش داده می‌شود مشخص می‌کند. DestinationEnum همه مقادیر دردسترس برای هدف‌یابی مقصد را فهرست می‌کند و در سراسر میاناهای برنامه‌سازی کاربردی فرعی، مثلاً برای مشخصه‌های تبلیغات، یکپارچه است.

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

سازگاری با نسخه قدیمی

وقتی شروع به استفاده از Merchant API می‌کنید، ادغام Content API for Shopping موجود شما بدون وقفه به کار خود ادامه می‌دهد. برای اطلاعات بیشتر، سازگاری را ببینید.

وقتی میاناهای برنامه‌سازی کاربردی فرعی‌تان را به Merchant API منتقل کردید، توصیه می‌کنیم فقط از Merchant API برای میاناهای برنامه‌سازی کاربردی فرعی منتقل‌شده‌تان استفاده کنید.

دردسترس بودن فراخوانی رویه از راه دور (gRPC)

gRPC روش جدید توصیه‌شده برای ادغام با Merchant API است.

مزایای آن شامل موارد زیر است:

گروه‌بندی سفارشی به گروه‌بندی داخلی تبدیل می‌شود

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

برای کمک به تسریع انتقال، کتابخانه‌های کارخواه را توصیه می‌کنیم.

Merchant API از روش customBatch که در Content API for Shopping ارائه شده است پشتیبانی نمی‌کند. به‌جای آن، ارسال چندین درخواست به‌طور هم‌زمان را ببینید یا فراخوانی‌هایتان را به‌صورت ناهمگام اجرا کنید.

مراجعه کنید

نمونه Java زیر نحوه درج ورودی محصول را نشان می‌دهد:

   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);
  }
}

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

ویژگی‌های انحصاری

ویژگی‌های آینده فقط در Merchant API نشان داده خواهد شد. (چند استثنا وجود خواهد داشت، مثل مشخصات فید سالانه ۲۰۲۵.)

ویژگی‌های انحصاری Merchant API عبارت‌اند از:

  • Reviews API. از «مرورها» برای پیاده‌سازی و مدیریت رده‌بندی‌های محصول و فروشگاهتان استفاده کنید. برای اطلاعات بیشتر، مرور فروشنده و مرور محصول را ببینید.
  • اعلان‌ها: برای دریافت اعلان لحظه‌ای درباره تغییرات حساب و داده‌های محصول، ثبت‌نام کنید.

قیمت

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

Content API for Shopping میانای برنامه‌سازی کاربردی فروشنده
فیلد مبلغ value:string amountMicros:int64
فیلد واحد پول currency:string currencyCode:string

اکنون مبلغ Price به‌صورت میکرو ثبت می‌شود، که ۱ میلیون میکرو معادل واحد استاندارد پول رایج شما است.

در Content API ویژه Shopping،‏ Price عدد اعشاری به‌شکل رشته بود.

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

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

جدیدترین به‌روزرسانی‌ها و اطلاعیه‌ها

برای به‌روزرسانی‌های دقیق‌تر، یادداشت‌های انتشار مربوط به هر زیرمیانای برنامه‌سازی کاربردی را ببینید. برای به‌روزرسانی‌های تجمیعی منظم‌تر Merchant API، جدیدترین به‌روزرسانی‌های ما را مرور کنید.

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

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

قبلی
Manage and transition Google Cloud projects
بعدی
Start your migration