ملفات الخلاصة المجزّأة

استنادًا إلى مستودعك، قد يكون من الضروري تقسيم الخلاصات إلى ملفات متعددة (أو تقسيمها).

حالات استخدام التقسيم

  • حجم الخلاصة أكبر من 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 تم ضبطه على معرّف فريد مماثل في جميع أقسام الخلاصة نفسها ولكنّه يختلف عن قيمة الخلاصات الأخرى. يجب أن يكون nonce عددًا صحيحًا موجبًا (uint64).
  • generation_timestamp هو الطابع الزمني بتنسيق يونكس و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. يمكنك تخصيص أرقام شرائح فريدة لكل مثيل (مثل الولايات المتحدة = N، والاتحاد الأوروبي = 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"
        }
      ]
    }
  ]
}