محوّل JSON إلى CSV

ما هو تحويل JSON إلى CSV؟

يُحوِّل محوِّل JSON إلى CSV البيانات المنظّمة من تنسيق JSON إلى قيم مفصولة بفواصل، وهو تنسيق جدولي تستوعبه جداول البيانات وقواعد البيانات وأدوات التحليل بصورة مباشرة. يخزّن JSON البيانات في شكل كائنات متداخلة ومصفوفات دون مخطط بيانات ثابت، في حين يخزّن CSV البيانات في شكل صفوف وأعمدة مع سطر ترويسة يُحدّد أسماء الحقول. التحويل هو الجسر الذي يوصل بيانات API إلى جداول البيانات وقواعد البيانات.

CSV (القيم المفصولة بفواصل) معرَّف بموجب RFC 4180. كل سطر يمثّل سجلًا واحدًا، وتُفصل الحقول داخل السطر بمحرف فاصل، وأكثره شيوعًا الفاصلة. يجب تضمين الحقول التي تحتوي على الفاصل أو علامات الاقتباس المزدوجة أو فواصل الأسطر بين علامتَي اقتباس مزدوجتَين، مع تخطي علامات الاقتباس الداخلية بمضاعفتها. هذا التخطي هو المصدر الرئيسي للأخطاء عند كتابة محوّل JSON إلى CSV يدويًا.

يكون التحويل مباشرًا عندما يكون المدخل مصفوفة مسطّحة من الكائنات ذات المفاتيح المتسقة. يصبح كل كائن صفًّا واحدًا، ويصبح كل مفتاح فريد عنوانًا للعمود. تتطلب الكائنات والمصفوفات المتداخلة خطوة تسوية، فيما تتطلب المفاتيح غير المتسقة عبر الكائنات استراتيجية للتعامل مع الحقول المفقودة — وعادةً ترك الخلية فارغة. يُعالج محوّل موثوق جميع هذه الحالات الاستثنائية تلقائيًا.

لماذا تُحوِّل JSON إلى CSV؟

تُعيد واجهات API بيانات بتنسيق JSON، غير أن جداول البيانات وقواعد بيانات SQL وأدوات ذكاء الأعمال تتوقع بيانات جدولية. يُتيح لك تحويل JSON إلى CSV نقل البيانات بين هذه الأنظمة دون كتابة سكريبتات استيراد مخصصة.

حالات استخدام تحويل JSON إلى CSV

مرجع فواصل CSV

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

التعامل مع JSON المتداخل في CSV

CSV هو تنسيق مسطّح لا يمتلك آلية مدمجة لتمثيل الكائنات أو المصفوفات المتداخلة. عندما يحتوي JSON على بنى متداخلة، يجب على المحوّل تسويتها إلى أعمدة. ثمة عدة استراتيجيات، والاختيار الصحيح يعتمد على كيفية استهلاك CSV.

أمثلة برمجية

يتطلب تحويل JSON إلى CSV برمجيًا التعامل مع استخراج الترويسات واقتباس الحقول والهروب من الفاصل. تمتلك معظم اللغات دعمًا مدمجًا أو ضمن المكتبة القياسية لكتابة CSV.

const data = [
  { name: "Alice", age: 30, city: "Berlin" },
  { name: "Bob", age: 25, city: "Tokyo" },
]

// Extract headers from the first object
const headers = Object.keys(data[0])
const csv = [
  headers.join(","),
  ...data.map(row => headers.map(h => {
    const val = String(row[h] ?? "")
    // Quote fields that contain commas, quotes, or newlines
    return val.includes(",") || val.includes('"') || val.includes("\n")
      ? '"' + val.replace(/"/g, '""') + '"'
      : val
  }).join(","))
].join("\n")

console.log(csv)
// → name,age,city
// → Alice,30,Berlin
// → Bob,25,Tokyo

import json, csv, io

json_str = '[{"name":"Alice","age":30,"city":"Berlin"},{"name":"Bob","age":25,"city":"Tokyo"}]'
data = json.loads(json_str)

output = io.StringIO()
writer = csv.DictWriter(output, fieldnames=data[0].keys())
writer.writeheader()
writer.writerows(data)

print(output.getvalue())
# → name,age,city
# → Alice,30,Berlin
# → Bob,25,Tokyo

# Using jq to convert JSON array to CSV
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | \
  jq -r '(.[0] | keys_unsorted) as $k | $k, (.[] | [.[$k[]]] ) | @csv'
# → "name","age"
# → "Alice",30
# → "Bob",25

# Using Miller (mlr) for streaming conversion
echo '[{"name":"Alice","age":30}]' | mlr --json --ocsv cat
# → name,age
# → Alice,30

package main

import (
    "encoding/csv"
    "encoding/json"
    "fmt"
    "os"
)

func main() {
    jsonStr := `[{"name":"Alice","age":30},{"name":"Bob","age":25}]`
    var data []map[string]interface{}
    json.Unmarshal([]byte(jsonStr), &data)

    w := csv.NewWriter(os.Stdout)
    // Write header
    headers := []string{"name", "age"}
    w.Write(headers)
    // Write rows
    for _, row := range data {
        record := make([]string, len(headers))
        for i, h := range headers {
            record[i] = fmt.Sprintf("%v", row[h])
        }
        w.Write(record)
    }
    w.Flush()
    // → name,age
    // → Alice,30
    // → Bob,25
}

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