نظرة عامة على واجهة برمجة التطبيقات لمصادر البيانات للتجّار

توضّح هذه الصفحة كيفية إنشاء مصادر البيانات وتعديلها آليًا والتي تسمح لك بدمج المنتجات. تسهّل مصادر البيانات المبرمَجة عملية إرسال بيانات منتجاتك إلى Google. تضمن مصادر البيانات المبرمَجة وصول أحدث المعلومات حول المنتجات ذات الصلة من موقعك الإلكتروني إلى Google.

تتيح لك Content API for Shopping إنشاء مصادر بيانات أساسية فقط. باستخدام واجهة برمجة التطبيقات Merchant Data sources API، يمكنك إنشاء الأنواع التالية من مصادر البيانات:

لا تتيح لك Content API for Shopping إدارة مصادر البيانات إلا من خلال إدخال الملفات. تتيح لك Merchant API إدارة مصادر البيانات باستخدام مدخلات الملفات وواجهات برمجة التطبيقات.

باستخدام Merchant Data sources API، يمكنك إجراء ما يلي:

  • أنشئ مصدر بيانات أساسيًا جديدًا باستخدام feedLabel و contentLanguage محدّدَين.
  • أنشئ مصدر بيانات لا يتضمّن حقلَي feedLabel وcontentLanguage. باستخدام هذا النوع من مصادر البيانات، يمكنك استهداف بلدان متعددة لمنتجاتك، لأنّه يمكنك إدراج منتجات بمجموعات مختلفة من feedLabel وcontentLanguage في مصدر بيانات واحد.
  • أنشئ مصدر بيانات تكميليًا لربطه بمصدر بيانات أساسي حالي.
  • اضبط جدولاً زمنيًا لمصدر بيانات ملف.
  • سجِّل حسابك لإدارة مصادر البيانات تلقائيًا.
  • إدارة مصادر بيانات واجهة برمجة التطبيقات
  • يمكنك إدارة القاعدة التلقائية لمصادر البيانات باستخدام مصادر بيانات المنتجات الأساسية.
  • استخدِم أنواعًا أخرى من مصادر البيانات، مثل العروض الترويجية.

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

المتطلبات الأساسية

  • يجب أن يكون قد تم نقل حسابك إلى خلاصات لغة واحدة.

  • للتأكّد من أنّه سبق نقل الحساب إلى عملية تقسيم استهداف البيانات، استخدِم methods أو list في مصدر البيانات. في حال عدم استيفاء معايير الأهلية، ستتلقّى رسالة الاستثناء التالية وعليك التواصل مع فريق الدعم.

    This account is in the data sources migration process and can't be used with
this API yet. Contact support for more info on when this account will be able
to use the data sources endpoint.

إنشاء مصدر بيانات جديد

مصادر البيانات الأساسية هي مصادر البيانات الرئيسية لمستودع Merchant Center. لا يمكنك إضافة منتجات أو إزالتها إلا باستخدام مصدر بيانات أساسي. إذا كان كل منتج تضيفه إلى مصدر بياناتك الأساسي يستوفي متطلبات البيانات والأهلية في Merchant Center، لن تحتاج إلى إنشاء المزيد من مصادر البيانات.

لإنشاء مصدر بيانات أساسي جديد باستخدام feedLabel و contentLanguage محدّدَين، اضبط حقلَي feedLabel وcontentLanguage في الإعدادات الخاصة بالنوع. لمزيد من المعلومات عن هذه الحقول، اطّلِع على PrimaryProductDataSource.

يوضّح نموذج الطلب التالي كيفية إنشاء مصدر بيانات أساسي لمنتجاتك:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "primaryProductDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "feedLabel": "{FEED_LABEL}",
    "countries": [
      "{COUNTRY}"
    ],
    "channel": "ONLINE_PRODUCTS"
  }
}

غيِّر القيم في السلسلة على الشكل التالي:

  • {ACCOUNT_ID}: المعرّف الفريد لحسابك على Merchant Center.
  • {DISPLAY_NAME}: الاسم المعروض لمصدر البيانات
  • {CONTENT_LANGUAGE}: رمز اللغة المكوّن من حرفَين وفقًا لمعيار ISO 639-1 للمنتجات في مصدر البيانات
  • {FEED_LABEL}: تصنيف الخلاصة لمصدر البيانات
  • {COUNTRY}: رمز منطقة CLDR للبلد المستهدَف للمنتجات التي سيتم تحميلها باستخدام مصدر البيانات.

بعد تنفيذ الطلب بنجاح، يظهر الردّ التالي:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATA_SOURCE_ID}",
  "dataSourceId": "{DATA_SOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "primaryProductDataSource": {
    "channel": "ONLINE_PRODUCTS",
    "feedLabel": "{FEED_LABEL}",
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "countries": [
      "{COUNTRY}"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

لمزيد من المعلومات عن إنشاء مصدر بيانات، يُرجى الاطّلاع على الإجراء accounts.dataSources.create.

للاطّلاع على مصدر البيانات الذي تم إنشاؤه حديثًا، استخدِم الأسلوب accounts.dataSources.get أو accounts.dataSources.list.

إنشاء مصدر بيانات أساسي جديد يساعد في استهداف بلدان متعدّدة

لإنشاء خلاصة أساسية جديدة تساعدك في استهداف بلدان متعدّدة، عليك ضبط مصدر بياناتك باستخدام PrimaryProductDataSource ولا تضبط حقلَي feedLabel وcontentLanguage.

باستخدام Content API for Shopping، يتم إنشاء مصدر بيانات واحد فقط لواجهة برمجة التطبيقات لحسابك. باستخدام Merchant Data sources API، يمكنك الحصول على مصادر بيانات متعددة من واجهة برمجة التطبيقات، وبعضها يمكن أن يكون بدون ضبط الحقلين feedLabel وcontentLanguage.

يمكن أن تكون مصادر البيانات التي تتضمّن إدخال واجهة برمجة التطبيقات فقط بدون ضبط حقلَي feedLabel و contentLanguage. لا يمكن استخدام هذا النوع من مصادر البيانات في مدخلات الملفات.

إنشاء مصدر بيانات تكميلي وربطه بمصدر البيانات الأساسي

لا تُستخدَم مصادر البيانات التكميلية إلّا لتعديل بيانات المنتجات التي سبق أن تمّت إضافتها إلى مصدر بيانات أساسي واحد أو أكثر. يمكنك إنشاء عدّة مصادر بيانات تكميلية، ويمكن لكلّ منها إضافة بيانات إلى أي عدد من مصادر البيانات الأساسية.

يمكنك استخدام مصادر البيانات التكميلية لإجراء تعديلات جزئية على بيانات المنتجات من خلال إضافة المعرّف الفريد لمصدر البيانات كمَعلمة طلب بحث عند إجراء طلبات إلى الأسلوبين accounts.productInputs.insert و accounts.productInputs.delete. لا يمكنك استخدام مصادر البيانات التكميلية إلّا لتعديل المنتجات الحالية.

لإنشاء مصدر بيانات تكميلي، عليك ضبط مصدر البيانات باستخدام SupplementalProductDataSource ثم ربطه من خلال تعديل الحقل defaultRule في مصدر البيانات الأساسي.

يجب ضبط الحقلين feedLabel وcontentLanguage في مصادر بيانات الملفات التكميلية. يجب عدم ضبط حقلَي feedLabel و contentLanguage في مصادر بيانات البيانات التكميلية من واجهة برمجة التطبيقات.

إعداد جدول زمني لمصدر بيانات الملفات

لإعداد جدول زمني لخلاصة الملفات، اضبط مصدر البيانات ليكون مصدر بياناتملف باستخدام الحقل FileInput، ثم اضبط fetchsettings باستخدام الحقل FileInput.FetchSettings.

حذف مصدر بيانات

لحذف مصدر بيانات حالي من حسابك، استخدِم accounts.dataSources.delete هذه الطريقة.

استرجاع مصدر البيانات

لجلب ملف تم ضبطه في مصدر البيانات، استخدِم الأسلوب accounts.dataSources.fetch. تُجري هذه الطريقة عملية استرجاع البيانات على الفور من مصدر بيانات في حسابك. لا تعمل هذه الطريقة إلا على مصادر البيانات التي تتضمّن مجموعة إدخال ملف.

الحصول على مصدر البيانات

لاسترداد إعدادات مصدر البيانات لحسابك، استخدِم الإجراء accounts.dataSources.get.

مصدر بيانات القائمة

لعرض إعدادات مصادر البيانات لحسابك، استخدِم الطريقة accounts.dataSources.list.

مصدر بيانات التصحيح

لتعديل إعدادات مصدر بيانات حالي، استخدِم الأسلوب accounts.dataSources.patch.

تتيح لك مصادر بيانات المنتجات الأساسية إدارة القاعدة التلقائية لمصادر البيانات. القاعدة التلقائية هي القاعدة التي تنطبق على كل السمات في مصدر بياناتك. يمكن ضبط القاعدة التلقائية أثناء إنشاء مصدر البيانات أو من خلال تعديل مصدر بيانات حالي من خلال حقل القاعدة التلقائية.

لمزيد من المعلومات عن إعداد القواعد، يُرجى الاطّلاع على إعداد قواعد لمصادر بيانات المنتجات.

يضمن نموذج الإعداد التالي أنّه يتم أولاً أخذ جميع السمات من مصدر البيانات الذي يحمل المعرّف الفريد 1001. بعد ذلك، تتم إضافة السمات غير المتوفّرة من مصدر البيانات الأساسي. في النهاية، سيتم أخذ السمات المتبقية من مصدر البيانات التكميلية باستخدام المعرّف الفريد 1002 إذا لم يتم تقديمه في أي مصدر بيانات آخر. إذا تم تقديم السمة نفسها في مصادر بيانات متعددة، يتم اختيار القيمة الأعلى في القائمة.

defaultRule {
 takeFromDataSources: [
   '1001', // Supplemental product data source
   'self', //  Self reference to the primary data source
   '1002' // Supplemental product data source
 ]
}

الإدارة التلقائية للخلاصات

لتسجيل حسابك لإدارة مصادر البيانات تلقائيًا، عليك تنفيذ ما يلي:

بعد أن يصبح حسابك مؤهّلاً للتسجيل، يمكنك استخدام الطريقة accounts.autofeedSettings.updateAutofeedSettings لتفعيل الإدارة التلقائية لمصادر البيانات. يتيح تفعيل ميزة الإدارة التلقائية لمصادر البيانات لمحرّك بحث Google إضافة منتجاتك تلقائيًا من متجرك على الإنترنت والتأكّد من أنّها محدّثة دائمًا على منصات Google.

استرداد حالة تحميل الملف

للحصول على حالة مصدر بيانات باستخدام ملف أو استرجاع أو جدول بيانات، يمكنك استدعاء طريقة GET للخدمة accounts.dataSources.fileUploads. للحصول على نتيجة آخر عملية استرجاع لمصدر البيانات يتم احتسابها بشكل غير متزامن عند الانتهاء من معالجة مصدر البيانات، استخدِم اسم المعرّف latest.

GET https://merchantapi.googleapis.com/accounts/v1beta/{ACCOUNT_ID}/datasources/{DATASOURCE_ID}/fileUploads/latest

قد تحتوي حالة تحميل الملف على عرض تفصيلي لمنتجاتك، بما في ذلك أي مشاكل محتملة.

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