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

يقوم `exportMessagesStatistics` بتصدير سجل الرسائل والإحصائيات إلى ملف CSV على الخادم. استخدمه لعمليات السحب الكبيرة أو لكامل الحساب التي لا يمكن لـ [`messages:list`](/ar/developer/api-reference/statistics-api/message-statistics-api/#messageslist) التعامل معها.

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

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

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

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

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

## الطرق

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

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

### export

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

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

##### الترويسات

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

| الاسم | مطلوب | الوصف |
|------------------|----------|---------------------------------------------------------------------------------------------------------|
| `Authorization` | نعم | [رمز API للخادم](/ar/developer/api-reference/api-access-token/#server-api-token). يجب توفيره بالتنسيق التالي: `Authorization: Api <Server Key>`. |

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

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

| الاسم | مطلوب | النوع | الوصف |
|----------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------|
| `type` | نعم | String | يجب أن يكون <code>"TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"</code>. |
| <code>export_messages<wbr/>_v2</code> | نعم | Object | معلمات التصدير، الموضحة أدناه. |
| <code>export_messages<wbr/>_v2.application<wbr/>_code</code> | انظر الملاحظة | String | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code). مطلوب إذا لم يتم تعيين `app_group_code`. |
| <code>export_messages<wbr/>_v2.app<wbr/>_group_code</code> | انظر الملاحظة | String | رمز مجموعة التطبيقات، يقوم بالتصدير عبر كل تطبيق في المجموعة. مطلوب إذا لم يتم تعيين `application_code`. |
| <code>export_messages<wbr/>_v2.search</code> | لا | String | بحث نصي حر في عنوان الرسالة ومحتواها. |
| <code>export_messages<wbr/>_v2.filters</code> | لا | Object | مرشحات الرسائل، الموضحة أدناه. يمكن حذفه لتصدير سجل الحساب بالكامل. |
| <code>export_messages<wbr/>_v2.properties</code> | لا | Array | الأعمدة التي سيتم تضمينها في ملف CSV، الموضحة أدناه. |

يقبل `export_messages_v2.filters`:

| الاسم <div style="width:150px"></div> | النوع | الوصف |
|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `statuses` | Array | حالات الرسائل التي سيتم تضمينها. <details><summary>القيم الممكنة</summary><ul><li><code>"MESSAGE_STATUS_CANCELED"</code></li><li><code>"MESSAGE_STATUS_CREATING"</code></li><li><code>"MESSAGE_STATUS_DONE"</code></li><li><code>"MESSAGE_STATUS_FAIL"</code></li><li><code>"MESSAGE_STATUS_PENDING"</code></li><li><code>"MESSAGE_STATUS_PROCESSING"</code></li><li><code>"MESSAGE_STATUS_WAITING"</code></li></ul></details> |
| `platforms` | Array | [رموز المنصات](/ar/developer/api-reference/messages-api/api-prerequisites/#platforms) (رقمية، مثل `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 | مصدر الرسالة. <details><summary>القيم الممكنة</summary><ul><li><code>"AB_TEST"</code></li><li><code>"API"</code></li><li><code>"AUTO_PUSH"</code></li><li><code>"CP"</code></li><li><code>"CSV"</code></li><li><code>"CUSTOMER_JOURNEY"</code></li><li><code>"EMAIL_API"</code></li><li><code>"EMAIL_CP"</code></li><li><code>"GEO_ZONE"</code></li><li><code>"PUSH_ON_EVENT"</code></li><li><code>"RSS"</code></li><li><code>"SYSTEM"</code></li></ul></details> |
| `segments` | Array | [رموز المرشحات](/ar/developer/api-reference/api-identifiers/#segment--filter-code) التي أُرسلت إليها الرسالة. |
| `campaigns` | Array | [رموز الحملات](/ar/developer/api-reference/api-identifiers/#campaign-code). على عكس `messages:list`، يأخذ هذا قائمة، وليس رمزًا واحدًا. |
| `message_id` | String (uint64) | معرّف رسالة رقمي واحد، موضوع بين علامتي اقتباس. على عكس `messages:list`، يأخذ التصدير معرّفًا واحدًا، وليس مصفوفة. |
| `message_code` | String | [رمز رسالة](/ar/developer/api-reference/api-identifiers/#message-code) واحد. |

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

<details>
<summary>القيم الممكنة</summary>

- `"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"`

</details>

<Aside type="caution" title="الخاصية properties ليست مجرد مرشح">
الخاصية غير المدرجة في `properties` لا تظهر في الملف على الإطلاق، بما في ذلك الأعمدة الأساسية (المعرّف، تاريخ الإرسال، المحتوى، الحالة). ترك `properties` فارغًا ينتج ملف CSV بدون أعمدة. قم بإدراج كل عمود يجب أن يحتويه التصدير، وليس فقط المقاييس التي تريد إضافتها فوق مجموعة افتراضية.
</Aside>

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

```json
{
  "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"
    ]
  }
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "uid": "177458"
}
```
</TabItem>
<TabItem label="401: رمز وصول API غير صحيح">
```json
{
  "error": "account not found"
}
```
</TabItem>
</Tabs>

### status

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

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

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

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

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

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

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "status": "STATUS_SUCCESS",
  "progress": 1
}
```
</TabItem>
</Tabs>

`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"`. |

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

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}
```
</TabItem>
</Tabs>

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

### lastTasks

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

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

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

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

| الاسم | مطلوب | النوع | الوصف |
|------------------|----------|---------|---------------------------------------------------------------------------------------|
| `application` | لا | String | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code). يمكن حذفه لسرد المهام عبر جميع التطبيقات التي يمكن للرمز الوصول إليها. |
| `types` | لا | Array | قصر النتائج على أنواع مهام محددة. استخدم <code>["TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"]</code> لرؤية صادرات الرسائل فقط. |
| `campaign` | لا | String | التصفية حسب [رمز الحملة](/ar/developer/api-reference/api-identifiers/#campaign-code). |
| `message_id` | لا | String (uint64) | التصفية حسب معرّف رسالة رقمي واحد، موضوع بين علامتي اقتباس. |
| `message_code` | لا | String | التصفية حسب [رمز رسالة](/ar/developer/api-reference/api-identifiers/#message-code) واحد. |
| `limit` | لا | Integer | الحد الأقصى لعدد المهام التي سيتم إرجاعها. |
| `timestamp_from` | لا | String | إرجاع المهام التي تم إنشاؤها بعد هذا الطابع الزمني فقط (RFC 3339). |

<Aside type="note">
يتم الاحتفاظ بالمهام لمدة 30 يومًا بغض النظر عما إذا كان ملفها قد تم حذفه بالفعل بعد فترة الاحتفاظ بالملف البالغة 7 أيام. لا يزال بإمكان `lastTasks` إظهار مهمة لم يعد `result` الخاص بها يؤدي إلى ملف قابل للتنزيل.
</Aside>

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

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

<Tabs>
<TabItem label="200: OK">
```json
{
  "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"
      }
    }
  ]
}
```
</TabItem>
</Tabs>

### delete

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

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

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

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

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

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

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{}
```
</TabItem>
</Tabs>

### تنزيل

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

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

##### الترويسات

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

| الاسم | مطلوب | الوصف |
|------------------|----------|-----------------------------------------------------------------------------------------------------|
| `Authorization`| نعم | [رمز API للخادم](/ar/developer/api-reference/api-access-token/#server-api-token)، بنفس تنسيق طرق `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 عن العمل.