982f0c4a4d
Created by Github action --------- Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
148 lines
7.7 KiB
Plaintext
148 lines
7.7 KiB
Plaintext
---
|
|
title: واجهات برمجة التطبيقات
|
|
description: استعلم وعدّل بيانات إدارة علاقات العملاء (CRM) لديك برمجياً باستخدام REST أو GraphQL.
|
|
---
|
|
|
|
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
|
|
|
تم تصميم Twenty ليكون صديقًا للمطورين، حيث يوفر واجهات برمجة قوية تتكيف مع نموذج البيانات المخصص. نحن نوفر أربعة أنواع متميزة من واجهات برمجة التطبيقات لتلبية احتياجات التكامل المختلفة.
|
|
|
|
## نهج المطوّر أولاً
|
|
|
|
تقوم Twenty بإنشاء واجهات برمجة التطبيقات خصيصاً لنموذج بياناتك:
|
|
|
|
* **لا حاجة إلى معرفات طويلة**: استخدم أسماء الكائنات والحقول مباشرة في نقاط النهاية
|
|
* **معاملة متساوية للكائنات القياسية والمخصصة**: تحصل كائناتك المخصصة على نفس معاملة واجهة برمجة التطبيقات كما هو الحال مع الكائنات المضمنة
|
|
* **نقاط نهاية مخصصة**: يحصل كل كائن وحقل على نقطة نهاية API الخاصة به
|
|
* **وثائق مخصصة**: يتم إنشاؤها خصيصًا لنموذج بيانات مساحة عملك
|
|
|
|
<Note>
|
|
وثائق واجهة برمجة التطبيقات المخصصة لك متاحة ضمن **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب** بعد إنشاء مفتاح API. نظرًا لأن Twenty تُنشئ واجهات برمجة تطبيقات تتطابق مع نموذج البيانات المخصص لديك، فإن الوثائق فريدة لمساحة عملك.
|
|
</Note>
|
|
|
|
## نوعا واجهات برمجة التطبيقات
|
|
|
|
### واجهة برمجة التطبيقات الأساسية
|
|
|
|
يتم الوصول إليها عبر `/rest/` أو `/graphql/`
|
|
|
|
تعامَل مع **السجلات** الفعلية لديك (البيانات):
|
|
|
|
* إنشاء وقراءة وتحديث وحذف الأشخاص والشركات والفرص، إلخ.
|
|
* استعلام وتصفية البيانات
|
|
* إدارة العلاقات بين السجلات
|
|
|
|
### واجهة برمجة البيانات الوصفية
|
|
|
|
يتم الوصول إليها عبر `/rest/metadata/` أو `/metadata/`
|
|
|
|
إدارة **مساحة العمل ونموذج البيانات** لديك:
|
|
|
|
* إنشاء أو تعديل أو حذف الكائنات والحقول
|
|
* تكوين إعدادات مساحة العمل
|
|
* تعريف العلاقات بين الكائنات
|
|
|
|
## REST مقابل GraphQL
|
|
|
|
تتوفر واجهات برمجة التطبيقات الأساسية وواجهات البيانات الوصفية بصيغتي REST وGraphQL:
|
|
|
|
| التنسيق | العمليات المتاحة |
|
|
| ----------- | ----------------------------------------------------------------------------- |
|
|
| **REST** | CRUD، عمليات الدفعات، إدراج/تحديث |
|
|
| **GraphQL** | نفس الشيء + **عمليات إدراج/تحديث مجمعة**، واستعلامات العلاقات في استدعاء واحد |
|
|
|
|
اختر بناءً على احتياجاتك — كلا الصيغتين تصلان إلى البيانات نفسها.
|
|
|
|
## نقاط نهاية API
|
|
|
|
| البيئة | عنوان URL الأساسي |
|
|
| --------------------- | ------------------------- |
|
|
| **السحابة** | `https://api.twenty.com/` |
|
|
| **الاستضافة الذاتية** | `https://{your-domain}/` |
|
|
|
|
## المصادقة
|
|
|
|
كل طلب API يتطلب تضمين مفتاح API في رأس الطلب:
|
|
|
|
```
|
|
Authorization: Bearer YOUR_API_KEY
|
|
```
|
|
|
|
### قم بإنشاء مفتاح API
|
|
|
|
1. انتقل إلى **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب**
|
|
2. انقر على **+ إنشاء مفتاح**
|
|
3. التكوين:
|
|
* **الاسم**: اسم وصفي للمفتاح
|
|
* **تاريخ الانتهاء**: متى تنتهي صلاحية المفتاح
|
|
4. انقر على **حفظ**
|
|
5. **انسخه فوراً** — يظهر المفتاح مرة واحدة فقط
|
|
|
|
<VimeoEmbed videoId="928786722" title="إنشاء مفتاح API" />
|
|
|
|
<Warning>
|
|
يمنح مفتاح API الخاص بك الوصول إلى بيانات حساسة. لا تشاركه مع خدمات غير موثوقة. إذا تم اختراقه، عطّلْه فوراً وأنشئ مفتاحاً جديداً.
|
|
</Warning>
|
|
|
|
### تعيين دور لمفتاح API
|
|
|
|
لتحسين الأمان، عيّن دوراً محدداً لتقييد الوصول:
|
|
|
|
1. اذهب إلى **الإعدادات → الأدوار**
|
|
2. انقر على الدور الذي ترغب في تعيينه
|
|
3. افتح علامة التبويب **التعيين**
|
|
4. ضمن **مفاتيح API**، انقر على **+ تعيين إلى مفتاح API**
|
|
5. حدد مفتاح API
|
|
|
|
سيرث المفتاح أذونات ذلك الدور. راجع [الأذونات](/l/ar/user-guide/permissions-access/capabilities/permissions) للحصول على التفاصيل.
|
|
|
|
### إدارة مفاتيح API
|
|
|
|
**إعادة التوليد**: الإعدادات → واجهات برمجة التطبيقات وخطافات الويب → انقر على المفتاح → **إعادة التوليد**
|
|
|
|
**حذف**: الإعدادات → واجهات برمجة التطبيقات وخطافات الويب → انقر على المفتاح → **حذف**
|
|
|
|
## ملعب واجهة برمجة التطبيقات
|
|
|
|
اختبر واجهات برمجة التطبيقات لديك مباشرة في المتصفح باستخدام الملعب المدمج لدينا — متاح لكلٍ من **REST** و**GraphQL**.
|
|
|
|
### الوصول إلى الملعب
|
|
|
|
1. انتقل إلى **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب**
|
|
2. أنشئ مفتاح API (مطلوب)
|
|
3. انقر على **REST API** أو **GraphQL API** لفتح الملعب
|
|
|
|
### ما الذي ستحصل عليه
|
|
|
|
* **وثائق تفاعلية**: يتم إنشاؤها لنموذج البيانات المحدد لديك
|
|
* **اختبارات حيّة**: تنفيذ استدعاءات API فعلية على مساحة عملك
|
|
* **مستكشف المخطط**: تصفح الكائنات والحقول والعلاقات المتاحة
|
|
* **منشئ الطلبات**: أنشئ الاستعلامات مع الإكمال التلقائي
|
|
|
|
يعكس الملعب الكائنات والحقول المخصصة لديك، لذا تكون الوثائق دائماً دقيقة لمساحة عملك.
|
|
|
|
## عمليات الدفعات
|
|
|
|
كلٌ من REST وGraphQL يدعمان عمليات الدفعات:
|
|
|
|
* **حجم الدفعة**: حتى 60 سجل لكل طلب
|
|
* **العمليات**: إنشاء وتحديث وحذف سجلات متعددة
|
|
|
|
**ميزات خاصة بـ GraphQL:**
|
|
|
|
* **إدراج/تحديث دفعي**: إنشاء أو تحديث في استدعاء واحد
|
|
* استخدم الأسماء الجمع للكائنات (على سبيل المثال، `CreateCompanies` بدلاً من `CreateCompany`)
|
|
|
|
## حدود المعدل
|
|
|
|
يتم تنظيم طلبات API لضمان استقرار المنصة:
|
|
|
|
| الحد | القيمة |
|
|
| -------------- | ---------------------- |
|
|
| **الطلبات** | 100 استدعاء في الدقيقة |
|
|
| **حجم الدفعة** | 60 سجل لكل استدعاء |
|
|
|
|
<Tip>
|
|
استخدم عمليات الدفعات لزيادة الإنتاجية — عالج ما يصل إلى 60 سجلًا في استدعاء API واحد بدلاً من إجراء طلبات فردية.
|
|
</Tip>
|