ForHosting KIT · البيانات والملفات: تحويل وتنظيف

التحقق من CSV وفق مخطط الأعمدة وتحديد الأخطاء

قد يبدو ملف CSV منظماً، ومع ذلك يحتوي على قيم تعطل الاستيراد أو التقرير أو مسار معالجة البيانات.

● Betaمجاني · داخل متصفحك

استخدمها من الويبAPIالبريدTelegramالتطبيق قريبًا

تقارن هذه الأداة رأس الملف بالأعمدة المتوقعة بدقة، ثم تفحص كل صف وفق قواعد واضحة للنصوص والأرقام والأعداد الصحيحة والقيم المنطقية وتواريخ ISO. ولا تتوقف عند أول خلية خاطئة، بل تعيد قائمة كاملة بالمخالفات مع أرقام صفوف CSV وأسماء الأعمدة. يمكنكم تشغيلها مجاناً في المتصفح أو استخدام API بسعر $0.002 لكل طلب ضمن سير عمل آلي.

حددوا العقد قبل فحص الملف

صفوا كل عمود متوقع بثلاث خصائص: اسمه الدقيق ونوعه وما إذا كان إلزامياً. ترتيب الأعمدة مهم لأن CSV بيانات موضعية؛ فرأس name,id لا يمكن اعتباره مطابقاً بأمان لرأس id,name حتى إن ورد الاسمان في كليهما. لذلك تقارن الأداة الرأس كاملاً بالمخطط قبل فحص صفوف البيانات. ويؤدي أي عمود مفقود أو زائد أو معاد التسمية أو مكرر أو منقول إلى خطأ إدخال بدلاً من تقرير تحقق مضلل. الأنواع المدعومة هي string وnumber وinteger وboolean وdate. تقبل الأرقام الصيغة العشرية والصيغة العلمية، ويجب أن تكون الأعداد الصحيحة ضمن المجال الآمن، وتقبل القيم المنطقية true أو false دون اعتبار لحالة الأحرف، وتستخدم التواريخ الصيغة YYYY-MM-DD مع التأكد من صحة اليوم في التقويم. يقبل النوع النصي أي قيمة غير فارغة، بينما تحدد required بصورة مستقلة إمكان ترك الخلية فارغة. ومن ثم يجوز أن يكون العدد الصحيح الاختياري فارغاً، لكن يجب أن يكون عدداً صحيحاً صالحاً متى وجد.

اقرؤوا مخالفات الصفوف والأعمدة بدقة

تبدأ النتيجة بالمؤشر valid وبأعداد الصفوف والأعمدة والمخالفات التي جرى فحصها. عندما تكون قيمة valid هي false، تحدد مصفوفة violations كل مشكلة برقم الصف واسم العمود ورمز ثابت ورسالة واضحة. تتبع الأرقام ملف CSV نفسه؛ فالصف 1 هو الرأس، وأول سجل هو الصف 2. وهكذا يمكنكم فتح الملف الأصلي والانتقال مباشرة إلى الموضع المذكور. تعني مخالفة required أن خلية إلزامية فارغة، وتعني مخالفة type أن قيمة موجودة لا تطابق النوع المعلن. وتحصل الصفوف ذات الحقول الزائدة أو الناقصة على مخالفة column_count تحت العمود الخاص _row، لأن المشكلة البنيوية لا يمكن نسبتها بثقة إلى خلية واحدة مسماة. يحلل القارئ الفواصل الواقعة بين علامات الاقتباس، وعلامات الاقتباس المهربة، وفواصل الأسطر المضمنة، وملفات CRLF وفق صياغة CSV، ولذلك لا تؤدي علامات الترقيم الصحيحة داخل حقل مقتبس إلى إزاحة الأعمدة التالية أو إنشاء بلاغ كاذب.

ضعوا التحقق عند مدخل سير العمل

تحققوا من الملف في أقرب نقطة ممكنة من دخوله إلى نظامكم. يمكن رفض ملف يرفعه شريك قبل وصوله إلى قاعدة البيانات، أو فحص تصدير مجدول قبل بدء الحسابات اللاحقة، أو عرض جميع الخلايا القابلة للتصحيح دفعة واحدة في واجهة الاستيراد. ولأن الخوارزمية حتمية ولا تستخدم الشبكة، فإن ملف CSV والمخطط نفسيهما ينتجان التقرير نفسه دائماً. وهذا يجعل المخرجات ملائمة للبوابات الآلية وللتنظيف التفاعلي معاً. تعاملوا مع عدم تطابق الرأس بطريقة تختلف عن مخالفات الصفوف؛ فالأول يعني أن الملف ليس مجموعة البيانات المتوقعة، أما الثانية فتعني وجود سجلات معروفة تحتاج إلى تصحيح. تقتصر الأداة على الإبلاغ، ولا تعدل القيم الأصلية أو تحولها أو تقتطعها أو تستبدلها. وبذلك لا تتغير المعرفات أو الأصفار البادئة أو النصوص التي أدخلها الأشخاص دون تنبيه. إذا احتاج مساركم إلى التطبيع، فنفذوه خطوة مستقلة ومقصودة، ثم أعيدوا التحقق وفق العقد الذي تتطلبه الوجهة فعلاً.

حالات الاستخدام

بوابة جودة الاستيراد

ارفضوا ملفات CSV المرفوعة من العملاء أو الشركاء مع تحديد دقيق للصف والعمود قبل إدخالها إلى قاعدة البيانات.

مراقبة عمليات التصدير

افحصوا عمليات التصدير الدورية لاكتشاف تغير الرأس والخلايا الإلزامية الفارغة والقيم التي لم تعد تطابق نوعها المعلن.

سير التصحيح المجمع

أعيدوا جميع المخالفات القابلة للكشف معاً لكي يتمكن المختص من إصلاح الملف في مراجعة واحدة.

الأسئلة الشائعة

هل يجب أن يتبع رأس CSV ترتيب المخطط نفسه؟

نعم. يجب أن تتطابق الأسماء وترتيبها تماماً، وإلا يفشل الطلب بخطأ إدخال متعلق بالرأس.

ما أنواع الأعمدة المدعومة؟

يدعم المخطط string وnumber وinteger وboolean وdate. ويجب أن تكون التواريخ أياماً تقويمية صحيحة بالصيغة YYYY-MM-DD.

هل يتوقف التحقق بعد أول صف خاطئ؟

لا. بعد اجتياز الرأس، تفحص الأداة جميع صفوف البيانات وتعيد كل المخالفات المكتشفة معاً.

كيف تعالج الفواصل وفواصل الأسطر بين علامات الاقتباس؟

يجوز أن تتضمن الحقول المقتبسة فواصل وعلامات اقتباس مزدوجة مهربة وفواصل أسطر من دون تقسيمها إلى أعمدة إضافية.

هل تعدل الأداة قيم CSV أو تحولها؟

لا. إنها تبلغ عن المخالفات فقط، ولا تقتطع ملف CSV المرسل أو تحوله أو تكمله أو تعيد كتابته.

للمطوّرين — الوصول عبر API

كل ما في هذه الصفحة متاح برمجيًا. هذا القسم موجّه للفرق التقنية التي تريد ربط الأداة بأنظمتها الخاصة؛ بقية المستخدمين يمكنهم استخدام الأداة أعلاه مباشرة دون الحاجة لقراءة ما يلي.

الـEndpoint

POSThttps://api.kit.forhosting.com/data/csv-validate-schema

صادِق على طلبك بترويسة Bearer، وأرسل طلب POST واحدًا لتدخل مهمتك قائمة التنفيذ فورًا؛ ثم تستلم النتيجة عبر webhook أو رابط موقّع.

استدعِ الخدمة من بيئتك

curl -X POST https://api.kit.forhosting.com/data/csv-validate-schema \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"csv":"id,email,active\n1,ada@example.com,true\n2,grace@example.com,false","schema":[{"name":"id","type":"integer","required":true},{"name":"email","type":"string","required":true},{"name":"active","type":"boolean","required":true}]}'

const res = await fetch("https://api.kit.forhosting.com/data/csv-validate-schema", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "csv": "id,email,active\n1,ada@example.com,true\n2,grace@example.com,false",
    "schema": [
      {
        "name": "id",
        "type": "integer",
        "required": true
      },
      {
        "name": "email",
        "type": "string",
        "required": true
      },
      {
        "name": "active",
        "type": "boolean",
        "required": true
      }
    ]
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/data/csv-validate-schema",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "csv": "id,email,active\n1,ada@example.com,true\n2,grace@example.com,false",
    "schema": [
        {
            "name": "id",
            "type": "integer",
            "required": true
        },
        {
            "name": "email",
            "type": "string",
            "required": true
        },
        {
            "name": "active",
            "type": "boolean",
            "required": true
        }
    ]
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/data/csv-validate-schema", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"csv":"id,email,active\\n1,ada@example.com,true\\n2,grace@example.com,false","schema":[{"name":"id","type":"integer","required":true},{"name":"email","type":"string","required":true},{"name":"active","type":"boolean","required":true}]}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"csv":"id,email,active\n1,ada@example.com,true\n2,grace@example.com,false","schema":[{"name":"id","type":"integer","required":true},{"name":"email","type":"string","required":true},{"name":"active","type":"boolean","required":true}]}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/data/csv-validate-schema", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

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

{
  "csv": "id,email,active\n1,ada@example.com,true\n2,grace@example.com,false",
  "schema": [
    {
      "name": "id",
      "type": "integer",
      "required": true
    },
    {
      "name": "email",
      "type": "string",
      "required": true
    },
    {
      "name": "active",
      "type": "boolean",
      "required": true
    }
  ]
}

مثال على الاستجابة

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "data.csv_validate_schema",
  "status": "queued",
  "_links": {
    "result": "/tasks/tsk_…/result"
  }
}

الواجهة غير متزامنة: تستلم task_id فور الإرسال، ويمكنك الاستعلام عن الحالة بمعدل طلب واحد في الثانية.

الأسعار

لكل طلب$0.002

السعر معلن كما تراه: لا tokens ولا نظام نقاط؛ وإن فشلت المهمة فلن تُحاسَب عليها.

الحدود

max_mb 25

الأخطاء

HTTP	الرمز	المعنى
`401`	`unauthorized`	مفتاح الوصول مفقود أو غير صالح؛ تحقق من ترويسة Bearer في طلبك.
`402`	`insufficient_balance`	رصيدك لا يكفي لتنفيذ هذه المهمة؛ أعد شحن الرصيد ثم أعد المحاولة.
`404`	`unknown_type`	نوع المهمة المطلوب غير موجود في الكتالوج — راجع الاسم المرسل في الطلب.
`429`	`rate_limited`	تجاوزت الحد المسموح من الطلبات؛ انتظر قليلًا ثم أعد المحاولة.

اطّلع على توثيق KIT الكامل ←