Merchant API Service

سرویس Merchant API به شما امکان می‌دهد از Merchant API در Apps Script برای آپلود محصولات و مدیریت حساب‌های Merchant Center استفاده کنید.

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

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

برای استفاده از سرویس Merchant API در Apps Script، سرویس‌های پیشرفته Apps Script را با استفاده از یکی از گزینه‌های زیر فعال کنید:

1. برای پروژه های جدید appsscript.json را فعال کنید . ما این گزینه را برای پروژه های Apps Script جدید توصیه می کنیم.

2. اسکریپت برنامه ها را برای پروژه های موجود فعال کنید . از این روش برای فعال کردن API های فرعی اضافی در پروژه های موجود استفاده کنید.

API ها را در appsscript.json فعال کنید

توجه: اگر از پروژه Apps Script موجود استفاده می‌کنید، از دستورالعمل‌های بخش فعال کردن اسکریپت برنامه‌ها برای سایر APIهای فرعی یا پروژه‌های موجود استفاده کنید.

مثال زیر یک فایل appsscript.json را نشان می دهد که API های فرعی محصولات، حساب ها، گزارش ها و منابع داده را فعال می کند.

1. در ویرایشگر Apps Script، تنظیمات پروژه کلیک کنید.

   

2. گزینه Show "appsscript.json" manifest file in editor را فعال کنید.

3. در ویرایشگر، فایل appsscript.json را انتخاب کنید.

4. محتوای فایل appsscript.json خود را با موارد زیر جایگزین کنید:

   {
     "dependencies": {
       "enabledAdvancedServices": [
         {
           "userSymbol": "MerchantApiAccounts",
           "version": "accounts_v1beta",
           "serviceId": "merchantapi"
         },
         {
           "userSymbol": "MerchantApiDataSources",
           "version": "datasources_v1beta",
           "serviceId": "merchantapi"
         },
         {
           "userSymbol": "MerchantApiProducts",
           "version": "products_v1beta",
           "serviceId": "merchantapi"
         },
         {
           "userSymbol": "MerchantApiReports",
           "version": "reports_v1beta",
           "serviceId": "merchantapi"
         }
       ]
     },
     "exceptionLogging": "STACKDRIVER",
     "runtimeVersion": "V8"
   }
   appsscript.json
   

5. روی ذخیره کلیک کنید.

6. اکنون می توانید به زیر API های زیر در کد خود به صورت زیر مراجعه کنید:

   الف MerchantApiAccounts

   ب MerchantApiDataSources

   ج MerchantApiProducts

   د MerchantApiReports

Apps Script را برای زیرمجموعه‌های API یا پروژه‌های موجود فعال کنید

از مراحل زیر برای فعال کردن API های فرعی در پروژه های موجود استفاده کنید.

1. پروژه Apps Script خود را باز کنید.

2. در سمت چپ، روی ویرایشگر < > کلیک کنید.

3. در سمت چپ، در کنار Services ، روی Add a service + کلیک کنید.

4. API فرعی را که می خواهید در انتخابگر نسخه فعال کنید، انتخاب کنید.

5. شناسه را با نام API فرعی خود اضافه کنید. به عنوان مثال، برای فعال کردن API فرعی Inventories، نسخه inventories_v1beta را انتخاب کنید و شناسه را به MerchantApiInventories تغییر دهید.

   

   هشدار: هر سرویس باید یک شناسه منحصر به فرد داشته باشد. همیشه نام زیر API را به شناسه اضافه کنید.

6. اکنون می توانید به زیر API Inventories در کد خود به عنوان MerchantApiInventories مراجعه کنید.

کد نمونه

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

محصولات را لیست کنید

این مثال نحوه فهرست کردن محصولات برای یک حساب Merchant Center معین را نشان می‌دهد.

/**
 * Lists all products for a given Merchant Center account.
 */
function productList() {
  // IMPORTANT:
  // Enable the Merchant API Products Bundle Advanced Service and call it
  // "MerchantApiProducts"

  // Replace this with your Merchant Center ID.
  const accountId = '<MERCHANT_CENTER_ID>';

  // Construct the parent name
  const parent = 'accounts/' + accountId;

  try {
    console.log('Sending list Products request');
    let pageToken;
    // Set the page size to 1000. This is the maximum allowed page size.
    let pageSize = 1000;

    console.log('Retrieved products below:');
    // Call the Products.list API method. Use the pageToken to iterate through
    // all pages of results.
    do {
      response = MerchantApiProducts.Accounts.Products.list(parent, {pageToken, pageSize});
      console.log(response);
      pageToken = response.nextPageToken;
    } while (pageToken); // Exits when there is no next page token.
  } catch (e) {
    console.log('ERROR!');
    console.log(e);
  }
}
list_products_sample.gs

محصولات تایید نشده را فیلتر کنید

این مثال نحوه فیلتر کردن محصولات تایید نشده در حساب Merchant Center را نشان می‌دهد.

/**
 * Demonstrates how to filter disapproved products using the Merchant API Reports service.
 */
function filterDisapprovedProducts() {
  // IMPORTANT:
  // Enable the Merchant API Reports Bundle Advanced Service and call it
  // "MerchantApiReports"
  // Enable the Merchant API Products Bundle Advanced Service and call it
  // "MerchantApiProducts"

  // Replace this with your Merchant Center ID.
  const accountId = '<INSERT_MERCHANT_CENTER_ID>';

  // Construct the parent name
  const parent = 'accounts/' + accountId;

  try {
    console.log('Sending search Report request');
    // Set pageSize to the maximum value (default: 1000)
    let pageSize = 1000;
    let pageToken;
    // The query below is an example of a query for the productView that gets product informations
    // for all disapproved products.
    let query = 'SELECT offer_id,' +
        'id,' +
        'price,' +
        'title' +
        ' FROM product_view' +
        ' WHERE aggregated_reporting_context_status = "NOT_ELIGIBLE_OR_DISAPPROVED"';


    // Call the Reports.search API method. Use the pageToken to iterate through
    // all pages of results.
    do {
      response =
          MerchantApiReports.Accounts.Reports.search({query, pageSize, pageToken}, parent);
      for (const reportRow of response.results) {
        console.log("Printing data from Product View:");
        console.log(reportRow);

        // OPTIONALLY, you can get the full product details by calling the GetProduct method.
        let productName = parent + "/products/" + reportRow.getProductView().getId();
        product = MerchantApiProducts.Accounts.Products.get(productName);
        console.log(product);
      }
      pageToken = response.nextPageToken;
    } while (pageToken);  // Exits when there is no next page token.

  } catch (e) {
    console.log('ERROR!');
    console.log('Error message:' + e.message);
  }
}
filter_disapproved_products_sample.gs

یک گزارش برای یک حساب معین بازیابی کنید

این مثال نحوه بازیابی گزارش برای یک حساب Merchant Center معین را نشان می دهد.

/**
 * Searches a report for a given Merchant Center account.
 */
function searchReport() {
  // IMPORTANT:
  // Enable the Merchant API Reports Bundle Advanced Service and call it
  // "MerchantApiReports"

  // Replace this with your Merchant Center ID.
  const accountId = '<MERCHANT_CENTER_ID>';

  // Construct the parent name
  const parent = 'accounts/' + accountId;

  try {
    console.log('Sending search Report request');
    // Set pageSize to the maximum value (default: 1000)
    let pageSize = 1000;
    let pageToken;
    // Uncomment the desired query from below. Documentation can be found at
    // https://developers.google.com/merchant/api/reference/rest/reports_v1beta/accounts.reports#ReportRow
    // The query below is an example of a query for the product_view.
    let query = 'SELECT offer_id,' +
        'id,' +
        'price,' +
        'gtin,' +
        'item_issues,' +
        'channel,' +
        'language_code,' +
        'feed_label,' +
        'title,' +
        'brand,' +
        'category_l1,' +
        'product_type_l1,' +
        'availability,' +
        'shipping_label,' +
        'thumbnail_link,' +
        'click_potential' +
        ' FROM product_view';

    /*
    // The query below is an example of a query for the
    price_competitiveness_product_view. let query = "SELECT offer_id,"
                 + "id,"
                 + "benchmark_price,"
                 + "report_country_code,"
                 + "price,"
                 + "title,"
                 + "brand,"
                 + "category_l1,"
                 + "product_type_l1"
                + " FROM price_competitiveness_product_view"
                + " WHERE date BETWEEN '2023-03-03' AND '2025-03-10'"; */
    /*
    // The query below is an example of a query for the
    price_insights_product_view. let query = "SELECT offer_id,"
                     + "id,"
                     + "suggested_price,"
                     + "price,"
                     + "effectiveness,"
                     + "title,"
                     + "brand,"
                     + "category_l1,"
                     + "product_type_l1,"
                     + "predicted_impressions_change_fraction,"
                     + "predicted_clicks_change_fraction,"
                     + "predicted_conversions_change_fraction"
                    + " FROM price_insights_product_view"; */

    /*
    // The query below is an example of a query for the
    product_performance_view. let query = "SELECT offer_id,"
            + "conversion_value,"
            + "marketing_method,"
            + "customer_country_code,"
            + "title,"
            + "brand,"
            + "category_l1,"
            + "product_type_l1,"
            + "custom_label0,"
            + "clicks,"
            + "impressions,"
            + "click_through_rate,"
            + "conversions,"
            + "conversion_rate"
            + " FROM product_performance_view"
            + " WHERE date BETWEEN '2023-03-03' AND '2025-03-10'"; */

    // Call the Reports.search API method. Use the pageToken to iterate through
    // all pages of results.
    do {
      response =
          MerchantApiReports.Accounts.Reports.search({query, pageSize, pageToken}, parent);
      for (const reportRow of response.results) {
        console.log(reportRow);
      }
      pageToken = response.nextPageToken;
    } while (pageToken);  // Exits when there is no next page token.

  } catch (e) {
    console.log('ERROR!');
    console.log(e);
    console.log('Error message:' + e.message);
    if (e.stack) {
      console.log('Stack trace:' + e.stack);
    }
  }
}

search_report_sample.gs

فهرست همه منابع داده

این مثال نشان می دهد که چگونه می توان همه منابع داده را در یک حساب Merchant Center معین فهرست کرد.

/**
 * Lists all data sources for a given Merchant Center account.
 */
function listDataSources() {
  // IMPORTANT:
  // Enable the Merchant API DataSources Bundle Advanced Service and call it
  // "MerchantApiDataSources"

  // Replace this with your Merchant Center ID.
  const accountId = '<MERCHANT_CENTER_ID>';

  // Construct the parent name
  const parent = 'accounts/' + accountId;
  let dataSources = [];
  let primaryDataSources = [];
  try {
    console.log('Sending list DataSources request');
    let pageToken;
    let pageSize = 10;
    // Call the DataSources.list API method. Use the pageToken to iterate through
    // all pages of results.
    do {
      response =
          MerchantApiDataSources.Accounts.DataSources.list(parent, {pageSize, pageToken});
      for (const datasource of response.dataSources) {
        dataSources.push(datasource);
        if (datasource.primaryProductDataSource) {
          primaryDataSources.push(datasource);
        }
      }
      pageToken = response.nextPageToken;
    } while (pageToken);  // Exits when there is no next page token.
    console.log('Retrieved ' + dataSources.length + ' data sources.');
    console.log(
        'There were ' + primaryDataSources.length +
        ' primary product data sources.');
  } catch (e) {
    console.log('ERROR!');
    console.log(e);
  }
}
list_data_sources_sample.gs