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

ادمج ملفي CSV بالمفتاح واكشف الصفوف غير المتطابقة

يمكنكم دمج ملفي CSV بواسطة مفتاح عندما يتضمن أحد الجدولين السجلات الأساسية ويضيف الآخر حقولاً مرتبطة.

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

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

ألصقوا نصي CSV وحددوا اسم الرأس المشترك لتحصلوا على ربط أيسر متوقع من دون إعداد قاعدة بيانات أو كتابة برنامج نصي مؤقت. تفصل الاستجابة أيضاً السجلات التي لم تجد تطابقاً في كل جانب، مما يسهّل مراجعة النواقص. وتُعالج القيم المقتبسة والمفاتيح المكررة وتعارضات الرؤوس ونهايات الأسطر الشائعة معالجة حتمية تضمن النتيجة نفسها للمدخلات نفسها.

جهزوا ملفي CSV بمفتاح مشترك موثوق

ابدؤوا بتحديد العمود الذي يمثل العنصر نفسه في الملفين، مثل customer_id أو order_number أو sku أو email. يجب أن تتطابق كتابة الرأس تماماً مع قيمة المفتاح التي ترسلونها، بما في ذلك حالة الأحرف والمسافات. ويمكن أن تختلف جميع الرؤوس الأخرى. يمثل ملف CSV الأيسر الجدول الأساسي، ولذلك يبقى كل سجل منه في النتيجة المدمجة سواء وُجد له سجل مطابق في اليمين أم لا. ويضيف ملف CSV الأيمن أعمدة عند تطابق قيمة المفتاح. استخدموا معرفاً ثابتاً كلما أمكن؛ فالأسماء والأوصاف قد تتغير أو تتضمن مسافات غير متسقة أو تتكرر، بينما يكون معرف النظام أكثر أماناً عادة. يدعم المحلل الحقول الموضوعة بين علامتي اقتباس، وعلامات الاقتباس المزدوجة المهروبة، والفواصل داخل القيم المقتبسة، وفواصل الأسطر المضمنة، وملفات CRLF، وعلامة ترتيب البايت UTF-8 في البداية. إذا كان الملفان يستخدمان فاصلاً آخر، فحددوا ذلك المحرف الواحد، ويجب أن يستخدم المدخلان الفاصل نفسه. تُرفض أسماء الأعمدة الفارغة أو المكررة لأنها تجعل كائنات النتيجة ملتبسة. كما يظهر خطأ إدخال واضح إذا كان رأس المفتاح مفقوداً من أي ملف CSV بدلاً من إرجاع جدول مضلل بلا تطابقات.

افهموا الربط الأيسر وسلوك المفاتيح المكررة

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

استخدموا تقارير عدم التطابق لتسوية البيانات بأمان

تتضمن مصفوفة unmatched_left سجلات اليسار الأصلية التي لم تجد مفاتيحها مقابلاً في اليمين. تبقى هذه السجلات في joined_rows لأن العملية ربط أيسر، لكن القائمة المنفصلة تتيح إحالتها إلى التصحيح أو الإثراء أو المراجعة. أما unmatched_right فتتضمن سجلات اليمين الأصلية التي لم يستخدمها أي سجل أيسر. لا تظهر هذه السجلات في الجدول المدمج، لكنها كثيراً ما تكشف بيانات مرجعية قديمة، أو معرفات جديدة غير متوقعة، أو ملفاً تابعاً لفترة إعداد تقارير غير صحيحة. تلخص العدادات حجم المصدرين وحجم النتيجة بعد التوسع وإجمالي السجلات غير المتطابقة، فتسهل اختبارات الجودة الآلية. يمكن لمسار عمل، مثلاً، رفض الاستيراد عندما تكون unmatched_left أكبر من الصفر أو إرسال تنبيه عندما تتجاوز unmatched_right حداً معيناً. تتم المطابقة حرفياً من دون إزالة المسافات أو توحيد حالة الأحرف أو إعادة تفسير الأرقام؛ لذلك تظل 001 و1 و1 المتبوعة بمسافة قيماً مختلفة. تمنع هذه القاعدة المحافظة الربط العرضي. طبّعوا المفاتيح قبل الطلب فقط إذا كانت قواعد العمل تسمح باعتبار تلك القيم متكافئة. مقابل $0.002 لكل طلب عبر API، يمكن إدراج العملية في عمليات الاستيراد المتكررة والتحقيقات الفردية.

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

إثراء ملفات تصدير العملاء

أضيفوا الخطة أو المنطقة أو مسؤول الحساب من ملف CSV مرجعي مع الاحتفاظ بكل عميل في التصدير الأساسي.

تسوية الطلبات والمدفوعات

اربطوا المعاملات برقم الطلب واكتشفوا الطلبات غير المدفوعة أو المدفوعات المرتبطة بطلب مجهول.

تدقيق تغطية كتالوج المنتجات

ادمجوا قائمة SKU الأساسية مع بيانات المورد ثم اكتشفوا المنتجات الناقصة وصفوف المورد غير المستخدمة.

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

ماذا يحدث إذا كان عمود المفتاح مفقوداً؟

يفشل الطلب بخطأ إدخال يحدد ما إذا كان المفتاح مفقوداً من ملف CSV الأيسر أم الأيمن.

هل تحتفظ العملية بجميع صفوف اليسار؟

نعم. العملية دائماً ربط أيسر، وتصبح الحقول المضافة من اليمين سلاسل فارغة للصف الذي لا يجد تطابقاً.

كيف تُعالج المفاتيح المكررة؟

يُدمج كل سجل أيسر مع جميع السجلات اليمنى المطابقة، ولذلك قد ينتج عنه أكثر من صف.

ماذا لو احتوى الملفان على عمود بالاسم نفسه؟

يحتفظ عمود اليسار باسمه، ويأخذ عمود اليمين prefix‏ right_ مع إضافة prefixات أخرى عند الضرورة.

هل تُنظف المفاتيح قبل المطابقة؟

لا. تحافظ المقارنة الحرفية على المسافات وحالة الأحرف والأصفار البادئة؛ طبّعوا القيم مسبقاً عند الحاجة.

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

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

الـEndpoint

POSThttps://api.kit.forhosting.com/data/merge-csv-on-key

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

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

curl -X POST https://api.kit.forhosting.com/data/merge-csv-on-key \
  -H "Authorization: Bearer $KIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"left_csv":"id,name\n1,Ada\n2,Linus\n3,Grace","right_csv":"id,team\n1,Research\n2,Platform\n4,Support","key":"id"}'

const res = await fetch("https://api.kit.forhosting.com/data/merge-csv-on-key", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.KIT_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "left_csv": "id,name\n1,Ada\n2,Linus\n3,Grace",
    "right_csv": "id,team\n1,Research\n2,Platform\n4,Support",
    "key": "id"
  })
});
const { task_id } = await res.json();

import os, requests

res = requests.post(
    "https://api.kit.forhosting.com/data/merge-csv-on-key",
    headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
    json={
    "left_csv": "id,name\n1,Ada\n2,Linus\n3,Grace",
    "right_csv": "id,team\n1,Research\n2,Platform\n4,Support",
    "key": "id"
},
)
task_id = res.json()["task_id"]

<?php
$res = file_get_contents("https://api.kit.forhosting.com/data/merge-csv-on-key", false, stream_context_create([
  "http" => [
    "method"  => "POST",
    "header"  => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
    "content" => '{"left_csv":"id,name\\n1,Ada\\n2,Linus\\n3,Grace","right_csv":"id,team\\n1,Research\\n2,Platform\\n4,Support","key":"id"}',
  ],
]));
$task = json_decode($res, true);

body := bytes.NewBufferString(`{"left_csv":"id,name\n1,Ada\n2,Linus\n3,Grace","right_csv":"id,team\n1,Research\n2,Platform\n4,Support","key":"id"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/data/merge-csv-on-key", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)

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

{
  "left_csv": "id,name\n1,Ada\n2,Linus\n3,Grace",
  "right_csv": "id,team\n1,Research\n2,Platform\n4,Support",
  "key": "id"
}

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

{
  "task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "type": "data.merge_csv_on_key",
  "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 الكامل ←