تصدير إحصائيات الرسائل بشكل غير متزامن

يقوم exportMessagesStatistics بتصدير سجل الرسائل والإحصائيات إلى ملف CSV على الخادم. استخدمه لعمليات السحب الكبيرة أو لكامل الحساب التي لا يمكن لـ messages:list التعامل معها.

متى تستخدم التصدير بدلاً من messages:list

استخدم messages:list لعمليات البحث المباشرة والمقسمة إلى صفحات لفترة محدودة. استخدم exportMessagesStatistics عندما تتجاوز النتيجة حد ترقيم الصفحات العميق لـ messages:list (page × per_page > 100000)، أو عندما يكون الهدف هو ملف واحد قابل للتنزيل بدلاً من JSON مقسم إلى صفحات. لا يوجد حد للتصدير على date_range أو عدد الصفوف، لأنه يقوم ببث النتيجة إلى ملف على القرص بدلاً من الاحتفاظ بها في استجابة واحدة.

كيف يعمل تدفق التصدير

1. استدعِ export بنفس المرشحات المستخدمة في messages:list. تعيد الاستجابة معرّف المهمة uid على الفور، قبل إنشاء الملف.
2. استعلم بشكل دوري عن status باستخدام ذلك الـ uid حتى يبلغ عن STATUS_SUCCESS (أو STATUS_FAILED).
3. استدعِ result بنفس الـ uid للحصول على اسم الملف الذي تم إنشاؤه.
4. نزّل الملف بالاسم.

استخدم lastTasks للبحث عن مهام التصدير الأخيرة لتطبيق ما، و delete لإلغاء مهمة أو إزالة ملفها مبكرًا.

الطرق

تتكون دورة حياة التصدير من خمس طرق، بالإضافة إلى نقطة نهاية تنزيل عادية:

الطريقة	الوصف
exportMessagesStatistics/export	يضع تصديرًا في قائمة الانتظار ويعيد معرّف المهمة uid.
exportMessagesStatistics/status	يتحقق من تقدم المهمة.
exportMessagesStatistics/result	يعيد اسم الملف الذي تم إنشاؤه بمجرد انتهاء المهمة.
exportMessagesStatistics/lastTasks	يسرد مهام التصدير الأخيرة لتطبيق ما.
exportMessagesStatistics/delete	يلغي مهمة أو يزيل ملفها قبل انتهاء فترة الاحتفاظ.
تنزيل	يقوم بتنزيل ملف CSV الذي تم إنشاؤه بالاسم.

export

يضع تصدير سجل الرسائل في قائمة الانتظار ويعيد معرّف المهمة على الفور.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

الترويسات

يحتاج الطلب إلى رمز API للخادم:

الاسم	مطلوب	الوصف
Authorization	نعم	رمز API للخادم. يجب توفيره بالتنسيق التالي: Authorization: Api <Server Key>.

معلمات جسم الطلب

يقبل جسم الطلب الحقول التالية:

الاسم	مطلوب	النوع	الوصف
type	نعم	String	يجب أن يكون “TASK_TYPE_EXPORT_MESSAGES_V2”.
export_messages_v2	نعم	Object	معلمات التصدير، الموضحة أدناه.
export_messages_v2.application_code	انظر الملاحظة	String	رمز تطبيق Pushwoosh. مطلوب إذا لم يتم تعيين app_group_code.
export_messages_v2.app_group_code	انظر الملاحظة	String	رمز مجموعة التطبيقات، يقوم بالتصدير عبر كل تطبيق في المجموعة. مطلوب إذا لم يتم تعيين application_code.
export_messages_v2.search	لا	String	بحث نصي حر في عنوان الرسالة ومحتواها.
export_messages_v2.filters	لا	Object	مرشحات الرسائل، الموضحة أدناه. يمكن حذفه لتصدير سجل الحساب بالكامل.
export_messages_v2.properties	لا	Array	الأعمدة التي سيتم تضمينها في ملف CSV، الموضحة أدناه.

يقبل export_messages_v2.filters:

الاسم	النوع	الوصف
statuses	Array	حالات الرسائل التي سيتم تضمينها. القيم الممكنة ”MESSAGE_STATUS_CANCELED" "MESSAGE_STATUS_CREATING" "MESSAGE_STATUS_DONE" "MESSAGE_STATUS_FAIL" "MESSAGE_STATUS_PENDING" "MESSAGE_STATUS_PROCESSING" "MESSAGE_STATUS_WAITING”
platforms	Array	رموز المنصات (رقمية، مثل 1 لـ iOS)، وليست سلاسل أسماء المنصات المستخدمة بواسطة messages:list.
sent_date	Object	فترة إعداد التقارير التي تمت تصفيتها حسب تاريخ الإرسال: {"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}.
created_date	Object	فترة إعداد التقارير التي تمت تصفيتها حسب تاريخ إنشاء الرسالة، بنفس تنسيق sent_date.
created_via	Array	مصدر الرسالة. القيم الممكنة ”AB_TEST" "API" "AUTO_PUSH" "CP" "CSV" "CUSTOMER_JOURNEY" "EMAIL_API" "EMAIL_CP" "GEO_ZONE" "PUSH_ON_EVENT" "RSS" "SYSTEM”
segments	Array	رموز المرشحات التي أُرسلت إليها الرسالة.
campaigns	Array	رموز الحملات. على عكس messages:list، يأخذ هذا قائمة، وليس رمزًا واحدًا.
message_id	String (uint64)	معرّف رسالة رقمي واحد، موضوع بين علامتي اقتباس. على عكس messages:list، يأخذ التصدير معرّفًا واحدًا، وليس مصفوفة.
message_code	String	رمز رسالة واحد.

يحدد export_messages_v2.properties الأعمدة التي يحتوي عليها ملف CSV.

القيم الممكنة

• "EXPORT_MESSAGE_PROPERTY_ID"
• "EXPORT_MESSAGE_PROPERTY_TIMESTAMP"
• "EXPORT_MESSAGE_PROPERTY_CONTENT"
• "EXPORT_MESSAGE_PROPERTY_TITLE"
• "EXPORT_MESSAGE_PROPERTY_APPLICATIONS"
• "EXPORT_MESSAGE_PROPERTY_STATUS"
• "EXPORT_MESSAGE_PROPERTY_PLATFORMS"
• "EXPORT_MESSAGE_PROPERTY_SOURCE"
• "EXPORT_MESSAGE_PROPERTY_FILTER"
• "EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"
• "EXPORT_MESSAGE_PROPERTY_SENT"
• "EXPORT_MESSAGE_PROPERTY_OPENED"
• "EXPORT_MESSAGE_PROPERTY_ERRORS"
• "EXPORT_MESSAGE_PROPERTY_RECIPIENTS"
• "EXPORT_MESSAGE_PROPERTY_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"

الخاصية properties ليست مجرد مرشح

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

مثال على الطلب

{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}

200: OK

{
  "uid": "177458"
}

401: رمز وصول API غير صحيح

{
  "error": "account not found"
}

status

يعيد تقدم مهمة التصدير.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status

معلمات جسم الطلب

مرر معرّف المهمة الذي أعاده export:

الاسم	مطلوب	النوع	الوصف
uid	نعم	String (int64)	معرّف المهمة من استجابة export، على سبيل المثال "177458".

مثال على الطلب

{
  "uid": "177458"
}

200: OK

{
  "status": "STATUS_SUCCESS",
  "progress": 1
}

status هي واحدة من "STATUS_PENDING"، "STATUS_SUCCESS"، أو "STATUS_FAILED". progress هو كسر بين 0 و 1؛ استعلم عن status بشكل دوري حتى يصل إلى "STATUS_SUCCESS" قبل استدعاء result.

result

يعيد اسم الملف الذي تم إنشاؤه بمجرد اكتمال المهمة.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result

معلمات جسم الطلب

مرر نفس معرّف المهمة الذي أعاده export:

الاسم	مطلوب	النوع	الوصف
uid	نعم	String (int64)	معرّف المهمة من استجابة export، على سبيل المثال "177458".

مثال على الطلب

{
  "uid": "177458"
}

200: OK

{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

استدعاء result قبل أن يبلغ status عن "STATUS_SUCCESS" يعيد نتيجة فارغة. مرر قيمة file كما هي إلى نقطة نهاية التنزيل.

lastTasks

يسرد مهام التصدير الأخيرة لتطبيق ما، من الأحدث إلى الأقدم.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks

معلمات جسم الطلب

كل معلمة هي مرشح اختياري؛ احذفها جميعًا لسرد كل مهمة يمكن للرمز الوصول إليها:

الاسم	مطلوب	النوع	الوصف
application	لا	String	رمز تطبيق Pushwoosh. يمكن حذفه لسرد المهام عبر جميع التطبيقات التي يمكن للرمز الوصول إليها.
types	لا	Array	قصر النتائج على أنواع مهام محددة. استخدم [“TASK_TYPE_EXPORT_MESSAGES_V2”] لرؤية صادرات الرسائل فقط.
campaign	لا	String	التصفية حسب رمز الحملة.
message_id	لا	String (uint64)	التصفية حسب معرّف رسالة رقمي واحد، موضوع بين علامتي اقتباس.
message_code	لا	String	التصفية حسب رمز رسالة واحد.
limit	لا	Integer	الحد الأقصى لعدد المهام التي سيتم إرجاعها.
timestamp_from	لا	String	إرجاع المهام التي تم إنشاؤها بعد هذا الطابع الزمني فقط (RFC 3339).

ملاحظة

يتم الاحتفاظ بالمهام لمدة 30 يومًا بغض النظر عما إذا كان ملفها قد تم حذفه بالفعل بعد فترة الاحتفاظ بالملف البالغة 7 أيام. لا يزال بإمكان lastTasks إظهار مهمة لم يعد result الخاص بها يؤدي إلى ملف قابل للتنزيل.

مثال على الطلب

{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}

200: OK

{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}

delete

يحذف مهمة وملفها قبل انتهاء فترة الاحتفاظ البالغة 7 أيام.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete

معلمات جسم الطلب

مرر معرّف المهمة الذي أعاده export:

الاسم	مطلوب	النوع	الوصف
uid	نعم	String (int64)	معرّف المهمة من استجابة export، على سبيل المثال "177458".

مثال على الطلب

{
  "uid": "177458"
}

200: OK

{}

تنزيل

يقوم بتنزيل ملف CSV الذي تم إنشاؤه بواسطة result، بالاسم.

GET https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>

الترويسات

قم بالمصادقة بنفس طريقة الطرق الأخرى، أو اعتمد على جلسة لوحة تحكم نشطة:

الاسم	مطلوب	الوصف
Authorization	نعم	رمز API للخادم، بنفس تنسيق طرق exportMessagesStatistics الأخرى: Authorization: Api <Server Key> (مخطط Api غير حساس لحالة الأحرف). الطلب الذي لا يحتوي على ترويسة Authorization ولا توجد جلسة لوحة تحكم مسجلة الدخول يحصل على 401 Unauthorized.

استبدل <file> بقيمة file الدقيقة من استجابة result، على سبيل المثال:

https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv

الملف هو ملف CSV يحتوي على الأعمدة المحددة في properties. يظل متاحًا لمدة 7 أيام بعد انتهاء التصدير، ثم تقوم مهمة التنظيف بإزالته ويتوقف عنوان URL عن العمل.