e7da97194a
Some checks failed
App Prod-Parity E2E Dispatch / dispatch (push) Failing after 10s
CD Storybook UI / build (push) Failing after 3m25s
CD Storybook UI / dispatch (push) Has been skipped
CD deploy main / website-changed-files (push) Successful in 18m8s
CI Agent Skills / changed-files-check (push) Successful in 18m9s
CI Create App E2E minimal / changed-files-check (push) Successful in 24s
CI Create App / changed-files-check (push) Successful in 26s
CI Docs / changed-files-check (push) Successful in 26s
CI Emails / changed-files-check (push) Successful in 28s
CI Example App Hello World / changed-files-check (push) Successful in 23s
CI Front / changed-files-check (push) Has been skipped
CI Example App Postcard / changed-files-check (push) Successful in 27s
CI UI / changed-files-check (push) Has been skipped
CI Utils Test / changed-files-check (push) Successful in 45s
CI Twenty Apps / discover (push) Successful in 1m3s
CD deploy main / deploy-main (push) Failing after 3s
CI Agent Skills / agent-skills-validate (push) Has been skipped
CI Create App / create-app-test (lint) (push) Has been skipped
CI Emails / emails-test (push) Has been skipped
CI Front / front-task (lingui:compile) (push) Has been skipped
CI Front / front-task (lint) (push) Has been skipped
CI Example App Postcard / example-app-postcard (push) Has been skipped
CI UI / ui-task (lint) (push) Has been skipped
CI UI / ui-task (pack-size) (push) Has been skipped
CI UI / ui-task (size) (push) Has been skipped
CI UI / ui-task (test) (push) Has been skipped
CI UI / ui-task (typecheck) (push) Has been skipped
CI Utils Test / utils-test (push) Has been skipped
CI Twenty Apps / ${{ matrix.app.name }} (push) Has been skipped
CI Emails / ci-emails-status-check (push) Successful in 2s
CI Example App Hello World / ci-example-app-hello-world-status-check (push) Successful in 2s
CI Example App Postcard / ci-example-app-postcard-status-check (push) Successful in 3s
CI UI / ui-sb-test (push) Has been skipped
CI Utils Test / ci-utils-test-status-check (push) Successful in 2s
CI Twenty Apps / ci-twenty-apps-status-check (push) Successful in 2s
CI UI / ci-ui-status-check (push) Successful in 2s
CI Desktop / desktop (push) Failing after 1m8s
Push docs to Crowdin / Push documentation to Crowdin (push) Failing after 55s
Push translations to Crowdin / Extract and upload translations (push) Failing after 5s
Push website translations to Crowdin / Extract and upload website translations (push) Failing after 5s
CI Create App / create-app-test (test) (push) Has been skipped
CI Create App / create-app-test (typecheck) (push) Has been skipped
CI Docs / docs-lint (push) Has been skipped
CI Example App Hello World / example-app-hello-world (push) Has been skipped
CI Front / front-task (lingui:extract) (push) Has been skipped
CI Front / front-task (test) (push) Has been skipped
CI Front / front-task (typecheck) (push) Has been skipped
CI UI / ui-sb-build (push) Failing after 1m32s
CI Twenty Apps / ${{ matrix.app.name }} (${{ matrix.server-source }}) (push) Has been skipped
CI Agent Skills / agent-skills-publish (push) Has been skipped
CI Create App / ci-create-app-status-check (push) Successful in 2s
CI Agent Skills / agent-skills-remote-source (push) Has been skipped
CI Create App E2E minimal / create-app-e2e-minimal (push) Has been cancelled
CI E2E Main / e2e-test (push) Has been cancelled
CI Front / front-sb-build (push) Has been cancelled
CI Front / front-build (push) Has been cancelled
CI Create App E2E minimal / ci-create-app-e2e-minimal-status-check (push) Has been cancelled
CI E2E Main / ci-e2e-main-status-check (push) Has been cancelled
CI E2E Main / notify-main-ci-failure (push) Has been cancelled
CI E2E Main / qa-scout-comment (push) Has been cancelled
CI Front / front-sb-test (push) Has been cancelled
CI Front / front-sb-screenshots (push) Has been cancelled
CI Front / ci-front-status-check (push) Has been cancelled
DPA Sub-Processor Sync / sync-subprocessors (push) Failing after 3s
AI Catalog Sync / sync-catalog (push) Failing after 2s
177 lines
9.6 KiB
Plaintext
177 lines
9.6 KiB
Plaintext
---
|
|
title: استيراد البيانات عبر واجهة API
|
|
description: متى وكيف تستخدم واجهات API الخاصة بـ Twenty لاستيراد البيانات على نطاق واسع.
|
|
---
|
|
|
|
## نظرة عامة
|
|
|
|
توفّر Twenty كلًا من **GraphQL** و**واجهات REST API** لاستيراد البيانات برمجيًا. استخدم واجهة API عندما لا يكون استيراد CSV عمليًا لحجم بياناتك أو عندما تحتاج إلى عمليات استيراد مؤتمتة ومتكررة.
|
|
|
|
## متى تستخدم الاستيراد عبر API
|
|
|
|
| السيناريو | الطريقة الموصى بها |
|
|
| ----------------------------- | ---------------------------- |
|
|
| أقل من 10,000 سجل | استيراد CSV |
|
|
| 10,000 - 50,000 سجل | استيراد CSV (قسّم إلى ملفات) |
|
|
| **أكثر من 50,000 سجل** | **استيراد API** |
|
|
| ترحيل لمرة واحدة | أيّ منهما (حسب الحجم) |
|
|
| **عمليات استيراد متكررة** | **استيراد API** |
|
|
| **مزامنة في الوقت الحقيقي** | **استيراد API** |
|
|
| **التكامل مع الأنظمة الأخرى** | **استيراد API** |
|
|
|
|
<Note>بالنسبة لمجموعات البيانات التي تبلغ مئات الآلاف، تكون واجهة API أسرع بكثير وأكثر موثوقية من عمليات استيراد CSV المتعددة.</Note>
|
|
|
|
## حدود معدل API
|
|
|
|
تفرض Twenty حدودًا للمعدل لضمان استقرار النظام:
|
|
|
|
| الحد | القيمة |
|
|
| ---------------------------- | ---------------- |
|
|
| **الطلبات في الدقيقة** | 100 |
|
|
| **السجلات لكل استدعاء دفعي** | 60 |
|
|
| **الحد الأقصى للإنتاجية** | ~6,000 سجل/دقيقة |
|
|
|
|
<Warning>
|
|
**خطّط لعملية الاستيراد وفق هذه الحدود.**
|
|
|
|
بالنسبة إلى 100,000 سجل عند أقصى إنتاجية، توقّع نحو 17 دقيقة من وقت الاستيراد. أضِف وقتًا احتياطيًا لمعالجة الأخطاء وإعادة المحاولة.
|
|
</Warning>
|
|
|
|
## البدء
|
|
|
|
### الخطوة 1: احصل على مفتاح API الخاص بك
|
|
|
|
1. انتقل إلى **الإعدادات → المطوّرون**
|
|
2. انقر **+ إنشاء مفتاح API**
|
|
3. امنح مفتاحك اسمًا وصفيًا
|
|
4. انسخ مفتاح API فورًا (لن يُعرَض مرة أخرى)
|
|
5. احفظه في مكان آمن
|
|
|
|
<Warning>
|
|
**أبقِ مفتاح API سريًا.**
|
|
|
|
يمكن لأي شخص لديه مفتاح API الخاص بك الوصول إلى بيانات مساحة العمل الخاصة بك وتعديلها. لا تقم أبدًا بإيداعه في مستودعات الكود أو مشاركته علنًا.
|
|
</Warning>
|
|
|
|
### الخطوة 2: اختر واجهة API الخاصة بك
|
|
|
|
تدعم Twenty نوعين من واجهات API:
|
|
|
|
| واجهة برمجة التطبيقات | الأفضل لـ | التوثيق |
|
|
| --------------------- | ------------------------------------------------------ | ----------------------------------- |
|
|
| **GraphQL** | استعلامات مرنة، وجلب البيانات المرتبطة، وعمليات معقّدة | [وثائق API](/l/ar/developers/extend/api) |
|
|
| **REST** | عمليات CRUD بسيطة، وأنماط REST مألوفة | [وثائق API](/l/ar/developers/extend/api) |
|
|
|
|
كلتا واجهتي API تدعمان:
|
|
|
|
* إنشاء السجلات وقراءتها وتحديثها وحذفها
|
|
* **عمليات الدُفعات** — إنشاء أو تحديث ما يصل إلى 60 سجلًا لكل استدعاء
|
|
|
|
**لعمليات الاستيراد، استخدم عمليات الدُفعات** لتعظيم الإنتاجية ضمن حدود المعدل.
|
|
|
|
### الخطوة 3: خطّط لترتيب الاستيراد
|
|
|
|
تمامًا مثل عمليات استيراد CSV، فإن **الترتيب مهم** للعلاقات:
|
|
|
|
1. **الشركات** أولًا (من دون تبعيات)
|
|
2. **الأشخاص** ثانيًا (يمكن ربطهم بالشركات)
|
|
3. **الفرص** ثالثًا (يمكن ربطها بالشركات والأشخاص)
|
|
4. **المهام/الملاحظات** (يمكن ربطها بأي مما سبق)
|
|
5. **الكائنات المخصّصة** (وفقًا لتبعياتها)
|
|
|
|
## أفضل الممارسات
|
|
|
|
### اجمع طلباتك في دُفعات
|
|
|
|
* لا ترسل السجلات واحدًا تلو الآخر
|
|
* اجمع ما يصل إلى **60 سجلًا لكل استدعاء API**
|
|
* هذا يُعظّم الإنتاجية ضمن حدود المعدل
|
|
|
|
### التعامل مع حدود المعدل
|
|
|
|
* طبّق فواصل زمنية بين الطلبات (600 مللي ثانية كحد أدنى لعمليات الاستيراد المستمرة)
|
|
* استخدم التراجع الأسي عند بلوغ الحدود
|
|
* راقِب الاستجابات 429 (طلبات كثيرة جدًا)
|
|
|
|
### تحقّق من البيانات أولًا
|
|
|
|
* نظّف بياناتك وتحقّق منها قبل الاستيراد
|
|
* تحقّق من تعبئة الحقول المطلوبة
|
|
* تحقّق من توافق التنسيقات مع متطلبات Twenty (راجع [تعيين الحقول](/l/ar/user-guide/data-migration/capabilities/field-mapping))
|
|
|
|
### سجّل كل شيء
|
|
|
|
* سجّل كل سجل تم استيراده (بما في ذلك المعرّفات)
|
|
* سجّل الأخطاء مع السياق الكامل
|
|
* يساعد ذلك في تصحيح المشكلات والتحقق من الإكمال
|
|
|
|
### اختبر أولًا
|
|
|
|
* اختبر بدفعة صغيرة (10-20 سجلًا)
|
|
* تحقّق من ظهور البيانات بشكل صحيح في Twenty
|
|
* ثم نفّذ عملية الاستيراد الكاملة
|
|
|
|
### استخدم upsert لتجنّب التكرارات
|
|
|
|
واجهة GraphQL API تدعم **upsert على دفعات** — حدِّث إذا كان السجل موجودًا، وأنشئ إذا لم يكن كذلك. يمنع هذا التكرارات عند إعادة تشغيل عمليات الاستيراد.
|
|
|
|
## العثور على أسماء الكائنات والحقول
|
|
|
|
للاطلاع على الكائنات والحقول المتاحة:
|
|
|
|
1. انتقل إلى **الإعدادات → API وخطافات الويب**
|
|
2. استعرض **واجهة API للبيانات الوصفية**
|
|
3. اعرض جميع الكائنات القياسية والمخصّصة مع حقولها
|
|
|
|
تُظهر الوثائق جميع الكائنات القياسية والمخصّصة وحقولها وأنواع البيانات المتوقعة.
|
|
|
|
## الخدمات الاحترافية
|
|
|
|
بالنسبة لعمليات ترحيل API المعقّدة، يمكن لشركائنا تقديم المساعدة:
|
|
|
|
| الخدمة | ما الذي يتضمّنه |
|
|
| ------------------------ | ------------------------------------- |
|
|
| **تصميم نموذج البيانات** | تصميم الهيكل الأمثل لبياناتك |
|
|
| **برامج نصية للترحيل** | كتابة وتشغيل البرامج النصية للاستيراد |
|
|
| **تحويل البيانات** | التعامل مع التعيين المعقّد والتنظيف |
|
|
| **التحقق وضمان الجودة** | التحقق من اكتمال عملية الترحيل |
|
|
|
|
**الأفضل لـ:**
|
|
|
|
* عمليات ترحيل لأكثر من 100,000 سجل
|
|
* تحويلات بيانات معقّدة
|
|
* جداول زمنية ضيّقة
|
|
* الفرق التي تفتقر إلى موارد المطورين
|
|
|
|
تواصل معنا عبر [contact@twenty.com](mailto:contact@twenty.com) أو استكشف [خدمات التنفيذ](/l/ar/user-guide/getting-started/capabilities/implementation-services).
|
|
|
|
## الأسئلة الشائعة
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="ما الفرق بين GraphQL وREST؟">
|
|
يتيح لك GraphQL طلب البيانات التي تحتاجها بدقة ضمن استعلام واحد، وهو أفضل للعمليات المعقّدة. يعتمد REST على طرق HTTP القياسية (GET وPOST وPUT وDELETE)، وقد يكون أكثر ألفة إذا سبق لك العمل مع واجهات API التقليدية.
|
|
</Accordion>
|
|
|
|
<Accordion title="هل يمكنني تحديث السجلات الموجودة عبر API؟">
|
|
نعم! استخدم تحديثات mutations في GraphQL أو طلبات PUT/PATCH في REST مع `id` الخاص بالسجل.
|
|
</Accordion>
|
|
|
|
<Accordion title="كيف أتعامل مع التكرارات؟">
|
|
استعلم أولًا عن السجلات الموجودة باستخدام معرّفات فريدة (البريد الإلكتروني، النطاق). حدِّث إذا كان موجودًا، وأنشئ إذا لم يكن كذلك.
|
|
</Accordion>
|
|
|
|
<Accordion title="هل يمكنني حذف السجلات عبر API؟">
|
|
نعم، استخدم delete mutations في GraphQL أو طلبات DELETE في REST.
|
|
</Accordion>
|
|
|
|
<Accordion title="هل يوجد SDK لـ Python أو Node.js؟">
|
|
لا يتوفر ذلك في الوقت الحالي، لكن كلتا واجهتي API تعملان مع أي عميل HTTP بأي لغة.
|
|
</Accordion>
|
|
</AccordionGroup>
|
|
|
|
## وثائق API
|
|
|
|
للحصول على تفاصيل التنفيذ الكاملة وأمثلة الشيفرة ومرجع المخطط (schema):
|
|
|
|
* [وثائق API](/l/ar/developers/extend/api)
|