> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karzoun.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# إجراء: عمليات JSON

> مرجع كامل لإجراء عمليات JSON: ٢٨ عملية تحويل بيانات مجمّعة في سبع مجموعات، مع شرح كل عملية ومتى تستخدمها.

## بطاقة سريعة

|                      |                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------- |
| **الاسم البرمجي**    | `jsonOperations`                                                                          |
| **الفئة في المنتقي** | متقدّم                                                                                    |
| **أين يعيش**         | إجراء واحد داخل [عقدة الإجراء](/ar/help-center/guides/automations/nodes/actions/overview) |
| **عدد العمليات**     | ٢٨ عملية جاهزة                                                                            |

بعد [طلب HTTP](/ar/help-center/guides/automations/nodes/actions/http-request) تحصل على استجابة JSON — أحياناً معقّدة، متداخلة، أو تحتاج تلخيصاً قبل استخدامها. بدل كتابة [دالة JavaScript](/ar/help-center/guides/automations/nodes/actions/js-function) لكل معالجة صغيرة، تختار من قائمة ٢٨ عملية جاهزة. تختار العملية، والنموذج يعرض تلقائياً فقط الحقول التي تخصها (مفتاح البحث، القيمة، الفاصل، الإزاحة والطول...).

<Info>
  **وسائط مطلوبة:** محرر عمليات JSON مفتوحاً بعملية "استخراج بمسار JSON" على استجابة API حقيقية، يظهر فيها الحقل المصدر والمسار والهدف.
  المسار المقترح: `/images/help/automations/action-json-operations.webp`
</Info>

## البنية العامة

كل عملية تحتاج:

1. **مصدر البيانات**: متغيّر JSON من خطوة سابقة (مثال: استجابة طلب HTTP)، أو نص JSON خام تكتبه مباشرة.
2. **إعدادات خاصة بالعملية المختارة** (مفتاح، قيمة، فاصل...).
3. **الهدف**: أين تُحفظ النتيجة — حقل على العميل أو متغيّر مسار.

## المجموعات السبع والعمليات الـ٢٨

### استخراج بمسار

| العملية                           | ماذا تفعل                                                                                                                          |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **استخراج بمسار JSON (JSONPath)** | تسحب قيمة واحدة من أي عمق داخل بنية JSON متداخلة بكتابة مسارها (مثال: `data.orders[0].total`) — الأسرع حين تعرف مكان القيمة بالضبط |

### قراءة بمفتاح

| العملية                           | ماذا تفعل                                                                                                                        |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **أول عنصر**                      | تُرجع أول عنصر في مصفوفة                                                                                                         |
| **آخر عنصر**                      | تُرجع آخر عنصر في مصفوفة                                                                                                         |
| **عنصر بمفتاح محدد**              | تبحث عن أول عنصر يحمل مفتاحاً معيناً وتُرجعه                                                                                     |
| **عنصر بمفتاح وقيمة معاً**        | تبحث عن العنصر الذي يطابق مفتاحاً *وقيمة* محددة معاً — مفيد للبحث عن سجل بعينه في قائمة (مثال: الطلب الذي رقمه يساوي قيمة معينة) |
| **جميع القيم بمفتاح**             | تجمع كل القيم المرتبطة بمفتاح معين عبر كل عناصر المصفوفة في قائمة واحدة                                                          |
| **شريحة من العناصر (إزاحة وطول)** | تُرجع جزءاً محدداً من المصفوفة بالبدء من موضع (إزاحة) وعدد عناصر معين (طول) — مفيد للتقسيم على صفحات                             |

### كتابة/تعديل

| العملية                     | ماذا تفعل                                                                      |
| --------------------------- | ------------------------------------------------------------------------------ |
| **إدراج عنصر**              | تضيف عنصراً جديداً للمصفوفة                                                    |
| **تحديث عنصر**              | تعدّل عنصراً موجوداً يطابق شرطاً معيناً                                        |
| **تحديث أو إدراج (Upsert)** | تعدّل العنصر إن كان موجوداً، أو تضيفه جديداً إن لم يكن — بخطوة واحدة بدل فرعين |
| **حذف الكل**                | تفرّغ المصفوفة بالكامل                                                         |
| **حذف بمفتاح**              | تحذف كل العناصر التي تحمل مفتاحاً معيناً                                       |
| **حذف بقيمة**               | تحذف كل العناصر التي تساوي قيمة معينة                                          |
| **حذف بمفتاح وقيمة معاً**   | تحذف العناصر التي تطابق مفتاحاً وقيمة محددين معاً بدقة                         |

### إحصاءات

كل عملية إحصاء تعمل على قيم مرتبطة بمفتاح محدد عبر عناصر المصفوفة:

| العملية         | ماذا تفعل                                        |
| --------------- | ------------------------------------------------ |
| **عدد العناصر** | تُرجع عدد العناصر في المصفوفة                    |
| **الجمع**       | تجمع كل القيم العددية لمفتاح معين                |
| **المتوسط**     | متوسط القيم العددية لمفتاح معين                  |
| **الوسيط**      | القيمة الوسطى (Median) للقيم العددية لمفتاح معين |
| **أكبر قيمة**   | أعلى قيمة عددية لمفتاح معين                      |
| **أصغر قيمة**   | أدنى قيمة عددية لمفتاح معين                      |

<Tip>
  مثال عملي: استجابة طلب HTTP ترجع قائمة طلبات العميل. استخدم **الجمع** على مفتاح `total` لحساب إجمالي ما اشتراه العميل تاريخياً، واحفظه في حقل مخصص على بطاقته — دون كتابة سطر كود واحد.
</Tip>

### ترتيب

| العملية    | ماذا تفعل                               |
| ---------- | --------------------------------------- |
| **تصاعدي** | ترتب المصفوفة من الأصغر للأكبر          |
| **تنازلي** | ترتب المصفوفة من الأكبر للأصغر          |
| **عشوائي** | تعيد ترتيب المصفوفة عشوائياً            |
| **معكوس**  | تعكس ترتيب المصفوفة الحالي بلا فرز جديد |

### تحويل بنية

| العملية                    | ماذا تفعل                                                                                                                           |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **كل المفاتيح**            | تُرجع قائمة بكل مفاتيح الكائن                                                                                                       |
| **كل القيم**               | تُرجع قائمة بكل قيم الكائن                                                                                                          |
| **كل القيم بمفتاح**        | تُرجع قائمة بكل القيم المرتبطة بمفتاح معين عبر عناصر متعددة                                                                         |
| **تحويل لكائن مفتاح-قيمة** | تحوّل مصفوفة عناصر إلى كائن واحد، مفتاحه من حقل وقيمته من حقل آخر — مفيد لتسريع البحث اللاحق بالمفتاح بدل تكرار المرور على المصفوفة |
| **دمج العناصر بفاصل نصي**  | تدمج كل عناصر المصفوفة في نص واحد، بفاصل تحدده أنت (فاصلة، شرطة...) — مفيد لعرض قائمة داخل رسالة نصية                               |

### تحميل

| العملية                        | ماذا تفعل                                                                          |
| ------------------------------ | ---------------------------------------------------------------------------------- |
| **تحميل عناصر من نص JSON خام** | تحوّل نص JSON مكتوب يدوياً (Raw) إلى بنية بيانات تستطيع باقي العمليات التعامل معها |

## متى تستخدمه؟

| احتياجك                                       | الأنسب                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| تنظيف أو تلخيص استجابة JSON معقدة لحقول بسيطة | عمليات JSON                                                                     |
| حساب إحصائي بسيط (جمع، متوسط، عدّ)            | عمليات JSON — أسرع من كتابة كود                                                 |
| منطق حسابي أو شرطي معقد لا تغطيه عملية جاهزة  | [دالة JavaScript](/ar/help-center/guides/automations/nodes/actions/js-function) |

## أخطاء شائعة

| الخطأ                                             | النتيجة                               | الصواب                                                  |
| ------------------------------------------------- | ------------------------------------- | ------------------------------------------------------- |
| اختيار عملية إحصاء على حقل غير عددي               | نتيجة فارغة أو خطأ                    | تأكد أن المفتاح المستهدف يحمل قيماً عددية               |
| توقّع ترتيب النتيجة دون استخدام عملية ترتيب صريحة | ترتيب غير متوقع في الرسالة أو التقرير | أضف عملية ترتيب بعد عمليات القراءة إن كان الترتيب مهماً |
| استخدام "تحديث عنصر" بلا شرط مطابقة دقيق          | تحديث عنصر خاطئ بالغلط                | تأكد من مفتاح/قيمة المطابقة قبل النشر                   |
| مصدر بيانات غير موجود أو فارغ من خطوة سابقة       | فشل صامت أو قيمة افتراضية غير متوقعة  | تأكد من نجاح الخطوة السابقة (طلب HTTP) قبل التحويل      |

## ذات صلة

* [عقدة: إجراء — نظرة عامة](/ar/help-center/guides/automations/nodes/actions/overview)
* [طلب HTTP](/ar/help-center/guides/automations/nodes/actions/http-request)
* [دالة JavaScript](/ar/help-center/guides/automations/nodes/actions/js-function)


## Related topics

- [عقدة: إجراء — نظرة عامة](/ar/help-center/guides/automations/nodes/actions/overview.md)
- [إجراء: طلب HTTP](/ar/help-center/guides/automations/nodes/actions/http-request.md)
- [إجراء: دالة JavaScript](/ar/help-center/guides/automations/nodes/actions/js-function.md)
- [نظرة عامة](/ar/help-center/guides/automations/overview.md)
- [إجراء: تحديث خاصية العميل](/ar/help-center/guides/automations/nodes/actions/set-property.md)