نسخه بتای اول API فروشگاه در تاریخ ۲۸ فوریه ۲۰۲۶ متوقف و غیرفعال خواهد شد. برای مراحل انتقال به آخرین نسخه پایدار، به بخش «مهاجرت از نسخه بتای اول به نسخه ۱» مراجعه کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

این راهنما فرآیند مهاجرت از API محتوا برای خرید به API فروشنده برای مدیریت داده‌های تجاری را توضیح می‌دهد.

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

شروع کنید

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

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

برای استفاده از رابط برنامه‌نویسی کاربردی فروشگاه، باید حساب مرکز فروشگاه و پروژه Google Cloud خود را با استفاده از روش ثبت‌نام توسعه‌دهنده، به شرح زیر پیوند دهید:

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

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

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

بهبودهایی در رابط برنامه‌نویسی کاربردی محتوا برای خرید

رابط برنامه‌نویسی کاربردی فروشنده (Merchant API) به شما امکان می‌دهد گردش‌های کاری را در مرکز فروشندگان خودکار و ساده کنید و قابلیت‌های پیشرفته‌تری را نسبت به رابط برنامه‌نویسی کاربردی محتوا برای خرید ارائه می‌دهد.

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

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

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

زیر-APIها با ویژگی‌های جدید، از جمله:
- ردیابی سفارش از سابقه ردیابی سفارش تجاری پشتیبانی می‌کند تا تخمین‌های دقیق و صحیحی از هزینه ارسال را به مشتریان ارائه دهد. سیگنال‌های آن همچنین امکان ارسال رایگان و سریع را برای لیست‌های بهبود یافته فراهم می‌کند.
- حل مسئله، دسترسی به محتوای تشخیصی و اقدامات پشتیبانی را به همان روشی که در رابط کاربری مرکز فروشندگان موجود است، فراهم می‌کند.
- استودیو محصول (ALPHA) از genAI برای تولید و بهینه‌سازی عناوین و توضیحات محصول استفاده می‌کند. برای درخواست دسترسی ، باید این فرم را امضا کنید.
- منابع جدید در زیر-API حساب‌ها .
- OmnichannelSettings پیکربندی حساب را برای ارائه خدمات همه کانالی، مانند فهرست‌های محلی رایگان (FLL) و تبلیغات موجودی محلی (LIA)، مدیریت می‌کند.
- LfpProviders برای داده‌های موجودی به شرکای Local Feeds Partnership (LFP) متصل می‌شود.
- GbpAccounts برای داده‌های فروشگاه محلی به حساب نمایه کسب‌وکار گوگل متصل می‌شود.
- OnlineReturnPolicy امکان ایجاد، حذف و به‌روزرسانی سیاست‌های آنلاین شما را فراهم می‌کند.
روش‌های جدید برای موجودی، داده‌های محصولات و سایر APIها، از جمله:
- یک متد جدید در زیر-API محصولات .
- ProductsUpdate به شما امکان می‌دهد محصولات را به‌صورت جداگانه و بدون نیاز به ارائه تمام فیلدهای مورد نیاز برای ProductInput به‌روزرسانی کنید.
توانایی ایجاد نه تنها منابع داده اولیه، بلکه منابع داده چندگانه مانند:
آپلود نقد و بررسی محصولات و نقد و بررسی‌های فروشندگان را معرفی می‌کند.
با استفاده از Merchant API، می‌توانید اعلان‌ها را برای تغییرات در داده‌های حساب فعال کنید.

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

حداکثر pageSize از ۲۵۰ به ۱۰۰۰ ردیف در هر فراخوانی API افزایش یافت.
تأخیری که برای درج محصول، تبلیغات، بررسی محصول و بررسی فروشنده پس از ایجاد DataSources وجود داشت، برطرف شده است.

چه اتفاقی در راه است:

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

پشتیبانی از gRPC

رابط برنامه‌نویسی کاربردی فروشگاه (Merchant API) از gRPC و REST پشتیبانی می‌کند. می‌توانید همزمان از gRPC برای رابط برنامه‌نویسی کاربردی فروشگاه و از REST برای رابط برنامه‌نویسی کاربردی محتوا برای خرید استفاده کنید.

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

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

سازگاری

این راهنما تغییرات کلی را که در کل رابط برنامه‌نویسی کاربردی فروشنده اعمال می‌شود، شرح می‌دهد.

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

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

بهبودهایی در رابط برنامه‌نویسی کاربردی محتوا (Content API)

رابط برنامه‌نویسی کاربردی فروشنده (Merchant API) در زمینه‌های زیر نسبت به رابط برنامه‌نویسی کاربردی محتوا (Content API) بهبودهایی دارد:

زیر-APIها با ویژگی‌های جدید برای ادغام منحصر به فرد شما
روش‌های جدید برای موجودی، داده‌های محصولات و سایر APIها
توانایی ایجاد نه تنها منابع داده اولیه، بلکه منابع داده چندگانه، مانند:
آپلود نقد و بررسی محصولات و نقد و بررسی‌های فروشندگان را معرفی می‌کند.
با استفاده از Merchant API، می‌توانید اعلان‌ها را برای تغییرات در داده‌های حساب فعال کنید.
قابلیت فیلتر کردن برای منبع حساب‌ها را معرفی می‌کند.

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

نسخه‌بندی و زیر-APIها

رابط برنامه‌نویسی کاربردی فروشنده (Merchant API) مفاهیم نسخه‌بندی و زیر-APIها را معرفی می‌کند. طراحی ماژولار آن، با فراهم کردن امکان تمرکز بر زیر-APIهای مورد نیاز و امکان انتقال آسان‌تر به نسخه‌های جدیدتر در آینده، سهولت استفاده را بهبود می‌بخشد. نسخه‌بندی با URLهای درخواستی شما اعمال خواهد شد. این استراتژی مشابه تجربه API تبلیغات گوگل است.

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

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

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

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

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

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

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

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

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

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

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

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

API محتوا برای خرید	رابط برنامه‌نویسی کاربردی (API) فروشنده
`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`GET https://merchantapi.googleapis.com/products/v1/{name}`

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

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

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

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

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

برای مثال، شناسه محصول در API محتوا برای خرید:

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/online~en~US~1234/localInventories</code>

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

enum های رایج

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

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

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

سازگاری معکوس

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

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

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

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

از مزایای آن می‌توان به موارد زیر اشاره کرد:

زبان-آگنوستیک
به بافرهای پروتکل متکی است
از HTTP/2 برای ارائه راهکارهای مقیاس‌پذیر با عملکرد بالا استفاده می‌کند ( مرجع RPC )
اگر از کتابخانه‌های کلاینت یا نمونه‌های کد ما استفاده می‌کنید، gRPC مکانیزم انتقال پیش‌فرض است.
برای اطلاعات بیشتر در مورد gRPC، به لینک زیر مراجعه کنید:
- راهنمای gRPC
- از gRPC استفاده کن

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

وقتی از فراخوانی‌های غیرهمزمان استفاده می‌کنید، دسته‌بندی (batching) کارایی بیشتری دارد. درباره استفاده از فراخوانی‌های موازی برای دستیابی به دسته‌بندی در Merchant API و نحوه Refactor کردن کد برای درخواست‌های همزمان بیشتر بیاموزید.

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

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

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

   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

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

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

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

ویژگی‌های منحصر به فرد Merchant API شامل موارد زیر است

API نقد و بررسی‌ها. از نقد و بررسی‌ها برای پیاده‌سازی و مدیریت رتبه‌بندی محصولات و فروشگاه خود استفاده کنید. برای اطلاعات بیشتر به نقد فروشنده و نقد محصول مراجعه کنید.
اعلان‌ها : برای دریافت اعلان‌های فوری در مورد تغییرات در داده‌های محصول یک حساب کاربری، ثبت‌نام کنید.

قیمت

در اینجا تغییرات Price در بسته Merchant Common را مشاهده می‌کنید:

	API محتوا برای خرید	رابط برنامه‌نویسی کاربردی (API) فروشنده
فیلد مبلغ	`value:string`	`amountMicros:int64`
فیلد ارز	`currency:string`	`currencyCode:string`

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

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

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

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

آخرین به‌روزرسانی‌ها و اطلاعیه‌ها

برای به‌روزرسانی‌های جزئی‌تر، به یادداشت‌های انتشار مربوط به هر زیر-API مراجعه کنید. برای به‌روزرسانی‌های منظم‌تر و تجمیع‌شده‌ی API فروشگاه، آخرین به‌روزرسانی‌های ما را بررسی کنید.

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

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

قبلی

MCP Server

بعدی

Migrate accountstatuses to Account Issues