الاختيار بين خلاصات الملفات وMerchant API

يمكنك تحميل بيانات المنتجات إلى Merchant Center باستخدام الخلاصات المستندة إلى الملفات أو Merchant API أو كليهما:

  • خلاصات المنتجات المستندة إلى الملفات: يمكنك تحميل ملفات CSV أو TSV أو ملفّات XML باستخدام بروتوكول النقل الآمن للملفات (SFTP) أو Google Cloud Storage أو "جداول بيانات Google" أو عمليات الحصول على الخلاصات وفق جدول زمني محدّد.
  • ‫Merchant API: يمكنك إرسال طلبات آلية مباشرةً من الواجهة الخلفية لإجراء تعديلات تزايدية عند تغيير بيانات المنتجات، بالإضافة إلى مزامنة الكتالوج بالكامل بشكل دوري.

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

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

قيِّم مدى تقلّب الكتالوج وبنية الخلفية وسير العمليات التشغيلية لتحديد ما إذا كنت ستستخدم Merchant API أو خلاصات الملفات أو إعدادًا مختلطًا.

حالات استخدام Merchant API

استخدِم مصدر بيانات أساسي لواجهة برمجة التطبيقات في الحالات التالية:

  • الدمج الآلي المباشر: تفضّل طلب واجهة برمجة تطبيقات مباشرةً من الواجهة الخلفية بدلاً من إنشاء الملفات وإدارة مسارات نقل الملفات (مثل بروتوكول النقل الآمن للملفات أو Google Cloud Storage).
  • تقلّب كبير في الأسعار والمستودع: تتغيّر أسعار منتجاتك أو مستويات المخزون بشكل متكرّر على مدار اليوم.
  • تعديلات فورية عند تغيير البيانات: تريد إرسال تغييرات المنتجات إلى Google فور حدوثها في الخلفية، بدلاً من انتظار عملية إنشاء الملفات وتحميلها المجدوَلة التالية.
  • تعديلات الكتالوج المتزايدة: تريد إدراج منتجات فردية أو تعديلها أو حذفها عند تغييرها، بدون إعادة تحميل الكتالوج بالكامل في كل مرة.
  • تعديلات جزئية على السمات: تريد تعديل حقول معيّنة لمنتج (مثل price أو availability باستخدام productInputs.patch) بدون إعادة إرسال حمولة المنتج الكاملة.

حالات استخدام خلاصات الملفات

استخدِم مصدر بيانات أساسي مستند إلى ملف في الحالات التالية:

  • الكتالوج الثابت: تتغيّر بيانات منتجاتك بشكل غير متكرّر (على سبيل المثال، مرّة واحدة في اليوم أو أقل).
  • الخلفية التي تستخدم اللقطات فقط بدون تتبُّع التغييرات: تصدّر الخلفية لقطات كاملة من الكتالوج فقط ولا يمكنها تتبُّع التغييرات على مستوى السلع أو عمليات حذف المنتجات الصريحة.
  • سير العمل المستند إلى جداول البيانات: تنظّم الفِرق غير الهندسية بيانات المنتجات أو تلغيها مباشرةً في "جداول بيانات Google" أو ملفات CSV.
  • عمليات تتطلّب صيانة منخفضة: تفضّل تصدير الملفات بشكل مجدول حيث يتولى Merchant Center معالجة عمليات الجلب واللقطات، بدلاً من تشغيل عملية دمج واجهة برمجة التطبيقات مع وتيرة الطلبات ومعالجة إعادة المحاولة والمزامنة الدورية للكتالوج الكامل.

حالات استخدام كليهما

يمكنك الجمع بين خلاصات الملفات وMerchant API في حساب Merchant Center نفسه في الحالات التالية:

  • كتالوجات المنتجات المقسّمة: يمكنك استخدام Merchant API للمنتجات التي تتغيّر بسرعة (مثل التخفيضات الكبيرة لفترة محدودة أو المخزون الذي يتغيّر بسرعة) وخلاصات الملفات لأقسام الكتالوج الثابتة أو مجموعات المنتجات المنفصلة. تأكَّد من تحميل كل منتج من خلال مصدر بيانات أساسي واحد فقط (راجِع الاستخدام الموازي وملكية مصدر البيانات الأساسي).
  • البيانات الأساسية من واجهة برمجة التطبيقات مع الخلاصات التكميلية المستندة إلى الملفات: يمكنك إدارة بيانات المنتجات الأساسية من خلال مصدر بيانات أساسي لواجهة برمجة التطبيقات، بينما تقدّم الفِرق غير الهندسية أو الشركاء الخارجيون سمات إضافية من خلال الخلاصات التكميلية المستندة إلى الملفات (مثل "جداول بيانات Google" أو ملفات CSV) المرتبطة بقواعد السمات، أو العكس.
  • النقل الجزئي أو التدريجي: يمكنك نقل أسواق أو فئات أو حسابات فرعية معيّنة إلى واجهة برمجة التطبيقات مع الاحتفاظ ببقية الكتالوج في خلاصات الملفات.

إذا قرّرت نقل بعض منتجاتك أو جميعها من خلاصات الملفات إلى Merchant API، يُرجى اتّباع دليل نقل البيانات المفصّل.

الاختلافات الرئيسية في البنية

تختلف خلاصات الملفات وMerchant API المستندة إلى الإرسال في طريقة معالجة Google لبيانات المنتجات وإدارتها:

الفكرة خلاصات الملفات Merchant API
نموذج الدمج تصدير الملفات بلا إنترنت: يمكنك تصدير الكتالوج إلى ملف ونقله باستخدام بروتوكول النقل الآمن للملفات (SFTP) أو Google Cloud Storage أو "جداول بيانات Google" أو الحصول على الخلاصات وفق جدول زمني محدّد. الدمج الآلي المباشر: يرسل الخلفية طلبات مباشرةً إلى نقطة نهاية واجهة برمجة التطبيقات.
دقة التغيير المعالجة المجمّعة: يتطلّب تعديل سلعة واحدة عادةً إعادة معالجة الملف بأكمله. المعاملات الدقيقة: يمكنك إدراج المنتجات التي تم تغييرها فقط أو تصحيحها أو حذفها.
توقيت المزامنة المزامنة المجمّعة: يتم الاحتفاظ بالتغييرات في الخلفية إلى أن يحين موعد الدورة التالية المجدوَلة لتصدير الملفات ونقلها. الطلبات الفورية أو المجدوَلة: يمكنك إرسال التغييرات المتزايدة فور حدوثها، إلى جانب عمليات المزامنة الكاملة الدورية.
سلوك الحذف ضمنية (لقطة): كل ملف هو لقطة كاملة، ويؤدي حذف صف من ملفك الأساسي إلى حذف المنتج. صريح: لا يتوفّر مفهوم اللقطة، لذا عليك استدعاء productInputs.delete لإزالة منتج تم إيقافه نهائيًا.
تمثيل الموارد حالة واحدة: تمثّل صفوف الملف الإدخال الأوّلي. فصل البيانات الأولية عن البيانات التي تمت معالجتها: تقسّم واجهة برمجة التطبيقات البيانات إلى ProductInput (البيانات الأولية التي أدخلتها) وProduct (الحالة النهائية للبيانات التي تمت معالجتها).
قواعد السمات (الخلاصات) يتم تطبيقها على أعمدة الملفات الأولية في واجهة مستخدم Merchant Center. تتوفّر هذه السمة في واجهة مستخدم Merchant Center. مطلوبة عند دمج بيانات واجهة برمجة التطبيقات مع ملفات تكميلية تابعة لجهات خارجية، واختيارية لعمليات التحويل من مصدر واحد إذا تم التعامل معها في الخلفية.

الاستخدام الموازي وملكية مصدر البيانات الأساسي ("الأولوية لآخر تعديل")

على الرغم من أنّه يمكنك استخدام كلّ من خلاصات الملفات وواجهة برمجة التطبيقات في حساب Merchant Center نفسه، ننصح بشدة باستخدام طريقة واحدة فقط لإدراج أي منتج معيّن.

يعمل Merchant Center وفقًا لنموذج "الأولوية لآخر تعديل". يحصل مصدر البيانات الأساسي (واجهة برمجة التطبيقات أو خلاصة الملفات) الذي أرسل أحدث عملية إدراج للمنتج على الملكية الأساسية لبيانات هذا المنتج:

  • عندما يكون مصدر بيانات الملف هو مالك المنتج: يؤدي حذف المنتج من عملية تحميل ملف لاحقة إلى حذفه ضمنيًا من Merchant Center.
  • عندما يكون مصدر بيانات واجهة برمجة التطبيقات هو المصدر الأساسي للمنتج: لن يؤدي حذف المنتج من ملف تم تحميله إلى أي نتيجة لأنّ خلاصة الملف لم تعُد المصدر الأساسي للمنتج. يجب الاتصال بالرقم ‎accounts.productInputs.delete لإزالته.
  • خطر إعادة الملكية عن طريق الخطأ: إذا تم تشغيل خلاصة ملف معدَّلة بعد إرسال البيانات عبر واجهة برمجة التطبيقات وكانت الخلاصة تحتوي على المنتج، يستعيد مصدر بيانات الملف الملكية. وبالتالي، ستؤدي عمليات الحذف اللاحقة من الملف إلى حذف المنتج بشكل غير متوقّع.

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

الاعتبارات الأساسية المتعلّقة بواجهة برمجة التطبيقات

من المهم فهم سلوكيات Merchant API الأساسية التالية قبل البدء في عملية التنفيذ:

مصادر بيانات مرنة (بدون لغة أو تصنيف)

على عكس خلاصات الملفات التي تتطلّب منك تحديد تصنيف خلاصة مستهدَف ولغة معيّنين مسبقًا، تتيح لك Merchant API إنشاء مصادر بيانات أساسية بدون تحديد feedLabel أو contentLanguage.

  • عمليات تحميل مرنة: تتيح لك هذه الميزة تحميل المنتجات بأي لغة أو تصنيف خلاصة إلى مصدر بيانات واحد.
  • إدارة مبسّطة: لن تحتاج إلى إنشاء وإدارة مصادر بيانات منفصلة لكل سوق مستهدَف. ملاحظة: لمزيد من التفاصيل حول اختيار استراتيجية مصدر البيانات، يُرجى الاطّلاع على اختيار استراتيجية مصدر البيانات.

استراتيجية المزامنة والحصص

على عكس خلاصة الملفات التي يتم فيها تحميل الكتالوج بأكمله دفعة واحدة، يجب تصميم عملية دمج Merchant API لتشمل كلاً من التعديلات المتزايدة والمزامنة الكاملة على فترات منتظمة:

  • الجمع بين التعديلات المتزايدة والمزامنة الكاملة الدورية: أرسِل طلبات productInputs.insert أو productInputs.patch عند تغيير سمات المنتجات في الخلفية. بما أنّ الاعتماد على التعديلات المتزايدة فقط قد يؤدي إلى عدم مزامنة بياناتك بمرور الوقت، ننصحك أيضًا بإجراء عمليات مزامنة كاملة بشكل دوري لمطابقة الكتالوج مع المصدر الموثوق (ما يؤدي أيضًا إلى إعادة ضبط فترة انتهاء صلاحية المنتجات التي تبلغ 30 يومًا). يعتمد معدّل تكرار المزامنة الكاملة على حجم الكتالوج وحصة واجهة برمجة التطبيقات المتاحة.
  • تنظيم الطلبات بما يتوافق مع حصص واجهة برمجة التطبيقات: لا تطلب البيانات من واجهة برمجة التطبيقات لجميع منتجاتك دفعة واحدة. على الرغم من إمكانية إرسال التغييرات المتزايدة فور حدوثها، يمكنك توزيع طلبات المزامنة الكاملة بالتساوي على مدار اليوم للبقاء ضمن حصص طلبات الإجراءات اليومية ولكل دقيقة. لمعرفة التفاصيل، يُرجى الاطّلاع على الحصص والحدود القصوى و إجراء تعديلات متكرّرة على منتجاتك.

اختبار عملية التكامل

Validate your integration logic in a safe environment before moving to production.

استخدام حسابات اختبارية

قبل إجراء تغييرات في الإنتاج، ننصحك بتنفيذ الخطوات الأولية لعملية نقل البيانات في حساب اختبار في وضع الحماية:

  1. إنشاء حساب اختباري: يمكنك إعداد حساب اختباري منفصل لإجراء التجارب بأمان بدون التأثير في الإعلانات أو البيانات المجانية المنشورة.
  2. إنشاء مصدر بيانات لواجهة برمجة التطبيقات: تدرَّب على إنشاء مصدر بيانات أساسي لواجهة برمجة التطبيقات.
  3. اختبار قواعد السمات: يمكنك التحقّق من عمليات تحويل البيانات وعمليات دمج الخلاصات التكميلية.
  4. التحقّق من صحة الحمولات ومفاتيح المنتجات: يمكنك إرسال عيّنات من المنتجات للتحقّق من حالة أحرف رموز التخزين التعريفية والترميز ومعالجة الأخطاء.

لمعرفة التفاصيل، يُرجى الاطّلاع على الخطوة 1: إنشاء حسابات تجريبية ودليل الحسابات التجريبية.

التحقّق من صحة توافق مفتاح المنتج

تأكَّد من أنّ مفتاح المنتج في الحمولة المبرمَجة يتطابق تمامًا مع رموز التخزين التعريفية في خلاصة الملفات. تتعرّف Google على المنتجات من خلال الجمع بين:

  • ‫offerId (يُشار إليها باسم id في خلاصات الملفات، وهي حسّاسة لحالة الأحرف)
  • contentLanguage (مثلاً en)
  • feedLabel (مثلاً US)

الرموز الخاصة والترميز

إذا كانت معرّفات منتجاتك تحتوي على أحرف مثل / أو % أو ~، استخدِم التنسيق المرمّز (ترميز base64url غير المبطّن) في طلبات البيانات من واجهة برمجة التطبيقات. لمزيد من المعلومات، يُرجى الاطّلاع على ProductInput.name

التحكّم في التزامن

في عملية الدمج في الوقت الفعلي، يمكن أن تصل التعديلات بترتيب غير صحيح بسبب وقت استجابة الشبكة. لمنع التعديلات القديمة من استبدال البيانات الأحدث، استخدِم الحقل versionNumber في المورد ProductInput.

دليل مفصّل حول نقل البيانات

إذا قرّرت نقل بعض منتجاتك أو جميعها من خلاصات الملفات إلى Merchant API، اتّبِع هذا الدليل الإرشادي لنقل منتجاتك بدون فقدان مرات الظهور أو سجلّ العرض.

1. التدرّب على عملية نقل البيانات في حساب تجريبي

قبل إجراء تغييرات في مرحلة الإنتاج، أنشِئ حسابًا تجريبيًا في وضع الحماية باستخدام طريقة accounts.createTestAccount (راجِع دليل الحسابات التجريبية). توفّر الحسابات الاختبارية بيئة معزولة تتم فيها الموافقة على العروض تلقائيًا، ولا تتطلّب إثبات ملكية النطاق، ولا يتم عرض البيانات فيها بشكل علني مطلقًا.

استخدِم حسابك الاختباري لنسخ إعدادات الإنتاج والتدريب على عملية نقل البيانات من البداية إلى النهاية:

  1. نسخ إعدادات خلاصة الملفات: أنشِئ مصدر بيانات أساسيًا للملفات (وأي مصادر بيانات تكميلية) في الحساب التجريبي وحمِّل عيّنة من ملف الخلاصة الإنتاجية.
  2. إنشاء مصدر بيانات وقواعد تجريبية لواجهة برمجة التطبيقات: أنشِئ مصدر بيانات أساسي لواجهة برمجة التطبيقات واضبط أي قواعد سمات مطلوبة أو عمليات دمج للخلاصات التكميلية.
  3. اختبار الاستحواذ على الملكية ومواءمة المفاتيح: أرسِل طلبات productInputs.insert للمنتجات النموذجية وتأكَّد من أنّ مصدر بيانات واجهة برمجة التطبيقات يستحوذ على ملكية السلع الحالية بدون إنشاء منتجات متكرّرة.
  4. التحقّق من التعديلات وعمليات الحذف: يمكنك اختبار التعديلات الجزئية باستخدام productInputs.patch وعمليات الإزالة باستخدام productInputs.delete، وفحص الموارد الناتجة باستخدام products.get.

2. إنشاء مصادر بيانات واجهة برمجة التطبيقات للإنتاج

قبل إرسال البيانات، أنشئ مصدر بيانات أساسي من نوع API في حسابك.

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

لإنشاء مصدر بيانات يقبل عمليات الإرسال من واجهة برمجة التطبيقات، أرسِل طلب POST إلى نقطة النهاية dataSources. لمزيد من التفاصيل، يُرجى الاطّلاع على المقالة إنشاء مصدر بيانات أساسي للمنتجات.

3- نقل قواعد السمات المخصّصة

ترتبط قواعد السمات المخصّصة بمصادر بيانات معيّنة ولا يتم نقلها تلقائيًا من مصدر بيانات الملف إلى مصدر بيانات واجهة برمجة التطبيقات الجديد.

تعتمد طريقة نقل قواعد السمات على الغرض منها:

  • الدمج من مصادر متعددة والخلاصات التكميلية التابعة لجهات خارجية: إذا كنت تدمج بيانات واجهة برمجة التطبيقات الأساسية مع مصادر بيانات تكميلية خارجية (مثل ملفات المورّدين التابعين لجهات خارجية أو جداول بيانات المستودع أو خلاصات العروض الترويجية)، عليك إعادة إنشاء قواعد السمات في واجهة مستخدم Merchant Center وإرفاقها بمصدر بيانات واجهة برمجة التطبيقات الجديد. لا يمكن أن تحلّ المعالجة المُسبقة من جهة العميل محلّ القواعد التي تدمج البيانات من مصادر مستقلة متعددة.
  • تحويلات البيانات من مصدر واحد: لتنظيف البيانات من مصدر واحد أو القيم التلقائية أو تنسيق السلسلة في بيانات الكتالوج الأساسية، اختَر بين:
    • عمليات التحويل في الخلفية (يُنصح بها): يمكنك تطبيق عمليات التحويل في نظامك الخاص قبل طلب البيانات من واجهة برمجة التطبيقات. يمنحك ذلك تحكّمًا آليًا أكبر واختبارًا أسهل وتصحيح أخطاء مبسطًا.
    • قواعد السمات في Merchant Center: أعِد إنشاء قواعد التحويل لمصدر بيانات واجهة برمجة التطبيقات الجديد في واجهة مستخدم Merchant Center إذا أردت أن يواصل Merchant Center إدارتها تلقائيًا.

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

فعِّل عملية دمج واجهة برمجة التطبيقات في الإصدار العلني لبدء إدراج المنتجات وتعديلها وحذفها في مصدر البيانات الأساسي الجديد لواجهة برمجة التطبيقات:

  • إدراج المنتجات وتعديلها (الاستحواذ على الملكية): أرسِل طلبَي productInputs.insert و productInputs.patch من عملية الدمج. عند إدراج منتج باستخدام واجهة برمجة التطبيقات بالمفتاح نفسه (offerId وcontentLanguage وfeedLabel) لمنتج حالي في خلاصة ملفات، يحصل مصدر بيانات واجهة برمجة التطبيقات على ملكية هذا المنتج ويحتفظ بسجلّ عرضه. لمزيد من الإرشادات، يُرجى الاطّلاع على المقالتَين إدراج منتج وإضافة المنتجات وإدارتها.

  • حذف المنتجات التي تم إيقافها نهائيًا: اضبط عملية الدمج لاستدعاء productInputs.delete بشكل صريح كلما تمت إزالة منتج من الكتالوج.

  • النشر التدريجي: بالنسبة إلى الكتالوجات الكبيرة، فعِّل عملية الدمج في حساب فرعي واحد على Merchant Center أو مصدر بيانات واحد في كل مرة.

  • ضبط التزامن: في حال إرسال العديد من الطلبات، اضبط برنامج العميل للتعامل مع الطلبات المتزامنة وإدارة الاتصالات المتعددة. يُرجى الاطّلاع على دليل إعادة هيكلة الرمز البرمجي للطلبات المتزامنة.

5- إيقاف تعديلات مصدر بيانات الملف مؤقتًا

بعد تفعيل عملية دمج واجهة برمجة التطبيقات، أوقِف تعديلات الملفات قبل عملية تشغيل الملف التالية المجدوَلة كي لا يستبدل مصدر بيانات الملف تعديلات واجهة برمجة التطبيقات:

  1. توقَّف عن تحميل ملفات جديدة إلى موقع SFTP/FTP أو Google Cloud Storage أو "جداول بيانات Google".
  2. في واجهة مستخدم Merchant Center، انتقِل إلى مصدر بيانات الملف وأوقِف الحصول على الخلاصات وفق جدول زمني محدّد مؤقتًا.
  3. تبقى المنتجات الحالية التي يملكها مصدر بيانات الملفات معروضة لمدة تصل إلى 30 يومًا إلى أن يتم إدراجها من خلال عملية تكامل واجهة برمجة التطبيقات.

6. الانتظار حتى تكتمل عملية نقل البيانات والتحقّق منها

انتظِر حتى يتم نقل جميع المنتجات النشطة من مصدر بيانات الملف إلى مصدر بيانات واجهة برمجة التطبيقات. على الرغم من أنّ التعديلات المتزايدة تنقل المنتجات عند تغييرها، فإنّ إجراء مزامنة كاملة للكتالوج من خلال عملية الدمج العادية يسرّع عملية نقل الكتالوج بأكمله (يُرجى الاطّلاع على استراتيجية المزامنة والحصص).

خلال هذه المرحلة:

  1. في واجهة مستخدم Merchant Center، راقِب عدد السلع. انتظِر حتى ينخفض عدد مصادر بيانات الملفات إلى 0 ويتطابق عدد مصادر بيانات واجهة برمجة التطبيقات مع الكتالوج النشط.
  2. استخدِم products.get للتحقّق من دمج السمات وقواعد السمات المخصّصة على النحو المتوقّع.
  3. استخدِم أداة بيانات تشخيص واجهة برمجة التطبيقات في واجهة مستخدم Merchant Center لتتبُّع معدّلات الأخطاء وأداء واجهة برمجة التطبيقات.

7. إيقاف مصدر بيانات الملفات

بعد اكتمال عملية النقل ووصول عدد عناصر خلاصة الملفات إلى 0:

  1. تأكَّد من أنّ التعديلات تظهر في الوقت الفعلي.
  2. احذف مصدر بيانات الملف القديم في واجهة مستخدم Merchant Center لمنع التحديثات غير المقصودة المستندة إلى الملفات من استبدال بيانات واجهة برمجة التطبيقات.
السابق
Migrate Local Inventory Ads settings