Объединение нескольких PDF документов в один файл является частой задачей при построении документооборотов или генерации отчетов. GroupDocs.Merger Cloud SDK for Node.js упрощает слияние PDF в Node.JS без необходимости работать с низкоуровневыми структурами PDF. В этом руководстве вы найдете пошаговую настройку, пошаговую реализацию, полный пример кода, эквивалентные вызовы cURL и рекомендации по производительности для больших или зашифрованных PDF.

Перед началом: Требования и установка

Прежде чем начать, убедитесь, что у вас есть следующее:

  • Node.js 14 или более поздней версии, установленный на вашей машине разработки.
  • Активный аккаунт GroupDocs Cloud с client ID и client secret.
  • Доступ к PDF‑файлам, которые вы хотите объединить, хранящимся в хранилище GroupDocs Cloud.

Установите SDK через npm и загрузите последнюю версию пакета:

npm install groupdocs-merger-cloud

Вы также можете получить SDK со страницы официального релиза: Скачать SDK. После установки вы готовы приступить к написанию кода.

Пошаговое руководство по объединению PDF в Node.JS

Шаг 1: Установите SDK и импортируйте необходимые классы

Сначала импортируйте классы, которые вам понадобятся для объединения PDF‑файлов.

const { MergeApi, MergeOptions, FileInfo, Configuration } = require("@groupdocs/merger-cloud");

Этот импорт предоставляет вам доступ к основному API, объектам конфигурации и дескрипторам файлов.

Шаг 2: Настройте свои учетные данные GroupDocs

Создайте объект конфигурации с вашими учетными данными клиента.

const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

Предоставление правильных учетных данных позволяет библиотеке аутентифицировать ваши запросы.

Шаг 3: Определите PDF‑файлы для объединения

Список PDF‑документов, которые вы хотите объединить. Этот шаг готовит вас к эффективному объединению PDF в Node.JS.

const filesToMerge = [
    new FileInfo({ filePath: "input1.pdf" }),
    new FileInfo({ filePath: "input2.pdf" })
];

Каждый FileInfo указывает на файл, хранящийся в вашем хранилище GroupDocs Cloud.

Шаг 4: Установить параметры слияния

Настройте место вывода и прикрепите список файлов к запросу на слияние.

const mergeOptions = new MergeOptions();
mergeOptions.fileInfos = filesToMerge;
mergeOptions.outputPath = "merged_output.pdf";

Эти настройки контролируют, как вы объединяете PDF в Node.JS и где будет сохранён результат.

Шаг 5: Выполнить операцию слияния

Создайте экземпляр API, вызовите метод merge и обработайте ответ.

const mergeApi = new MergeApi(config);

try {
    const result = await mergeApi.mergeDocuments(mergeOptions);
    console.log("Merge completed. Output file stored at:", result.path);
} catch (error) {
    console.error("Error during PDF merge:", error);
}

Асинхронный вызов возвращает путь к объединённому документу, если операция выполнена успешно.

Полный пример реализации объединения PDF в Node.JS

Следующий код демонстрирует полный рабочий процесс от конфигурации до обработки результата.

const { MergeApi, MergeOptions, FileInfo, Configuration } = require("@groupdocs/merger-cloud");

// Configure the SDK (replace with your actual credentials)
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

async function mergePdfFiles() {
    // Initialize the Merge API
    const mergeApi = new MergeApi(config);

// Define the PDF files to be merged (must exist in GroupDocs Cloud storage)
    const filesToMerge = [
        new FileInfo({ filePath: "input1.pdf" }),
        new FileInfo({ filePath: "input2.pdf" })
    ];

// Set merge options
    const mergeOptions = new MergeOptions();
    mergeOptions.fileInfos = filesToMerge;
    mergeOptions.outputPath = "merged_output.pdf";

try {
        // Perform the merge operation
        const result = await mergeApi.mergeDocuments(mergeOptions);
        console.log("Merge completed. Output file stored at:", result.path);
    } catch (error) {
        console.error("Error during PDF merge:", error);
    }
}

// Execute the merge
mergePdfFiles();

Примечание: Этот пример кода демонстрирует базовую функциональность. Прежде чем использовать его в вашем проекте, убедитесь, что обновили все пути к файлам и значения конфигурации в соответствии с вашей реальной средой, проверьте, что все необходимые зависимости правильно установлены, и тщательно протестируйте в вашей среде разработки. Если вы столкнётесь с какими‑либо проблемами, обратитесь к официальной документации или свяжитесь с командой поддержки для получения помощи.

Объединение PDF через REST API с использованием cURL

Если вы предпочитаете чисто REST‑подход, ту же операцию можно выполнить с помощью команд cURL.

Сначала получите токен доступа:

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

Загрузите исходные PDF‑файлы в ваше хранилище (замените YOUR_ACCESS_TOKEN токеном из предыдущего шага):

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/file/upload?path=input1.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/local/path/input1.pdf"

Повторите загрузку для input2.pdf. Затем запросите операцию слияния:

curl -X POST "https://api.groupdocs.cloud/v2.0/merger/merge" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfos": [
               {"filePath":"input1.pdf"},
               {"filePath":"input2.pdf"}
           ],
           "outputPath":"merged_output.pdf"
         }'

Наконец, загрузите объединённый файл:

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/download?path=merged_output.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o merged_output.pdf

Для полного списка конечных точек и параметров см. справку API.

Настройка параметров объединения

SDK предоставляет несколько параметров, позволяющих точно настроить процесс слияния:

  • outputPath - Путь назначения для объединённого PDF. Настройте его, чтобы контролировать, где будет сохранён результат.
  • fileInfos - Массив объектов FileInfo, определяющих исходные PDF и их порядок.

Вы также можете задать дополнительные свойства, такие как pages для объединения определённых диапазонов страниц или password для зашифрованных PDF. Обратитесь к официальной документации для полного списка настраиваемых полей.

Соображения по производительности при объединении PDF

При объединении больших или множества PDF‑файлов учитывайте следующие рекомендации:

  • Используйте async/await, чтобы избежать блокировки цикла событий, особенно для больших документов.
  • Пакетные загрузки: загружайте исходные PDF‑файлы параллельно перед вызовом слияния, чтобы снизить общую задержку.
  • Потоковая обработка: для чрезвычайно больших PDF рассмотрите возможность хранения промежуточных результатов в облачном хранилище и слияния их небольшими частями.
  • Зашифрованные PDF: указывайте пароли в объектах FileInfo; обработка зашифрованных файлов добавляет накладные расходы, поэтому по возможности сливайте их после расшифровки.

Применение этих практик помогает эффективно объединять PDF в Node.JS, минимизируя потребление памяти.

Вопросы, которые могут у вас возникнуть

  • Как объединить PDF‑файлы в Node.JS с помощью GroupDocs?
    Используйте GroupDocs.Merger Cloud SDK for Node.js для создания экземпляра MergeApi, настройки MergeOptions с вашими исходными PDF и вызова mergeDocuments. Полный пример кода в этом руководстве демонстрирует процесс.

  • Могу ли я объединять зашифрованные PDF-файлы в Node.JS?
    Да, SDK поддерживает объединение зашифрованных PDF. Укажите правильные пароли в объектах FileInfo перед вызовом mergeDocuments. См. официальную документацию для получения подробностей.

  • Какие варианты лицензирования доступны для GroupDocs.Merger?
    GroupDocs предлагает гибкие тарифные планы. Для тестирования вы можете запросить временную лицензию, чтобы оценить библиотеку перед покупкой полной подписки.

  • Где я могу найти больше примеров и поддержку?
    Дополнительные образцы доступны в репозитории GitHub. Для получения помощи посетите форум поддержки.

Дополнительное чтение