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

از 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 Center و پروژه Google Cloud خود را با استفاده از روش Developer Registration به شرح زیر پیوند دهید:

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

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

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

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

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

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

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

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

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

API های فرعی با ویژگی های جدید، از جمله:
- ردیابی سفارش از تاریخچه ردیابی سفارشات تجاری پشتیبانی می کند تا تخمین های دقیق و دقیق حمل و نقل را به مشتریان ارائه دهد. سیگنال های آن همچنین فهرست های پیشرفته را با ارسال رایگان و سریع فعال می کند.
- حل مشکل دسترسی به محتوای تشخیصی و اقدامات پشتیبانی را به همان روشی که در Merchant Center UI موجود است، فراهم می‌کند.
- Product Studio (ALPHA) از genAI برای تولید و بهینه سازی عناوین و توضیحات محصول استفاده می کند. برای درخواست دسترسی باید این فرم را امضا کنید.
- منابع جدید در API فرعی حساب‌ها .
- OmnichannelSettings پیکربندی حساب را برای سرویس دهی چند کاناله، مانند فهرست‌های محلی رایگان (FLL) و تبلیغات موجودی محلی (LIA) مدیریت می‌کند.
- LfpProviders برای داده های موجودی به شرکای Local Feeds Partnership (LFP) متصل می شود.
- GbpAccounts برای داده‌های فروشگاه محلی به حساب Google Business Profile متصل می‌شود.
- OnlineReturnPolicy امکان ایجاد، حذف و به روز رسانی خط مشی های آنلاین شما را فراهم می کند.
روش‌های جدید برای موجودی، داده‌های محصولات و سایر APIها، از جمله:
- روشی جدید در میانای برنامه‌سازی کاربردی فرعی محصولات .
- ProductsUpdate به شما امکان می دهد تا محصولات جداگانه را بدون نیاز به ارائه تمام فیلدهای مورد نیاز برای ProductInput به روز کنید.
توانایی ایجاد نه تنها منابع داده اولیه، بلکه چندین منبع داده مانند:
بارگذاری نظرات محصول و نظرات بازرگان را معرفی می کند
با Merchant 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 خرید نسخه 2.1 استفاده کنید. ممکن است از Content API برای خرید برای آپلود یک محصول محلی جدید (که در یک فروشگاه محلی می فروشید) استفاده کنید، سپس از منبع Merchant Inventories API LocalInventory برای مدیریت اطلاعات موجود در فروشگاه برای آن محصول استفاده کنید.

بهبود در Content API

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

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

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

نسخه سازی و API های فرعی

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

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

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

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

در حالی که Content API برای خرید از شناسه‌ها برای شناسایی منابع استفاده می‌کند (به عنوان مثال، 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/v1beta/{PARENT}/regionalInventories:insert

جدول نحوه تغییر درخواست Content API for Shopping products.get را نشان می دهد:

Content API برای خرید	Merchant API
`GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}`	`GET https://merchantapi.googleapis.com/products/v1beta/{name}`

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

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

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

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

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

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

channel:contentLanguage:feedLabel:offerId .

در Merchant Center API به صورت زیر می شود:

channel~contentLanguage~feedLabel~offerId .

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

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

به عنوان مثال، برای فهرست کردن موجودی‌های محلی برای یک محصول معین، 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</code>

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

شماره های رایج

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

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

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

سازگاری با عقب

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

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

در دسترس بودن تماس روش از راه دور (gRPC).

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

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

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

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

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

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

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 نیاز دارید، دلیل آن را در بازخورد خود به ما بگویید.

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

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

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

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

قیمت

این چیزی است که برای 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 است.

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

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

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

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

قبلی

Quickstart

بعدی

Migrate accountstatuses to Account Issues