# واجهة برمجة تطبيقات التجزئة (الفلاتر)

## createFilter

`POST` `https://api.pushwoosh.com/json/1.3/createFilter`

ينشئ فلترًا جديدًا.

**نص الطلب**

| الاسم | مطلوب | النوع | الوصف |
| ---------------------------------------------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| auth\* | نعم | string | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| name\* | نعم | string | [اسم الفلتر](/ar/developer/api-reference/api-identifiers/#segment--filter-name). |
| filter\_expression\* | نعم | string | <p>تعبير تم إنشاؤه وفقًا لقواعد <a href="/developer/api-reference/segmentation-filters-api/segmentation-language/">لغة التجزئة</a>. <br /><strong>مثال:</strong> <code>T("City", eq, "Madrid")</code> لتجزئة المستخدمين الذين مدينتهم هي مدريد.</p> |
| application | لا | string | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code). هذه المعلمة قابلة للاستخدام فقط مع الإعداد عالي السرعة؛ وإلا يجب حذفها. |
| expiration\_date | لا | string | انتهاء صلاحية الفلتر. سيتم حذف الفلتر تلقائيًا في التاريخ المحدد، ما لم يتم استخدامه في إعداد مسبق (Preset) أو موجز RSS. |

**200**
```json
{
  "status_code": 200, 
  "status_message": "OK", 
  "response": {
    "name": "filter name"
  }
}
```



**مثال**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// إنشاء فلاتر للمناطق الزمنية
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}
```


## listFilters

`POST` `https://api.pushwoosh.com/json/1.3/listFilters`

يعرض قائمة بالشرائح (الفلاتر) المتاحة مع شروطها.

**نص الطلب**

| الاسم | مطلوب | النوع | الوصف |
| --------------------------------------------- | -------- | ------ | ---------------------------------------------- |
| auth\* | نعم | string | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| application\* | نعم | string | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |


**200**
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

```


**مثال**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}
```

## deleteFilter

`POST` `https://api.pushwoosh.com/json/1.3/deleteFilter`

يحذف فلترًا موجودًا.

**نص الطلب**

| الاسم | النوع | الوصف |
| -------------------------------------- | ------ | ---------------------------------------------- |
| auth\* | string | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| name\* | string | [اسم الفلتر](/ar/developer/api-reference/api-identifiers/#segment--filter-name). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>



```json title="مثال"
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
    "name": "filter name"
  }
}
```

## exportSegment

`POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment`

طلب مجدول. يُصدّر قائمة المشتركين الذين يندرجون تحت شروط الفلتر المحددة.

**نص الطلب**
| الاسم <div style="width:100px"></div> | مطلوب <div style="width:100px"></div> | النوع | الوصف |
|----------------------------|------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| auth\* | نعم | string | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| filterExpression\* | نعم | string | شروط الفلتر |
| exportData | لا | array | البيانات المراد تصديرها. القيم الممكنة: `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. تضمين `"location"` يضيف عمودي `Latitude` و `Longitude` إلى ملف CSV المصدر. إذا تم حذف `exportData`، يتم تضمين `Latitude` و `Longitude` في التصدير بشكل افتراضي. |
| filterCode | لا | string | [رمز فلتر](/ar/developer/api-reference/api-identifiers/#segment--filter-code) مُعد مسبقًا، يمكن استخدامه بدلاً من `filterExpression`. يمكن الحصول عليه من واجهة برمجة التطبيقات `/listFilters` أو من شريط عنوان متصفحك عند عرض الفلتر في لوحة التحكم. |
| applicationCode | مطلوب إذا كنت تستخدم `filterExpression` أو `filterCode`. | string | [رمز تطبيق Pushwoosh](/ar/developer/api-reference/api-identifiers/#application-code) |
| generateExport | لا | boolean | بشكل افتراضي، يتم تعيينه على `true`، وتحتوي الاستجابة على رابط لتنزيل الملف. إذا كان `false`، فسيتم إرسال عدد الأجهزة فقط في الاستجابة. |
| format | لا | string | يحدد تنسيق الملف المصدر: "csv" أو "json\_each\_line". إذا تم حذفه، يتم إنشاء ملف CSV. |
| tagsList | لا | array | يحدد [الوسوم (tags)](/ar/developer/api-reference/api-identifiers/#tag) المراد تصديرها. للحصول على وسوم محددة فقط، يجب أن تحتوي مصفوفة "exportData" على القيمة "tags". |
| includeWithoutTokens | لا | boolean | اضبطه على `true` لتضمين المستخدمين الذين ليس لديهم رموز دفع (push tokens) في الملف المصدر. القيمة الافتراضية هي `false`. |


<Tabs>
<TabItem label="200 ناجح">
```json
{
  "task_id": "177458"
}
```
</TabItem>
</Tabs>



```json title="مثال"
{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // مطلوب. رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // شروط الفلتر، ارجع إلى دليل لغة التجزئة للصيغة
  "filterCode": "12345-67890",                              // رمز فلتر مُعد مسبقًا، يمكن استخدامه بدلاً من filterExpression
  "applicationCode": "00000-AAAAA",                         // مطلوب إذا كنت تستخدم `filterExpression` أو `filterCode`. رمز تطبيق Pushwoosh. يمكن الحصول عليه من طلب واجهة برمجة التطبيقات /listFilters أو شريط عنوان متصفحك أثناء عرض الفلتر في لوحة التحكم.
  "generateExport": true,                                   // إذا كان false، فسيتم إرسال عدد الأجهزة فقط في الاستجابة؛ بشكل افتراضي، تحتوي الاستجابة على رابط لتنزيل ملف CSV
  "format": "json_each_line",                               // تنسيق الملف لتقديم البيانات فيه: "csv" – يتم تنزيل ملف .csv؛ "json" – ملف JSON مع جميع الأجهزة المصدرة؛ أو "json_each_line" – سطر JSON لكل جهاز. إذا لم يتم تحديده، فإن CSV هو التنسيق الافتراضي.
  "exportData": ["hwids", "tags"],                          // اختياري. البيانات المراد تصديرها. القيم الممكنة: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys"
  "tagsList": ["Name", "Level"],                            // اختياري. يحدد الوسوم المراد تصديرها. للحصول على الوسوم المحددة فقط، يجب إرسال القيمة "tags" ضمن مصفوفة "exportData" أو أن تكون "exportData" فارغة.
  "includeWithoutTokens": true                              // اختياري. اضبطه على true لتضمين المستخدمين الذين ليس لديهم رموز دفع في الملف المصدر. القيمة الافتراضية هي false.
}
```

<Aside type="note">
يرجى العثور على مرجع لغة التجزئة لكتابة تعبيرات الفلتر [هنا](/ar/developer/api-reference/segmentation-filters-api/segmentation-language/).
</Aside>

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

```json
{
  "auth": "yxoPUlwqm…………pIyEX4H",            // رمز الوصول إلى واجهة برمجة التطبيقات من لوحة تحكم Pushwoosh
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // تعبير الفلتر يشير إلى شريحة التطبيق
  "applicationCode": "AAAAA-BBBBB"           // رمز تطبيق Pushwoosh المطلوب
}
```

<Aside type="caution">
في الاستجابة، ستحصل على **`task_id`** للحصول على الملف الناتج. بعد ذلك، قم باستدعاء [/exportSegment/result](./#exportsegment-results) مع `task_id` هذا في نص الطلب لاسترداد الملف الناتج.
</Aside>

## نتائج exportSegment

`POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment/result`

**يسترد الرابط إلى ملف CSV الذي يحتوي على نتائج /exportSegment.**

**نص الطلب**

| الاسم | النوع | الوصف |
| ------------------------------------------ | ------ | -------------------------------------------------------- |
| auth\* | String | [رمز الوصول إلى واجهة برمجة التطبيقات (API access token)](/ar/developer/api-reference/api-identifiers/#api-access-token) من لوحة تحكم Pushwoosh. |
| task\_id\* | String | المعرف الذي تم استلامه في استجابة `/exportSegment` الخاصة بك. |

<Tabs>
<TabItem label="200: OK">
```json
{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}
```
</TabItem>
</Tabs>

مرّر "**task\_id**" الذي تم استلامه في استجابة `/exportSegment` الخاصة بك في نص طلب `/exportSegment/result`.

في استجابة `/exportSegment/result`، ستتلقى المعلمة "filename". اتبع الرابط الموجود في قيمة تلك المعلمة لتنزيل أرشيف ZIP تلقائيًا.
فك ضغط الأرشيف لاسترداد ملف CSV أو JSON (اعتمادًا على "format" المحدد في طلبك) الذي يحتوي على بيانات الأجهزة.

بدءًا من 3 أبريل 2025، يلزم الحصول على إذن لتنزيل الملف:

- إذا كنت تقوم بالتنزيل عبر **متصفح**، فما عليك سوى تسجيل الدخول إلى **لوحة تحكم Pushwoosh** للوصول.
- إذا كنت تقوم بالتنزيل عبر **برنامج خادم**، فقم بتضمين الرأس التالي في طلبك:
`Authorization: Token YOUR_API_TOKEN`

إذا قمت بتحديد "exportData" في طلب `/exportSegment` الخاص بك، فسيحتوي الملف الذي تم تنزيله على البيانات المطلوبة فقط. بشكل افتراضي، يحتوي الملف على بيانات المستخدم التالية:

| **الحقل** | الوصف | مثال على القيمة |
| ------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------ |
| Hwid | [معرف الجهاز (Hardware ID)](/ar/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 |
| User ID | [معرف المستخدم (User ID)](/ar/developer/api-reference/api-identifiers/#user-id) الذي يربط جهازًا بمستخدم معين. إذا لم يتم تعيين معرف مستخدم، يتم استخدام HWID. | user8192 |
| Push Token | معرف فريد يتم تعيينه لجهاز بواسطة بوابات المراسلة السحابية. [اعرف المزيد](/ar/developer/api-reference/api-identifiers/#push-token) | eeeb2fd7....0fc3547 |
| Type | نوع المنصة (عدد صحيح). | 1 |
| Type (humanized) | نوع المنصة (نص). | iOS |
| Age | قيمة وسم العمر الافتراضي. | 29 |
| ApplicationVersion | قيمة وسم إصدار التطبيق الافتراضي. | 1.12.0.0 |
| City | قيمة وسم المدينة الافتراضي. | us, boston |
| TagName | قيمة وسم تم إنشاؤه في حسابك. | TagValue |