Merchant API Service

تتيح لك خدمة Merchant API استخدام Merchant API في Apps Script لتحميل المنتجات وإدارة حسابات Merchant Center.

للحصول على معلومات تفصيلية عن Merchant API، يُرجى الاطّلاع على المستندات المرجعية. كما هو الحال مع جميع الخدمات المتقدّمة في Apps Script، تستخدم خدمة Merchant API الكائنات والطرق والمعلَمات نفسها التي تستخدمها واجهة برمجة التطبيقات العامة.

تتألف Merchant API من مجموعة من واجهات برمجة التطبيقات الفرعية، وهي عبارة عن مجموعات من الخدمات والموارد ذات الصلة. في ما يلي قائمة بواجهات برمجة التطبيقات الفرعية.

لاستخدام خدمة Merchant API في "برمجة تطبيقات Google"، فعِّل الخدمات المتقدّمة في "برمجة تطبيقات Google" باستخدام أحد الخيارات التالية:

1. تفعيل ملف appsscript.json للمشاريع الجديدة ننصح باستخدام هذا الخيار للمشاريع الجديدة في "برمجة تطبيقات Google".

2. تفعيل "برمجة تطبيقات Google" للمشاريع الحالية استخدِم هذه الطريقة لتفعيل واجهات برمجة تطبيقات فرعية إضافية في المشاريع الحالية.

تفعيل واجهات برمجة التطبيقات في appsscript.json

ملاحظة: إذا كنت تستخدم مشروعًا حاليًا في "برمجة التطبيقات"، اتّبِع التعليمات الواردة في القسم تفعيل "برمجة التطبيقات" لواجهات برمجة تطبيقات فرعية أخرى أو مشاريع حالية.

يوضّح المثال التالي ملف appsscript.json يتيح استخدام واجهات برمجة التطبيقات الفرعية الخاصة بالمنتجات والحسابات والتقارير ومصادر البيانات.

1. في محرِّر "برمجة تطبيقات Google"، انقر على إعدادات المشروع .

   

2. فعِّل الخيار عرض ملف البيان "appsscript.json" في المحرر.

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. يمكنك الآن الرجوع إلى واجهات برمجة التطبيقات الفرعية التالية ضمن الرمز الخاص بك على النحو التالي:

   أ. MerchantApiAccounts

   ب. MerchantApiDataSources

   ج. MerchantApiProducts

   د. MerchantApiReports

تفعيل Apps Script لواجهات برمجة التطبيقات الفرعية الإضافية أو المشاريع الحالية

اتّبِع الخطوات التالية لتفعيل واجهات برمجة التطبيقات الفرعية في المشاريع الحالية.

1. افتح مشروعك في "برمجة تطبيقات Google".

2. على يمين الصفحة، انقر على أداة التعديل < >.

3. على يمين الشاشة، بجانب الخدمات، انقر على إضافة خدمة +.

4. اختَر واجهة برمجة التطبيقات الفرعية التي تريد تفعيلها ضِمن أداة اختيار الإصدار.

5. أضِف المعرّف مع اسم واجهة برمجة التطبيقات الفرعية. على سبيل المثال، لتفعيل واجهة برمجة التطبيقات الفرعية Inventories، اختَر الإصدار inventories_v1beta وغيِّر المعرّف إلى MerchantApiInventories.

   

   تحذير: يجب أن يكون لكل خدمة معرّف فريد. أضِف دائمًا اسم واجهة برمجة التطبيقات الفرعية إلى المعرّف.

6. يمكنك الآن الرجوع إلى واجهة برمجة التطبيقات الفرعية الخاصة بالمستودعات الإعلانية ضمن الرمز البرمجي الخاص بك على النحو التالي: 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