استخراج تصاویر از آرشیوهای فشرده کار رایجی برای توسعه‌دهندگانی است که خطوط لوله رسانه‌ای می‌سازند. GroupDocs.Conversion Cloud SDK for Python یک API قدرتمند ارائه می‌دهد که تبدیل فرمت‌ها را بدون نیاز به نصب‌های محلی مدیریت می‌کند. در این راهنما ما تبدیل RAR به JPG در Python را گام به گام بررسی می‌کنیم، شامل تنظیمات، پیاده‌سازی کد، گزینه‌های cURL و ملاحظات عملکرد. در پایان یک اسکریپت قابل استفاده مجدد خواهید داشت که می‌تواند در هر پروژه Python یکپارچه شود.

پیش‌نیازها و راه‌اندازی

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

  • Python 3.7 یا بالاتر نصب شده بر روی ماشین توسعه شما.
  • یک حساب GroupDocs.Conversion Cloud (client ID و client secret).
  • دسترسی شبکه به نقاط انتهایی GroupDocs Cloud.

SDK را از طریق pip نصب کنید:

pip install groupdocs-conversion-cloud

اگر ترجیح می‌دهید، بسته SDK را دانلود کنید یا منبع را در GitHub مشاهده کنید: دانلود SDK.

در ادامه، اعتبارنامه‌های خود را پیکربندی کنید. قطعه کد زیر واردات مورد نیاز و بلوک پیکربندی را که مستقیماً از پیاده‌سازی مرجع گرفته شده است، نشان می‌دهد.

import groupdocs_conversion_cloud
from groupdocs_conversion_cloud import Configuration, ApiClient, ConversionApi
# Replace with your actual GroupDocs Conversion Cloud credentials
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

config = Configuration()
config.client_id = client_id
config.client_secret = client_secret

api_client = ApiClient(config)
conversion_api = ConversionApi(api_client)

پس از نصب SDK و تنظیم اعتبارها، آماده‌اید تا فرآیند تبدیل را آغاز کنید.

تبدیل RAR به JPG در پایتون: راهنمای گام به گام

مرحله 1: بارگذاری سند منبع

ابتدا مسیر آرشیو RAR ذخیره‌شده در فضای ذخیره‌سازی پیش‌فرض ابر را مشخص کنید.

from groupdocs_conversion_cloud import FileInfo

input_file_path = "sample.rar"  # Archive containing images
file_info = FileInfo(file_path=input_file_path)

مرحله ۲: تعریف گزینه‌های تبدیل JPG

یک شیء JpgConvertOptions ایجاد کنید تا کیفیت خروجی و تغییر اندازه اختیاری را کنترل کنید.

from groupdocs_conversion_cloud import JpgConvertOptions

jpg_options = JpgConvertOptions(
    quality=90,          # Quality range 0‑100
    # width=1024,        # Uncomment to resize width
    # height=768,        # Uncomment to resize height
)

مرحله 3: تنظیمات تبدیل

اطلاعات فایل، فرمت هدف، پوشه خروجی و گزینه‌ها را در یک نمونه ConvertSettings ترکیب کنید.

from groupdocs_conversion_cloud import ConvertSettings

output_folder = "converted_images/"
convert_settings = ConvertSettings(
    file_info=file_info,
    format="jpg",
    output_path=output_folder,
    options=jpg_options,
)

مرحله 4: اجرای درخواست تبدیل

درخواست را به سرویس ابری ارسال کنید و پاسخ را پردازش کنید.

from groupdocs_conversion_cloud import ConvertDocumentRequest

request = ConvertDocumentRequest(convert_settings)
conversion_result = conversion_api.convert_document(request)

print("Conversion completed. Generated files:")
for doc in conversion_result:
    print(f" - {doc.path}")

مرحله 5: (اختیاری) دانلود فایل‌های نتیجه

اگر به فایل‌های JPG به صورت محلی نیاز دارید، از StorageApi برای دانلود هر سند تولید شده استفاده کنید.

import os
download_api = groupdocs_conversion_cloud.StorageApi(api_client)

for doc in conversion_result:
    local_path = os.path.join("local_output", os.path.basename(doc.path))
    os.makedirs(os.path.dirname(local_path), exist_ok=True)
    download_request = groupdocs_conversion_cloud.DownloadFileRequest(
        path=doc.path,
        storage_name=None,
    )
    file_content = download_api.download_file(download_request)
    with open(local_path, "wb") as f:
        f.write(file_content)
    print(f"Downloaded {doc.path} to {local_path}")

با این مراحل، تبدیل RAR به JPG در Python را با استفاده از کتابخانه GroupDocs تکمیل کرده‌اید.

تبدیل RAR به JPG در پایتون - پیاده‌سازی کامل

مثال زیر برنامه کامل و آماده اجرا را نشان می‌دهد. این برنامه شامل تمام ایمپورت‌ها، پیکربندی، منطق تبدیل و مدیریت اختیاری دانلود است.

import os
import sys
import groupdocs_conversion_cloud
from groupdocs_conversion_cloud import (
    Configuration,
    ApiClient,
    ConversionApi,
    ConvertDocumentRequest,
    ConvertSettings,
    FileInfo,
    JpgConvertOptions,
)

# -------------------- Configuration --------------------
# Replace with your actual GroupDocs Conversion Cloud credentials
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

config = Configuration()
config.client_id = client_id
config.client_secret = client_secret

api_client = ApiClient(config)
conversion_api = ConversionApi(api_client)

# -------------------- Input / Output --------------------
# Input RAR file located in the default storage
input_file_path = "sample.rar"          # e.g., an archive containing images
# Output folder where JPG files will be saved (must end with a slash)
output_folder = "converted_images/"

# Ensure the output folder path ends with a slash for the API
if not output_folder.endswith("/"):
    output_folder += "/"

# -------------------- Conversion Settings --------------------
file_info = FileInfo(file_path=input_file_path)

# JPG conversion options – you can customize quality, page size, etc.
jpg_options = JpgConvertOptions(
    # Example: set quality to 90 (range 0‑100)
    quality=90,
    # Example: set width/height if you want to resize
    # width=1024,
    # height=768,
)

convert_settings = ConvertSettings(
    file_info=file_info,
    format="jpg",                # Target format
    output_path=output_folder,   # Destination folder in storage
    options=jpg_options,
    # storage_name can be omitted to use the default storage
)

# -------------------- Perform Conversion --------------------
try:
    request = ConvertDocumentRequest(convert_settings)
    conversion_result = conversion_api.convert_document(request)

# conversion_result is a list of ConvertedDocument objects
    print("Conversion completed. Generated files:")
    for doc in conversion_result:
        print(f" - {doc.path}")

except groupdocs_conversion_cloud.ApiException as e:
    print(f"API error: {e}")
    sys.exit(1)
except Exception as ex:
    print(f"Unexpected error: {ex}")
    sys.exit(1)

# -------------------- Optional: Download Result Files --------------------
# If you need to download the generated JPGs locally:
download_api = groupdocs_conversion_cloud.StorageApi(api_client)

for doc in conversion_result:
    local_path = os.path.join("local_output", os.path.basename(doc.path))
    os.makedirs(os.path.dirname(local_path), exist_ok=True)
    try:
        download_request = groupdocs_conversion_cloud.DownloadFileRequest(
            path=doc.path,
            storage_name=None,  # None = default storage
        )
        file_content = download_api.download_file(download_request)
        with open(local_path, "wb") as f:
            f.write(file_content)
        print(f"Downloaded {doc.path} to {local_path}")
    except Exception as dl_ex:
        print(f"Failed to download {doc.path}: {dl_ex}")

# -------------------- Cleanup --------------------
# No explicit cleanup required for the Cloud SDK; resources are managed by the service.

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید که مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روزرسانی کنید که با محیط واقعی شما مطابقت داشته باشد، اطمینان حاصل کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند، و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک با تیم پشتیبانی تماس بگیرید.

تبدیل RAR به JPG از طریق REST API با cURL

اگر ترجیح می‌دهید از روش خالص REST استفاده کنید، می‌توانید همان تبدیل را با دستورات cURL انجام دهید.

  1. دریافت یک توکن دسترسی (جایگزین مقادیر نگهدارنده با اعتبارهای خود):
curl -X POST "https://api.groupdocs.cloud/v2.0/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
  1. بارگذاری آرشیو RAR به ذخیره‌سازی پیش‌فرض:
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/sample.rar" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@/path/to/sample.rar"
  1. درخواست تبدیل به فرمت JPG:
curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "fileInfo": { "filePath": "sample.rar" },
        "outputPath": "converted_images/",
        "format": "jpg",
        "options": { "quality": 90 }
      }'
  1. فایل‌های JPG حاصل را دانلود کنید (برای هر فایلی که در پاسخ تبدیل فهرست شده است، تکرار کنید):
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/converted_images/image1.jpg" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o image1.jpg

برای دریافت فهرست کامل پارامترها و استفاده پیشرفته، به مرجع API مراجعه کنید.

تنظیمات دقیق تبدیل برای RAR به JPG

SDK چندین گزینه را ارائه می‌دهد که به شما امکان کنترل کیفیت و اندازه خروجی را می‌دهد. در ادامه دو تنظیم رایج که معمولاً تنظیم می‌شوند آورده شده است:

  • کیفیت - سطح فشرده‌سازی JPEG (0‑100) را تعیین می‌کند. مقادیر بالاتر تصویر واضح‌تری را با هزینهٔ حجم فایل بزرگ‌تر فراهم می‌آورند.
jpg_options = JpgConvertOptions(quality=90)
  • تغییر اندازه ابعاد - می‌توانید width و height را تنظیم کنید تا در طول تبدیل، تصاویر را مقیاس‌بندی کنید. این برای زمانی که به تصویرهای کوچک یا دارایی‌های با اندازه کاهش یافته نیاز دارید، مفید است.

برای ویژگی‌های اضافی مانند colorMode یا dpi به کلاس JpgConvertOptions مراجعه کنید.

بهینه‌سازی عملکرد استخراج دسته‌ای

هنگام پردازش تعداد زیادی آرشیو RAR بزرگ، نکات زیر را در نظر بگیرید:

  1. جریان به جای دانلود - از StorageApi برای جریان دادن فایل‌ها مستقیماً به حافظه در صورت امکان استفاده کنید تا بار I/O کاهش یابد.
  2. درخواست‌های موازی - چندین درخواست تبدیل را به‌صورت همزمان اجرا کنید (با رعایت محدودیت‌های نرخ API) تا از هسته‌های CPU موجود استفاده شود.
  3. تنظیم هوشمندانه کیفیت - کاهش کیفیت JPEG می‌تواند به‌طور چشمگیری زمان پردازش و پهنای باند را برای عملیات‌های انبوه کاهش دهد.
  4. استفاده مجدد از نمونه ConversionApi - یک شیء ConversionApi واحد ایجاد کنید و آن را در میان چندین فایل مجدداً استفاده کنید تا از هزینهٔ تکراری احراز هویت جلوگیری شود.

اعمال این استراتژی‌ها به حفظ خط لوله تبدیل RAR به JPG در پایتون سریع و بهینه در مصرف منابع کمک می‌کند.

نتیجه‌گیری نهایی

اتوماتیک‌سازی تبدیل RAR به JPG در پایتون با استفاده از GroupDocs.Conversion Cloud SDK for Python به سادگی انجام می‌شود. این کتابخانه پیچیدگی‌های مدیریت آرشیو و تولید تصویر را انتزاع می‌کند و به شما امکان می‌دهد بر منطق کسب‌وکار تمرکز کنید. به یاد داشته باشید گزینه‌های قیمت‌گذاری را در صفحه محصول بررسی کنید و قبل از استقرار در محیط تولید، یک مجوز ارزیابی موقت از صفحه مجوز موقت دریافت کنید. با کدها، مثال‌های cURL و نکات عملکردی ارائه‌شده، شما مجهز به ادغام استخراج تصویر قابل اعتماد در هر برنامه پایتون هستید.

سوالات متداول

  • چگونه می‌توانم تبدیل RAR به JPG را در پایتون انجام دهم؟
    از GroupDocs.Conversion Cloud SDK for Python استفاده کنید. این SDK یک API سطح‑بالا ارائه می‌دهد تا آرشیو RAR را بارگذاری کنید، گزینه‌های JPG را مشخص کنید و تصاویر تبدیل‌شده را با حداقل کد دریافت کنید.

  • آیا می‌توانم چندین فایل RAR را در یک دسته تبدیل کنم؟
    بله. بر روی فهرستی از مسیرهای آرشیو تکرار کنید و همان نمونه ConversionApi را دوباره استفاده کنید. برای هر اجرا مسیر output_path را تنظیم کنید تا نتایج منظم بمانند.

  • اگر آرشیو RAR خراب باشد چه می‌شود؟
    SDK یک ApiException شامل جزئیات خطا پرتاب می‌کند. استثنا را بگیرید، پیام را لاگ کنید و به‌صورت اختیاری فایل مشکل‌دار را نادیده بگیرید. کدهای خطای دقیق در مستندات API مستند شده‌اند.

  • کجا می‌توانم اطلاعات مجوزدهی را پیدا کنم؟
    جزئیات قیمت‌گذاری و مجوزدهی، از جمله یک مجوز ارزیابی موقت، در صفحه صفحه مجوز موقت موجود است.

مقالات مرتبط