Unire più documenti PDF in un unico file è una necessità frequente quando si creano flussi di lavoro documentali o si generano report. GroupDocs.Merger Cloud SDK for Node.js semplifica l’unione di PDF in Node.JS senza doversi occupare delle strutture PDF a basso livello. Questa guida ti accompagna attraverso la configurazione, un’implementazione passo‑passo, un esempio di codice completo, chiamate cURL equivalenti e consigli sulle prestazioni per PDF di grandi dimensioni o crittografati.

Prima di iniziare: Requisiti e installazione

Prima di iniziare, assicurati di avere quanto segue:

  • Node.js 14 o versioni successive installato sulla tua macchina di sviluppo.
  • Un account GroupDocs Cloud attivo con client ID e client secret.
  • Accesso ai file PDF che desideri combinare, archiviati nello storage GroupDocs Cloud.

Installa l’SDK tramite npm e scarica l’ultima versione del pacchetto:

npm install groupdocs-merger-cloud

Puoi anche recuperare l’SDK dalla pagina di rilascio ufficiale: Download SDK. Dopo l’installazione, sei pronto per iniziare a programmare.

Guida passo-passo per unire PDF in Node.JS

Passo 1: Installa SDK e importa le classi necessarie

Per prima cosa, importa le classi di cui avrai bisogno per unire i PDF.

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

Questa importazione ti consente di accedere all’API principale, agli oggetti di configurazione e ai descrittori di file.

Passo 2: Configura le tue credenziali GroupDocs

Crea un oggetto di configurazione con le credenziali del client.

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

Fornire le credenziali corrette consente alla libreria di autenticare le tue richieste.

Passo 3: Definire i file PDF da unire

Elenca i documenti PDF che desideri combinare. Questo passaggio ti prepara per unire PDF in Node.JS in modo efficiente.

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

Ogni FileInfo punta a un file archiviato nel tuo storage GroupDocs Cloud.

Passo 4: Imposta le opzioni di unione

Configura la posizione di output e allega l’elenco dei file alla richiesta di merge.

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

Queste impostazioni controllano come unire PDF in Node.JS e dove verrà salvato il risultato.

Passo 5: Esegui l’operazione di unione

Crea l’istanza dell’API, chiama il metodo merge e gestisci la risposta.

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);
}

La chiamata asincrona restituisce il percorso del documento unito se l’operazione ha successo.

Esempio completo di implementazione per l’unione di PDF in Node.JS

Il codice seguente dimostra il flusso di lavoro completo dalla configurazione alla gestione del risultato.

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();

Nota: Questo esempio di codice dimostra la funzionalità principale. Prima di usarlo nel tuo progetto, assicurati di aggiornare tutti i percorsi dei file e i valori di configurazione per corrispondere al tuo ambiente reale, verifica che tutte le dipendenze richieste siano correttamente installate e testa accuratamente nel tuo ambiente di sviluppo. Se incontri problemi, consulta la documentazione ufficiale o contatta il team di supporto per assistenza.

Unire PDF tramite API REST usando cURL

Se preferisci un approccio REST puro, la stessa operazione può essere eseguita con comandi cURL.

Per prima cosa, ottieni un token di accesso:

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"}'

Carica i PDF di origine nel tuo storage (sostituisci YOUR_ACCESS_TOKEN con il token del passaggio precedente):

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"

Ripeti il caricamento per input2.pdf. Quindi richiedi l’operazione di unione:

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"
         }'

Infine, scarica il file unito:

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

Per un elenco completo di endpoint e parametri, consulta il riferimento API.

Configurazione delle opzioni di unione

L’SDK espone diverse opzioni che consentono di perfezionare il processo di unione:

  • outputPath - Percorso di destinazione per il PDF unito. Modifica questo per controllare dove viene memorizzato il risultato.
  • fileInfos - Un array di oggetti FileInfo che definiscono i PDF di origine e il loro ordine.

È possibile impostare anche proprietà aggiuntive come pages per unire intervalli di pagine specifici, o password per PDF crittografati. Consulta la documentazione ufficiale per l’elenco completo dei campi configurabili.

Considerazioni sulle prestazioni per l’unione di PDF

Quando si uniscono PDF di grandi dimensioni o numerosi, tenete a mente questi consigli:

  • Usa async/await per evitare di bloccare il ciclo di eventi, soprattutto per documenti di grandi dimensioni.
  • Caricamenti batch: carica i PDF di origine in parallelo prima di avviare l’unione per ridurre la latenza complessiva.
  • Elaborazione in streaming: per PDF estremamente grandi, considera di memorizzare i risultati intermedi nello storage cloud e di unirli in blocchi più piccoli.
  • PDF crittografati: fornisci le password negli oggetti FileInfo; l’elaborazione di file crittografati aggiunge overhead, quindi uniscili dopo la decrittazione quando possibile.

Applicare queste pratiche ti aiuta a unire PDF in Node.JS in modo efficiente, riducendo al minimo il consumo di memoria.

Domande che potresti avere

  • Come posso unire file PDF in Node.JS usando GroupDocs?
    Usa il GroupDocs.Merger Cloud SDK for Node.js per creare un’istanza MergeApi, configurare MergeOptions con i PDF di origine e chiamare mergeDocuments. L’esempio di codice completo in questa guida dimostra il processo.

  • Posso unire file PDF crittografati in Node.JS?
    Sì, l’SDK supporta l’unione di PDF crittografati. Fornisci le password corrette negli oggetti FileInfo prima di chiamare mergeDocuments. Consulta la documentazione ufficiale per ulteriori dettagli.

  • Quali sono le opzioni di licenza per GroupDocs.Merger?
    GroupDocs offre piani tariffari flessibili. Per i test, è possibile richiedere una licenza temporanea per valutare la libreria prima di acquistare un abbonamento completo.

  • Dove posso trovare più esempi e supporto?
    Esempi aggiuntivi sono disponibili nel repository GitHub. Per assistenza, visita il forum di supporto.

Ulteriori letture