انتقال از Content API ویژه Shopping به Merchant 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"
}

برای اطلاعات بیشتر، راهنمای شروع سریع و مرجع «میانای برنامه‌سازی کاربردی فروشنده» را ببینید.

بهبودها نسبت به Content API ویژه Shopping

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

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

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

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

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

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

پشتیبانی از gRPC

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

کتابخانه‌های کارخواه «میانای برنامه‌سازی کاربردی بازرگان» به gRPC نیاز دارند.

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

سازگاری

این راهنما تغییرات کلی را که بر کل «میانای برنامه‌سازی کاربردی بازرگان» اعمال می‌شود شرح می‌دهد.

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

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

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

«میانای برنامه‌سازی کاربردی بازرگان» در زمینه‌های زیر نسبت به «میانای برنامه‌سازی کاربردی محتوا» بهبود یافته است:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

جدول نشان می‌دهد که درخواست Content API ویژه Shopping 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 ویژه Shopping:

channel:contentLanguage:feedLabel:offerId.

در «میانای برنامه‌سازی کاربردی بازرگان» به این تبدیل می‌شود:

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/) گنجانده شده‌اند، زیرا حساب ولی منبع محصول است.

تعداد مشترک

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

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

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

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

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

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

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

gRPC روش توصیه‌شده جدید برای ادغام با «میانای برنامه‌سازی کاربردی بازرگان» است.

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

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

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

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

«میانای برنامه‌سازی کاربردی فروشنده» از روش customBatch ویژه در «میانای برنامه‌سازی کاربردی محتوا ویژه 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 نیاز دارید، در بازخورد خود به ما بگویید چرا.

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

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

ویژگی‌های انحصاری «میانای برنامه‌سازی کاربردی بازرگان» شامل موارد زیر می‌شود

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

قیمت

این موارد برای Price در بسته «مشترک فروشنده» تغییر کرده است:

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

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

در «میانای برنامه‌سازی کاربردی محتوا برای خرید»، Price عدد اعشاری در قالب یک رشته بود.

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

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

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

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

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

برای جزئیات درباره «میانای برنامه‌سازی کاربردی بازرگان» و میاناهای برنامه‌سازی کاربردی فرعی آن، طراحی «میانای برنامه‌سازی کاربردی بازرگان» را ببینید.

بعدی
Start your migration