انتقل إلى المحتوى
أدلة المستخدم الدعم طلب عرض توضيحي تسجيل الدخول
Pushwoosh.com

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

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

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

Anchor link to

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

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

Anchor link to
  1. استدعاء export بنفس المرشحات مثل messages:list. تعيد الاستجابة معرف المهمة uid على الفور، قبل إنشاء الملف.
  2. استطلاع status باستخدام هذا uid حتى يبلغ عن STATUS_SUCCESS (أو STATUS_FAILED).
  3. استدعاء result بنفس uid للحصول على file الذي تم إنشاؤه و file_url جاهز للاستخدام.
  4. تنزيل الملف. استخدم file_url كما هو، أو انظر result لبناء عنوان URL من file إذا عاد فارغًا.

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

الطرق

Anchor link to

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

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

export

Anchor link to

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

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

الترويسات
Anchor link to

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

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

يقبل نص الطلب الحقول التالية:

الاسممطلوبالنوعالوصف
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 يقبل:

الاسم
النوعالوصف
statusesArrayحالات الرسائل التي سيتم تضمينها.
القيم الممكنة
  • ”MESSAGE_STATUS_CANCELED"
  • "MESSAGE_STATUS_CREATING"
  • "MESSAGE_STATUS_DONE"
  • "MESSAGE_STATUS_FAIL"
  • "MESSAGE_STATUS_PENDING"
  • "MESSAGE_STATUS_PROCESSING"
  • "MESSAGE_STATUS_WAITING”
platformsArrayرموز المنصات (رقمية، على سبيل المثال 1 لـ iOS)، وليست سلاسل أسماء المنصات المستخدمة بواسطة messages:list.
sent_dateObjectفترة التقرير المفلترة حسب تاريخ الإرسال: {"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}.
created_dateObjectفترة التقرير المفلترة حسب تاريخ إنشاء الرسالة، بنفس تنسيق sent_date.
created_viaArrayمصدر الرسالة.
القيم الممكنة
  • ”AB_TEST"
  • "API"
  • "AUTO_PUSH"
  • "CP"
  • "CSV"
  • "CUSTOMER_JOURNEY"
  • "EMAIL_API"
  • "EMAIL_CP"
  • "GEO_ZONE"
  • "PUSH_ON_EVENT"
  • "RSS"
  • "SYSTEM”
segmentsArrayرموز المرشحات التي أرسلت إليها الرسالة.
campaignsArrayرموز الحملات. على عكس messages:list، يأخذ هذا قائمة، وليس رمزًا واحدًا.
message_idString (uint64)معرف رسالة رقمي واحد، بين علامتي اقتباس. على عكس messages:list، يأخذ التصدير معرفًا واحدًا، وليس مصفوفة.
message_codeStringرمز رسالة واحد.

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"
مثال على الطلب
Anchor link to
{
  "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"
    ]
  }
}
{
  "uid": "177458"
}

status

Anchor link to

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

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

معلمات نص الطلب
Anchor link to

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

الاسممطلوبالنوعالوصف
uidنعمString (int64)معرف المهمة من استجابة export، على سبيل المثال "177458".
مثال على الطلب
Anchor link to
{
  "uid": "177458"
}
{
  "status": "STATUS_SUCCESS",
  "progress": 1
}

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

result

Anchor link to

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

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

معلمات نص الطلب
Anchor link to

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

الاسممطلوبالنوعالوصف
uidنعمString (int64)معرف المهمة من استجابة export، على سبيل المثال "177458".
مثال على الطلب
Anchor link to
{
  "uid": "177458"
}
{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

استدعاء result قبل أن يبلغ status عن "STATUS_SUCCESS" يعيد نتيجة فارغة. file_url هو رابط جاهز للاستخدام إلى نقطة نهاية التنزيل على مركز البيانات الصحيح للحساب — استخدمه كما هو بدلاً من بناء عنوان URL من file بنفسك. يكون file_url فارغًا إذا لم يكن لمركز بيانات الحساب عنوان URL أساسي مكون. في هذه الحالة، يمكنك فقط الرجوع إلى بناء عنوان URL من file إذا كان الحساب على مركز البيانات الافتراضي app.pushwoosh.com — حساب على مركز بيانات آخر أو نطاق whitelabel ليس لديه طريقة لاشتقاق المضيف الصحيح من file وحده.

lastTasks

Anchor link to

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

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

معلمات نص الطلب
Anchor link to

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

الاسممطلوبالنوعالوصف
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).
مثال على الطلب
Anchor link to
{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}
{
  "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",
        "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}

delete

Anchor link to

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

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

معلمات نص الطلب
Anchor link to

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

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

تنزيل

Anchor link to

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

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

الترويسات
Anchor link to

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

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

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

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

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