تبدیل داده‌های خام JSON به گزارش‌های زیبا و قالب‌بندی‌شده XLSX یک نیاز مکرر برای توسعه‌دهندگان Python است که روی داشبوردهای تحلیلی کار می‌کنند. Aspose.BarCode Cloud SDK for Python یک کتابخانه قدرتمند ارائه می‌دهد که تولید بارکد و مدیریت فایل‌ها را در ابر ساده می‌کند. در این راهنما شما یاد خواهید گرفت که چگونه تبدیل JSON به XLSX را در Python انجام دهید، از تنظیم SDK تا تولید تصاویر بارکد و استخراج جدول نهایی. در پایان یک اسکریپت قابل استفاده مجدد خواهید داشت که برای بارهای کاری تولیدی آماده است.

قبل از شروع: پیش‌نیازها و نصب

برای دنبال کردن این آموزش به موارد زیر نیاز دارید:

  • Python 3.7 یا جدیدتر نصب شده بر روی ماشین شما.
  • یک IDE یا ویرایشگر متن به انتخاب شما (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

مرحله ۲: آماده‌سازی کتاب‌کار و ردیف سرعنوان

یک کتاب‌کار 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 است که در تماس‌های بعدی از آن استفاده خواهید کرد.

۲. بارگذاری فایل 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

۳. تولید یک تصویر بارکد برای مقدار نمونه

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 چندین پارامتر را ارائه می‌دهد که می‌توانید برای سازگار کردن با پروژه‌تان تنظیم کنید:

  • Barcode Type - از EncodeBarcodeType.CODE_128، EncodeBarcodeType.QR، EncodeBarcodeType.PDF_417 و غیره انتخاب کنید.
  • Image Format - PNG به‌صورت پیش‌فرض است، اما می‌توانید با تغییر فیلد format، jpeg یا gif درخواست کنید.
  • Image Size - برای کنترل وضوح، img.width و img.height را در اسکریپت تنظیم کنید.
  • Column Width - برای جا دادن متن طولانی‌تر، 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 را به صورت جریان (Stream) کنید - از ijson برای تکرار بر روی رکوردها بدون نگه داشتن کل لیست در حافظه استفاده کنید.
  2. کش (Cache) بارکدهای تکراری - دیکشنری 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 که می‌توانم پردازش کنم وجود دارد؟
    خود API ابری محدودیت سخت‌گیرانه‌ای ندارد، اما برای فایل‌های بسیار بزرگ باید JSON را به صورت استریم کنید و بارکدها را کش کنید، همان‌طور که در بخش عملکرد توضیح داده شده است.

  • آیا برای Aspose.Cells هنگام ایجاد فایل XLSX به یک لایسنس جداگانه نیاز دارم؟
    خیر. تولید XLSX به صورت محلی با OpenPyXL انجام می‌شود، بنابراین فقط Aspose.BarCode Cloud SDK برای تماس‌های ابری به لایسنس نیاز دارد.

بیشتر بخوانید