تبدیل فایل‌های PDF به اسناد قابل ویرایش DOCX یک نیاز مکرر هنگام ساخت برنامه‌های Python متمرکز بر اسناد است. GroupDocs.Conversion Cloud SDK for Python به شما امکان می‌دهد تبدیل PDF به DOCX را در Python با قابلیت اطمینان بالا و مقیاس‌پذیری ابری انجام دهید. در این آموزش خواهید دید که چگونه SDK را تنظیم کنید، یک تبدیل ناهمزمان را اجرا کنید و عملکرد را برای بارهای کاری تولیدی بهینه‌سازی کنید.

تبدیل PDF به DOCX در پایتون در 5 مرحله

  1. پیکربندی اعتبارها و URL پایه: مقدار GROUPDOCS_CLIENT_ID، GROUPDOCS_CLIENT_SECRET و URL پایه API را تنظیم کنید.

    import os
CLIENT_ID = os.getenv("GROUPDOCS_CLIENT_ID", "YOUR_CLIENT_ID")
CLIENT_SECRET = os.getenv("GROUPDOCS_CLIENT_SECRET", "YOUR_CLIENT_SECRET")

  2. مقداردهی اولیهٔ مشتری API: یک شیء Configuration ایجاد کنید، سپس یک ApiClient و یک نمونهٔ ConvertApi ایجاد کنید.

from groupdocs_conversion_cloud import Configuration, ApiClient, ConvertApi
config = Configuration()
config.api_base_url = "https://api.groupdocs.cloud"
config.client_id = CLIENT_ID
config.client_secret = CLIENT_SECRET
api_client = ApiClient(config)
convert_api = ConvertApi(api_client)   # See API reference: [ConvertApi](https://reference.groupdocs.cloud/conversion/)
  1. تعریف تنظیمات تبدیل: مسیر فایل PDF منبع را در ذخیره‌سازی ابری مشخص کنید، فرمت هدف را به docx تنظیم کنید و به‌صورت اختیاری مسیر خروجی را تعیین کنید.
from groupdocs_conversion_cloud import ConvertSettings
settings = ConvertSettings()
settings.file_path = "input.pdf"
settings.format = "docx"
settings.output_path = "output.docx"
  1. اجرای تبدیل ناهمزمان: متد async را فراخوانی کنید و منتظر پاسخی باشید که شامل URL دانلود است.
import asyncio
async def run_conversion():
    response = await convert_api.convert_document_async(settings)
    return response.url
download_url = asyncio.run(run_conversion())
  1. نتیجه را دانلود کنید و پاک‌سازی کنید: فایل DOCX را از URL به صورت جریان دریافت کنید و کلاینت را ببندید.
    import requests
download_resp = requests.get(download_url, stream=True)
download_resp.raise_for_status()
with open("output.docx", "wb") as out_file:
    for chunk in download_resp.iter_content(chunk_size=8192):
        if chunk:
            out_file.write(chunk)
api_client.close()

مثال کامل کد: تبدیل ناهمزمان PDF به DOCX در پایتون

این مثال نشان می‌دهد که چگونه می‌توان تبدیل ناهمزمان PDF به DOCX را با استفاده از GroupDocs.Conversion Cloud SDK for Python انجام داد.

import asyncio
import os
import requests
from groupdocs_conversion_cloud import (
    ConvertApi,
    ConvertSettings,
    Configuration,
    ApiClient
)

# Replace with your actual credentials or set them as environment variables
CLIENT_ID = os.getenv("GROUPDOCS_CLIENT_ID", "YOUR_CLIENT_ID")
CLIENT_SECRET = os.getenv("GROUPDOCS_CLIENT_SECRET", "YOUR_CLIENT_SECRET")

async def convert_pdf_to_docx():
    # Configuration
    config = Configuration()
    config.api_base_url = "https://api.groupdocs.cloud"
    config.client_id = CLIENT_ID
    config.client_secret = CLIENT_SECRET

# API client and Convert API instance
    api_client = ApiClient(config)
    convert_api = ConvertApi(api_client)

# Conversion settings
    settings = ConvertSettings()
    settings.file_path = "input.pdf"          # source file in GroupDocs Cloud storage
    settings.format = "docx"                  # target format
    settings.output_path = "output.docx"      # optional: path where the result will be stored

try:
        # Asynchronous conversion request
        # The SDK provides an async method that returns a response containing a download URL
        response = await convert_api.convert_document_async(settings)

# Download the converted DOCX file using the provided URL
        download_url = response.url
        download_resp = requests.get(download_url, stream=True)
        download_resp.raise_for_status()
        with open("output.docx", "wb") as out_file:
            for chunk in download_resp.iter_content(chunk_size=8192):
                if chunk:
                    out_file.write(chunk)

print("Conversion completed successfully. File saved as output.docx")
    finally:
        # Cleanup resources
        api_client.close()

if __name__ == "__main__":
    asyncio.run(convert_pdf_to_docx())

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

تبدیل PDF به DOCX از طریق REST API با استفاده از cURL

می‌توانید همان نتیجه را با تماس‌های خام HTTP به دست آورید. در ادامه دستورات cURL که جریان کار تبدیل ناهمزمان را تکرار می‌کنند، آمده‌اند.

  1. دریافت توکن دسترسی
curl -X POST "https://api.groupdocs.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 است.

  1. بارگذاری PDF منبع
curl -X POST "https://api.groupdocs.cloud/v2.0/storage/file/upload?path=input.pdf" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -F "file=@/path/to/local/input.pdf"
  1. شروع تبدیل ناهمزمان
curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "filePath": "input.pdf",
           "outputPath": "output.docx",
           "format": "docx"
         }'

پاسخ شامل فیلد url برای فایل DOCX حاصل است.

  1. دانلود DOCX تبدیل‌شده
curl -L "https://api.groupdocs.cloud/v2.0/storage/file/download?path=output.docx" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -o output.docx

برای جزئیات بیشتر، به مستندات رسمی API مراجعه کنید.

نصب و پیکربندی GroupDocs.Conversion Cloud SDK برای Python

pip install groupdocs-conversion-cloud

همچنین می‌توانید بسته را به‌صورت مستقیم از صفحه انتشار دانلود کنید: دانلود GroupDocs.Conversion Cloud SDK برای Python

پیش‌نیازها:

  • Python 3.7 یا جدیدتر
  • شناسهٔ مشتری و رمز عبور معتبر GroupDocs (در حساب GroupDocs شما موجود است)

پس از نصب، متغیرهای محیطی مورد نیاز را تنظیم کنید یا اعتبارنامه‌ها را مستقیماً در کد خود همان‌طور که در مراحل بالا نشان داده شده است، پاس دهید.

ویژگی‌های کلیدی GroupDocs.Conversion Cloud برای تبدیل PDF به DOCX

  • پردازش ناهمزمان - فراخوانی‌های تبدیل بدون مسدود کردن اجازه می‌دهند برنامه شما پاسخگو بماند.
  • یکپارچه‌سازی ذخیره‌سازی ابری - فایل‌ها از ذخیره‌سازی GroupDocs Cloud خوانده و در آن نوشته می‌شوند بدون نیاز به I/O محلی.
  • دقت فرمت - خروجی DOCX چیدمان، قلم‌ها و تصاویر را از PDF اصلی حفظ می‌کند.
  • معماری مقیاس‌پذیر - سرویس بارهای کاری با حجم بالا را مدیریت می‌کند و برای کارهای دسته‌ای یا میکروسرویس‌ها مناسب است.
  • مرجع جامع API - اسناد جزئی برای هر کلاس و متد در مرجع API موجود است.

تنظیمات تبدیل: گزینه‌ها برای PDF به DOCX

  • file_path - مسیر فایل PDF منبع در ذخیره‌سازی ابری.
    settings.file_path = "input.pdf"
  • format - فرمت هدف؛ برای اسناد Word از "docx" استفاده کنید.
    settings.format = "docx"
  • output_path - مسیر اختیاری که فایل تبدیل‌شده در آن ذخیره می‌شود.
    settings.output_path = "output.docx"
  • load_options - گزینه‌های پیشرفته بارگذاری PDF (مثلاً رمز عبور، بازه صفحه) می‌توانند از طریق PdfLoadOptions تنظیم شوند. برای فهرست کامل به مستندات مراجعه کنید.

ملاحظات عملکرد برای تبدیل ناهمزمان PDF به DOCX

  • استفاده از تماس‌های Async - استفاده از convert_document_async مسدودسازی رشته‌ها را کاهش داده و توان پردازشی را بهبود می‌بخشد.
  • دوباره استفاده از ApiClient - یک نمونه ApiClient را برای طول عمر کل برنامه ایجاد کنید تا از تکرار handshake‌ها جلوگیری شود.
  • بارگذاری جریان دانلودها - مثال فایل DOCX را در قطعات ۸ KB جریان می‌دهد و مصرف حافظه را پایین نگه می‌دارد.
  • پردازش دسته‌ای چندین فایل - برای تبدیل انبوه، چندین کار async را در صف قرار داده و با asyncio.gather منتظر بمانید.

بهترین شیوه‌ها برای تبدیل سریع PDF به DOCX در پایتون

  • اعتبارنامه‌ها را به‌صورت ایمن ذخیره کنید؛ هرگز به‌صورت سخت‌کد نشده نگهداری نکنید.
  • وجود فایل PDF منبع را قبل از فراخوانی API تأیید کنید.
  • از متغیرهای محیطی برای GROUPDOCS_CLIENT_ID و GROUPDOCS_CLIENT_SECRET استفاده کنید.
  • پاسخ تبدیل را برای خطاها نظارت کنید و منطق retry را برای مشکلات موقت شبکه پیاده‌سازی کنید.
  • URL دانلود و مدت زمان تبدیل را برای حسابرسی عملکرد ثبت کنید.

نتیجه‌گیری

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

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

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

  • چه اتفاقی می‌افتد اگر PDF منبع دارای رمز عبور باشد؟
    مقدار password را در PdfLoadOptions داخل ConvertSettings تنظیم کنید. SDK قبل از تبدیل، فایل را رمزگشایی می‌کند. برای سینتکس دقیق به مستندات مراجعه کنید.

  • آیا می‌توانم تبدیل را داخل یک کانتینر Docker اجرا کنم؟
    بله. SDK را با pip install groupdocs-conversion-cloud داخل تصویر Docker خود نصب کنید، متغیرهای محیطی را پیکربندی کنید و اسکریپت async یکسان را اجرا کنید. این کار وابستگی‌ها را ایزوله می‌کند و به راحتی مقیاس‌پذیر است.

  • آیا راهی برای نظارت بر سرعت تبدیل PDF به DOCX در پایتون وجود دارد؟
    زمان سپری شده بین فراخوانی ناهمزمان و تکمیل دانلود را اندازه‌گیری کنید. SDK به‌صورت آنی یک url برمی‌گرداند؛ زمان واقعی پردازش در مدت زمانی که فایل در آن URL در دسترس می‌شود، منعکس می‌شود.

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