تحويل بيانات JSON الخام إلى تقارير XLSX مصقولة هو حاجة متكررة لمطوري بايثون الذين يعملون على لوحات تحليلات. Aspose.BarCode Cloud SDK for Python يوفر مكتبة قوية تبسط إنشاء الباركود ومعالجة الملفات في السحابة. في هذا الدليل ستتعلم تحويل JSON إلى XLSX باستخدام بايثون، بدءًا من إعداد SDK إلى إنشاء صور الباركود وتصدير جدول البيانات النهائي. في النهاية ستحصل على سكريبت قابل لإعادة الاستخدام جاهز لأعباء العمل الإنتاجية.

قبل أن تبدأ: المتطلبات المسبقة والتثبيت

لمتابعة هذا البرنامج التعليمي تحتاج إلى:

  • Python 3.7 أو أحدث مثبت على جهازك.
  • بيئة تطوير متكاملة أو محرر نصوص من اختيارك (VS Code، PyCharm، إلخ).
  • حساب Aspose Cloud مع Client Id و Client Secret.
  • اتصال إنترنت لاستدعاءات API السحابة.

قم بتثبيت الحزم المطلوبة باستخدام pip:

pip install aspose-barcode-cloud openpyxl

قم بتنزيل SDK من صفحة الإصدار الرسمية إذا كنت تفضل التثبيت اليدوي: تنزيل Aspose.BarCode Cloud SDK for Python.

قم بتكوين بيانات الاعتماد الخاصة بك قبل إجراء أي مكالمات API:

from asposebarcodecloud import Configuration

CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"

config = Configuration()
config.host = "https://api.aspose.cloud"
config.api_key["client_id"] = CLIENT_ID
config.api_key["client_secret"] = CLIENT_SECRET

مع جاهزية البيئة، يمكننا الانتقال إلى التنفيذ.

بناءه خطوة بخطوة: تحويل JSON إلى XLSX في بايثون

الخطوة 1: تحميل ملف JSON المصدر

اقرأ مصفوفة JSON التي تحتوي على البيانات التي تريد تصديرها.

import json

INPUT_JSON_PATH = "input.json"
with open(INPUT_JSON_PATH, "r", encoding="utf-8") as f:
    json_data = json.load(f)   # expects a list of dictionaries

الخطوة 2: إعداد المصنف وصف الرأس

إنشاء مصنف Excel باستخدام OpenPyXL وكتابة رؤوس الأعمدة.

from openpyxl import Workbook
from openpyxl.utils import get_column_letter

wb = Workbook()
ws = wb.active
ws.title = "Data"

columns = list(json_data[0].keys())
columns.append("BarcodeImage")          # extra column for the barcode
for col_idx, col_name in enumerate(columns, start=1):
    ws.cell(row=1, column=col_idx, value=col_name)

الخطوة 3: إنشاء صور الباركود

استخدم Aspose.BarCode Cloud لإنشاء باركود بصيغة PNG لكل سجل.
مرجع API لـ BarcodeApi.generate_barcode متاح في مرجع API.

from asposebarcodecloud import BarcodeApi, GenerateBarcodeRequest, EncodeBarcodeType, ApiClient
from asposebarcodecloud.rest import ApiException

barcode_api = BarcodeApi(ApiClient(config))

def generate_barcode_image(text: str,
                           barcode_type: EncodeBarcodeType = EncodeBarcodeType.CODE_128) -> bytes:
    request = GenerateBarcodeRequest(text=text, type=barcode_type, format="png")
    try:
        response = barcode_api.generate_barcode(request)
        return response.read()
    except ApiException as e:
        print(f"Error generating barcode for '{text}': {e}")
        raise

الخطوة 4: إدراج الباركودات في ورقة العمل

قم بتخزين الباركودات المتطابقة في الذاكرة لتجنب استدعاءات API المتكررة، ثم دمج الصورة.

import io
from openpyxl.drawing.image import Image as XLImage

barcode_cache = {}
for row_idx, record in enumerate(json_data, start=2):
    # write regular fields
    for col_idx, field_name in enumerate(columns[:-1], start=1):
        ws.cell(row=row_idx, column=col_idx, value=record.get(field_name, ""))

# barcode generation / caching
    barcode_source = str(record.get("code", f"row{row_idx}"))
    img_bytes = barcode_cache.get(barcode_source) or generate_barcode_image(barcode_source)
    barcode_cache[barcode_source] = img_bytes

img_stream = io.BytesIO(img_bytes)
    img = XLImage(img_stream)
    img.width, img.height = 150, 50          # optional size adjustment
    img_cell = f"{get_column_letter(len(columns))}{row_idx}"
    ws.add_image(img, img_cell)

الخطوة 5: ضبط حجم الأعمدة تلقائيًا وحفظ المصنف

إنهاء الملف وكتابته إلى القرص.

for col_idx in range(1, len(columns) + 1):
    column_letter = get_column_letter(col_idx)
    ws.column_dimensions[column_letter].width = 20

OUTPUT_XLSX_PATH = "output.xlsx"
wb.save(OUTPUT_XLSX_PATH)
print(f"Conversion complete. XLSX saved to '{OUTPUT_XLSX_PATH}'.")

مع هذه الخطوات يتم إكمال تحويل JSON إلى XLSX، وتحتوي كل صف الآن على صورة باركود تم إنشاؤها بواسطة Aspose.BarCode.

البرنامج الكامل لتحويل JSON إلى XLSX في بايثون - مثال كامل للشفرة

المثال التالي يوضح تنفيذ تحويل JSON إلى XLSX من البداية إلى النهاية باستخدام Aspose.BarCode Cloud SDK for Python.

import json
import os
import io
from typing import Dict, Any, List

import asposebarcodecloud
from asposebarcodecloud import (
    BarcodeApi,
    GenerateBarcodeRequest,
    EncodeBarcodeType,
    Configuration,
    ApiClient,
)
from asposebarcodecloud.rest import ApiException

from openpyxl import Workbook
from openpyxl.drawing.image import Image as XLImage
from openpyxl.utils import get_column_letter

# -------------------- Aspose.BarCode Cloud Setup --------------------
# Replace these placeholders with your actual Aspose Cloud credentials.
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"

config = Configuration()
config.host = "https://api.aspose.cloud"
config.api_key["client_id"] = CLIENT_ID
config.api_key["client_secret"] = CLIENT_SECRET

barcode_api = BarcodeApi(ApiClient(config))

def generate_barcode_image(text: str, barcode_type: EncodeBarcodeType = EncodeBarcodeType.CODE_128) -> bytes:
    """
    Calls Aspose.BarCode Cloud to generate a barcode image for the given text.
    Returns raw PNG bytes.
    """
    request = GenerateBarcodeRequest(
        text=text,
        type=barcode_type,
        format="png"
    )
    try:
        response = barcode_api.generate_barcode(request)
        # response is a file-like object; read its content.
        return response.read()
    except ApiException as e:
        print(f"Error generating barcode for '{text}': {e}")
        raise

# -------------------- JSON to XLSX Conversion --------------------
INPUT_JSON_PATH = "input.json"
OUTPUT_XLSX_PATH = "output.xlsx"

# Load JSON data (expects a list of dictionaries)
with open(INPUT_JSON_PATH, "r", encoding="utf-8") as f:
    json_data: List[Dict[str, Any]] = json.load(f)

if not isinstance(json_data, list):
    raise ValueError("JSON root must be an array of objects.")

# Prepare workbook
wb = Workbook()
ws = wb.active
ws.title = "Data"

# Determine column order from first record
columns = list(json_data[0].keys())
# Append a column for the barcode image
barcode_column_name = "BarcodeImage"
columns.append(barcode_column_name)

# Write header row
for col_idx, col_name in enumerate(columns, start=1):
    ws.cell(row=1, column=col_idx, value=col_name)

# Cache to avoid regenerating identical barcodes
barcode_cache: Dict[str, bytes] = {}

# Process each JSON record
for row_idx, record in enumerate(json_data, start=2):
    # Write regular fields
    for col_idx, field_name in enumerate(columns[:-1], start=1):
        value = record.get(field_name, "")
        ws.cell(row=row_idx, column=col_idx, value=value)

# Generate or retrieve barcode image for a specific field (e.g., "code")
    barcode_source = str(record.get("code", f"row{row_idx}"))
    if barcode_source in barcode_cache:
        img_bytes = barcode_cache[barcode_source]
    else:
        img_bytes = generate_barcode_image(barcode_source)
        barcode_cache[barcode_source] = img_bytes

# Insert barcode image into the last column of the current row
    img_stream = io.BytesIO(img_bytes)
    img = XLImage(img_stream)
    # Adjust image size (optional)
    img.width, img.height = 150, 50
    img_cell = f"{get_column_letter(len(columns))}{row_idx}"
    ws.add_image(img, img_cell)

# Auto‑size columns (basic heuristic)
for col_idx, _ in enumerate(columns, start=1):
    column_letter = get_column_letter(col_idx)
    ws.column_dimensions[column_letter].width = 20

# Save workbook
wb.save(OUTPUT_XLSX_PATH)

print(f"Conversion complete. XLSX saved to '{OUTPUT_XLSX_PATH}'.")

ملاحظة: يوضح مثال الشيفرة هذا الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث مسارات الملفات (input.json, output.xlsx, إلخ) لتطابق المواقع الفعلية للملفات، وتحقق من أن جميع الاعتمادات المطلوبة مثبتة بشكل صحيح، واختبر بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشكلات، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

تنفيذ نفس المهمة باستخدام cURL وREST API

إذا كنت تفضل نهج REST النقي، يمكنك تحقيق النتيجة نفسها باستخدام بعض أوامر cURL. تتطابق سير العمل مع تنفيذ Python: الحصول على رمز الوصول، تحميل ملف JSON، إنشاء الباركود، إنشاء ملف XLSX، وتنزيل النتيجة.

1. المصادقة والحصول على رمز وصول

curl -X POST "https://api.aspose.cloud/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

تحتوي الاستجابة على access_token الذي ستستخدمه في المكالمات اللاحقة.

2. تحميل ملف JSON المصدر إلى Aspose Cloud Storage

curl -X PUT "https://api.aspose.cloud/v3.0/storage/file/input.json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     --data-binary @input.json

3. إنشاء صورة باركود لقيمة عينة

curl -X POST "https://api.aspose.cloud/v3.0/barcode/generate" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "text": "SampleCode123",
           "type": "Code128",
           "format": "png"
         }' \
     -o barcode.png

4. تحويل JSON إلى XLSX باستخدام Aspose.Cells Cloud

curl -X POST "https://api.aspose.cloud/v3.0/cells/convert?format=xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"FileName":"input.json"}' \
     -o output.xlsx

5. تنزيل ملف XLSX الناتج

curl -X GET "https://api.aspose.cloud/v3.0/storage/file/output.xlsx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.xlsx

توضح هذه الأوامر كيفية إجراء تحويل JSON إلى XLSX نفسه دون كتابة أي شفرة. لمزيد من التفاصيل، راجع وثائق API الرسمية.

تكوين خيارات التحويل للحصول على نتائج مثالية

تقدم Aspose.BarCode Cloud عدة معلمات يمكنك تعديلها لتناسب مشروعك:

  • نوع الباركود - اختر من EncodeBarcodeType.CODE_128، EncodeBarcodeType.QR، EncodeBarcodeType.PDF_417، إلخ.
  • تنسيق الصورة - PNG هو الافتراضي، ولكن يمكنك طلب jpeg أو gif عن طريق تغيير حقل format.
  • حجم الصورة - اضبط img.width و img.height في البرنامج النصي للتحكم في الدقة.
  • عرض العمود - عدل ws.column_dimensions[column_letter].width لتناسب النص الأطول.

مثال على تغيير نوع الباركود وتنسيق الصورة:

def generate_barcode_image(text: str,
                           barcode_type: EncodeBarcodeType = EncodeBarcodeType.QR,
                           image_format: str = "jpeg") -> bytes:
    request = GenerateBarcodeRequest(
        text=text,
        type=barcode_type,
        format=image_format
    )
    response = barcode_api.generate_barcode(request)
    return response.read()

تحسين الأداء لمجموعات بيانات JSON الكبيرة

عند التعامل مع آلاف السجلات، ضع في اعتبارك هذه التحسينات:

  1. تدفق JSON بدلاً من تحميل الملف بالكامل - استخدم ijson للتكرار على السجلات دون الاحتفاظ بالقائمة الكاملة في الذاكرة.
  2. تخزين الباركود المتكرر مؤقتًا - قاموس barcode_cache في عينة الكود يمنع استدعاءات API المتكررة للقيم المتطابقة.
  3. تغيير حجم الصور بحكمة - تقليل حجم صور الباركود يقلل من استهلاك الذاكرة ويسرّع حفظ دفتر العمل.
  4. كتابة الصفوف على دفعات - يتيح OpenPyXL كتابة الصفوف دفعة واحدة؛ تجميع الكتابات يمكن أن يقلل من الحمل الزائد.

ستساعدك تطبيق هذه النصائح في الحفاظ على سرعة التحويل وكفاءته في استهلاك الذاكرة حتى مع مجموعات البيانات الضخمة.

الخاتمة

تحويل JSON إلى XLSX في بايثون يصبح بسيطًا عندما تستفيد من قوة Aspose.BarCode Cloud SDK for Python. يوضح هذا الدليل إعداد البيئة، وإنشاء الباركود، وإنشاء دفتر العمل، وتحسين الأداء، مما يمنحك أساسًا قويًا لبناء خطوط تقارير. تذكر أن الترخيص التجاري مطلوب للنشر في بيئات الإنتاج؛ يمكنك استكشاف خيارات التسعير على صفحة المنتج أو الحصول على ترخيص مؤقت من صفحة الترخيص المؤقت. مع الكود المقدم وتوصيات أفضل الممارسات، أنت جاهز لدمج وظيفة تصدير البيانات الموثوقة في تطبيقاتك.

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

  • كيف يمكنني تنفيذ تحويل JSON إلى XLSX في بايثون دون كتابة منطق الباركود الخاص بي؟
    استخدم Aspose.BarCode Cloud SDK لإنشاء الباركود تلقائيًا ودمجه مع OpenPyXL لإنشاء ملفات Excel، كما هو موضح في مثال الكود الكامل.

  • ما هي الطريقة الموصى بها للتعامل مع الحقول المفقودة في إدخال JSON؟
    الوصول إلى قيم القاموس باستخدام record.get("field_name", "") لتوفير سلسلة فارغة افتراضية، مما يمنع حدوث أخطاء وقت التشغيل أثناء تعبئة ورقة العمل.

  • هل هناك أي حدود لحجم ملف JSON الذي يمكنني معالجته؟
    لا توجد حدود صلبة لواجهة برمجة التطبيقات السحابية نفسها، ولكن بالنسبة للملفات الكبيرة جدًا يجب عليك تدفق JSON وتخزين الباركود مؤقتًا، كما هو موضح في قسم الأداء.

  • هل أحتاج إلى ترخيص منفصل لـ Aspose.Cells عند إنشاء ملف XLSX؟
    لا. يتم إنشاء ملف XLSX محليًا باستخدام OpenPyXL، لذا يتطلب فقط Aspose.BarCode Cloud SDK ترخيصًا للمكالمات السحابية.

اقرأ المزيد