ملفات الخلاصة المشترَكة (الإصدار القديم)

وقد يكون من الضروري تقسيم الخلاصات إلى عدة ملفات حسب المستودع الإعلاني.

متى أستخدم عملية التقسيم إلى أجزاء؟

  • يتجاوز حجم الخلاصة 200 ميغابايت لملف واحد (بعد ضغط gzip).

    • مثال: يبلغ حجم خلاصة مدى التوفّر التي تم إنشاؤها 1 غيغابايت. ويجب تقسيم هذا العنصر إلى أكثر من 5 ملفات منفصلة (أو أجزاء).

  • يتم توزيع مستودع الشركاء على الأنظمة و/أو المناطق ما يؤدي إلى صعوبة في تسوية المستودع.

    • مثال: يملك الشريك مستودعًا إعلانيًا في الولايات المتحدة والاتحاد الأوروبي في أنظمة منفصلة. قد يتم إنشاء الخلاصة باستخدام ملفَّين (أو أجزاء)، أحدهما للولايات المتحدة والآخر للاتحاد الأوروبي باستخدام السمة nonce و generation_timestamp نفسها.

قواعد عامة

  • يجب ألا يتجاوز كل جزء 200 ميغابايت لملف واحد (بعد ضغط gzip).
  • ننصح بعدم تجاوز 20 جزءًا لكل خلاصة. وإذا كان لديك مبرر للنشاط التجاري يتطلّب أكثر من هذا المبلغ، يُرجى التواصل مع فريق الدعم للحصول على تعليمات إضافية.
  • يجب إرسال السجلات الفردية (مثلاً عنصر Merchant واحد) في جزء واحد، ولا يمكن تقسيمها على أجزاء متعددة. ولا يجب إرسالها في الجزء الذي يتضمّن السمة shard_number نفسها في الخلاصات المستقبلية.
  • للحصول على أداء أفضل، يجب تقسيم بياناتك بالتساوي على الأجزاء بحيث تكون جميع الملفات المجزأة متشابهة في الحجم.

كيفية تقسيم الخلاصات

بالنسبة إلى كل ملف (أو جزء)، اضبط FeedMetadata على ما يلي:

  • تم ضبط processing_instruction على PROCESS_AS_COMPLETE.
  • تم ضبط shard_number على الجزء الحالي من الخلاصة (بدءًا من 0 إلى total_shards - 1 بدون انقطاعات)
  • تم ضبط total_shards على إجمالي عدد أجزاء الخلاصة (بدءًا من 1).
  • تمّ ضبط السمة nonce على معرّف فريد متطابق في جميع أجزاء الخلاصة نفسها ولكن يختلف عن قيمة الخلاصات الأخرى.
  • وgeneration_timestamp هو الطابع الزمني بتنسيق Unix وEPOCH. ويجب أن يكون العنصر مطابقًا لجميع أجزاء الخلاصة.

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

  • Example: “availability_feed_1574117613_001_of_002.json.gz”

مثال على خلاصة مدى التوفّر المجزأة

الجزء 0

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 0,
    "total_shards": 3,
    "nonce": "111111",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1577275200,
          "merchant_id": "merchant1",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

الجزء 1

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 1,
    "total_shards": 3,
    "nonce": "111111",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1577620800,
          "merchant_id": "merchant2",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

الجزء 2

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 2,
    "total_shards": 3,
    "nonce": "111111",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1576670400,
          "merchant_id": "merchant3",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

استخدام عملية التقسيم إلى أجزاء للمستودع الموزع للشريك

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

على سبيل المثال، لنفترض أنّ مستودع الشريك مقسّم إلى منطقتَين (مستودع الولايات المتحدة والاتحاد الأوروبي)، اللتين تتوفران في نظامَين منفصلَين.

يمكن للشريك تقسيم كل خلاصة إلى ملفَين (أو جزأين):

  • خلاصة التجّار: جزء واحد للولايات المتحدة وجزء واحد للاتحاد الأوروبي
  • خلاصة الخدمات: جزء واحد للولايات المتحدة وجزء واحد للاتحاد الأوروبي
  • خلاصة مدى التوفّر: جزء واحد للولايات المتحدة وجزء واحد للاتحاد الأوروبي

اتّبِع الخطوات التالية لضمان معالجة الخلاصات بشكل صحيح:

  1. اختَر جدولاً زمنيًا للتحميل، واضبط كل مثيل من المستودع لاتّباع الجدول الزمني.
  2. عيِّن أرقامًا فريدة للأجزاء لكل مثيل (مثل US = N وEU = N + 1). اضبط total_shards على إجمالي عدد الأجزاء.
  3. وفي كل وقت تحميل مُجدوَل، اختَر generation_timestamp وnonce. في FeedMetadata، اضبط جميع الحالات بحيث تحتوي على القيم نفسها لهذين الحقلين.
    • يجب أن تكون قيمة الحقل generation_timestamp في الماضي أو الحاضر (يُفضَّل أن يكون الطابع الزمني لقاعدة بيانات الشريك لقراءة البيانات).
  4. وبعد تحميل جميع الأجزاء، يجمعها محرّك بحث Google من خلال الترميزَين generation_timestamp وnonce.

سيعالج محرّك بحث Google الخلاصة كخلاصة على الرغم من أنّ كل جزء يمثّل منطقة مختلفة من مستودع الشريك ويمكن تحميله في وقت مختلف من اليوم ما دامت السمة generation_timestamp متطابقة على جميع الأجزاء.

مثال على خلاصة مدى التوفّر المجزّأة حسب المنطقة

الجزء 0 - المستودع الإعلاني في الولايات المتحدة

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 0,
    "total_shards": 2,
    "nonce": "111111",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1577275200,
          "merchant_id": "US_merchant_1",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

الشريحة 1 - المخزون في الاتحاد الأوروبي

{
  "metadata": {
    "processing_instruction": "PROCESS_AS_COMPLETE",
    "shard_number": 1,
    "total_shards": 2,
    "nonce": "111111",
    "generation_timestamp": 1524606581
  },
  "service_availability": [
    {
      "availability": [
        {
          "spots_total": 1,
          "spots_open": 1,
          "duration_sec": 3600,
          "service_id": "1000",
          "start_sec": 1577620800,
          "merchant_id": "EU_merchant_1",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}