Trasforma la conversione di fogli di calcolo in una singola riga di codice: Guida completa all'Aspose.Cells Cloud Convert API (.NET / Python / Java)

Nessuna installazione locale di Excel. Nessun server di conversione da gestire. Trasforma XLSX → PDF, Excel → CSV/JSON/immagini/HTML in semplici chiamate REST — e fai partire il tuo primo “convertitore di fogli di calcolo cloud” in circa tre minuti.

“Convert that spreadsheet to a different format” è una delle richieste più comuni nello sviluppo quotidiano:

• I team finanziari e legali vogliono un report PDF in sola lettura e resistente alla manomissione invece di un .xlsx che chiunque può modificare;
• I team di dati hanno bisogno di estrarre dati tabulari verso sistemi a valle come CSV / JSON;
• Le app web e mobile desiderano fogli di lavoro — e persino grafici — renderizzati direttamente in PNG / SVG;
• I portali vogliono frammenti puliti di HTML / HTML-Table da incorporare;
• Qualcuno deve normalizzare una pila di file .xls / .xlsx / .csv / .ods in un unico formato.

Le soluzioni tradizionali — un’installazione locale di Excel con macro, o un componente COM pesante sul tuo server — sono difficili da scalare e complicate da mantenere cross‑platform. Aspose.Cells Cloud sostituisce tutto ciò con una pura REST API: carica un file, ricevi indietro un file in un nuovo formato.

Questo post illustra le tre API di conversione esposte dal core ConversionController nel microservizio Aspose.Cells Cloud (source: src/Aspose.Cells.Cloud.MicroService/Controllers/ConversionController.cs), con esempi eseguibili in cURL, C# (.NET), Python e Java.

1. Cosa può fare la funzionalità Convert?

ConversionController è il controller dedicato alla conversione di formato / esportazione. Avvolge la conversione a livello di motore, ad alta fedeltà, in tre gruppi di API HTTP:

Nota di implementazione: le rotte di origine utilizzano il prefisso v{version}/cells con la versione API 4.0, quindi le chiamate live appaiono come https://api.aspose.cloud/v4.0/cells/....

La granularità della conversione va ben oltre “l’intero file”

Oltre a convertire un intero workbook, il controller può esportare un singolo elemento:

• Un foglio di lavoro specifico → PDF / immagine / CSV / JSON / HTML
• Un intervallo di celle (ad es. A1:C12) → PDF / immagine / CSV / JSON / HTML
• Una tabella specifica → PDF / immagine / CSV / JSON / HTML
• Un grafico specifico → PNG / JPEG / BMP / GIF / SVG / TIFF / EMF / PDF

Così non dovrai mai convertire un’intera cartella di lavoro da 50 MB solo per prendere un grafico — converti solo ciò di cui hai bisogno e risparmia larghezza di banda e potenza di calcolo.

2. Quali formati sono supportati?

Basandosi sul registro ExportData integrato nel controller, la matrice di conversione appare approssimativamente così:

In breve: conversioni spreadsheet-to-spreadsheet di ogni tipo, plus l’intera famiglia di output foglio di calcolo → PDF / immagine / dati web — tutto dietro un’unica interfaccia API.

3. Due cose di cui hai bisogno prima di iniziare

1. Registrati per un account gratuito sul Aspose Cloud Dashboard e crea un’Applicazione per ottenere un Client ID e un Client Secret (gli SDK scambiano questi per un JWT automaticamente — non è necessario creare manualmente le intestazioni di autenticazione).
2. Installa l’SDK per il linguaggio di tua scelta:

<!-- .NET -->
<PackageReference Include="Aspose.Cells-Cloud" Version="25.x" />

# Python
pip install asposecellscloud

<!-- Java (Maven) — note: NOT on Maven Central, so the Aspose repo below is required -->
<repositories>
    <repository>
        <id>AsposeJavaAPI</id>
        <name>Aspose Java API</name>
        <url>https://repository.aspose.cloud/repo/</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-cells-cloud</artifactId>
    <version>26.8</version>
</dependency>

Nessun SDK richiesto? Tutto è REST puro, quindi cURL funziona altrettanto bene (vedi sotto).

4. Scenario 1: Converti un file Excel locale online (l’intestazione Convert API)

Questo è PUT /v4.0/cells/convert/spreadsheet — l’API “Convert” di punta:
carica il tuo file locale nel corpo della richiesta, il server lo converte e restituisce il nuovo file in streaming. Nulla viene salvato nello storage cloud e non rimane alcuna copia di upload — perfetto per i momenti “just convert this for me”.

① cURL

# 1) First, get a token
curl -X POST "https://api.aspose.cloud/connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# 2) XLSX -> PDF
curl -X PUT "https://api.aspose.cloud/v4.0/cells/convert/spreadsheet?format=pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@Book1.xlsx" \
  -o Book1.pdf

Sostituisci format con csv, json, png, xlsx… e otterrai quel formato. Un parametro, un formato di output.

② C# / .NET

using Aspose.Cells.Cloud.SDK.Api;
using Aspose.Cells.Cloud.SDK.Request;

var cellsApi = new CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

var request = new ConvertSpreadsheetRequest(
    spreadsheet: "C:/invoices/Book1.xlsx",   // local file path
    format: "pdf");                          // target: pdf / csv / json / png ...

using Stream result = cellsApi.ConvertSpreadsheet(request); // converted file stream
using var outFile = File.Create("C:/invoices/Book1.pdf");
result.CopyTo(outFile);

// Even simpler: point the SDK at an output path and let it write the file
// cellsApi.ConvertSpreadsheet(request, "C:/invoices/Book1.pdf");

Hai bisogno di un lavoro batch? Inseriscilo in un ciclo su una directory e otterrai “converti l’intera cartella XLSX → PDF”.

③ Python

from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import ConvertSpreadsheetRequest
import os

instance = CellsApi(
    os.getenv('CellsCloudClientId'),
    os.getenv('CellsCloudClientSecret'))

# Local XLSX -> PDF, result written locally
instance.convert_spreadsheet(
    ConvertSpreadsheetRequest("Book1.xlsx", "pdf"),
    local_outpath="Book1.pdf")

# Other formats: just change the parameter — json / csv / xlsx / png ...

④ Java

import com.aspose.cloud.cells.api.CellsApi;
import com.aspose.cloud.cells.request.ConvertSpreadsheetRequest;
import java.io.File;

public class ConvertDemo {
    public static void main(String[] args) throws Exception {
        CellsApi api = new CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

ConvertSpreadsheetRequest req = new ConvertSpreadsheetRequest();
        req.setSpreadsheet("C:/invoices/Book1.xlsx");   // local file path
        req.setFormat("pdf");                           // target: pdf / csv / json / png ...

File out = api.convertSpreadsheet(req);         // converted result as a File
        out.renameTo(new File("C:/invoices/Book1.pdf"));
        System.out.println("Converted: " + out.getAbsolutePath());
    }
}

Quattro lingue, un’azione: fornisci un percorso + un parametro di formato → ottieni il file di destinazione. Questo è l’intero punto di vendita dell’Convert API — zero dipendenza da Excel sul lato chiamante, nessun modello, nessun componente COM.

5. Scenario 2: Converti direttamente un file archiviato nel cloud

Quando un file è già presente in Aspose Cloud Storage (o nel tuo storage di oggetti), non è necessario scaricare/caricare file di grandi dimensioni — la conversione avviene nel cloud, riducendo il trasferimento dei dati e migliorando le prestazioni su grandi cartelle di lavoro:

# cloud Book1.xlsx -> PDF, downloaded locally
curl -G "https://api.aspose.cloud/v4.0/cells/Book1.xlsx" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "format=pdf" \
  --data-urlencode "folder=Reports" \
  -o Book1.pdf

from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import ExportSpreadsheetAsFormatRequest

instance = CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

# Convert a cloud-stored workbook straight to PDF
instance.export_spreadsheet_as_format(
    ExportSpreadsheetAsFormatRequest("Book1.xlsx", format="pdf", folder="Reports"))

È possibile approfondire anche un singolo elemento — ad es. render “the 3rd chart on Sheet1” come PNG (variante cloud‑storage):

# chart -> PNG
curl -G "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Sheet1/charts/2" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "format=png" \
  -o chart.png

Endpoint cloud granulari a colpo d’occhio:

6. Scenario 3: SaveAs — scrivi il risultato nuovamente nello storage cloud

Quando vuoi che il file convertito conservato nuovamente nello storage cloud (anziché scaricato), usa PUT /v4.0/cells/{name}/saveas. È una soluzione naturale per l’automazione, ad esempio “esporta il report di oggi in PDF per l’archiviazione, ogni giorno”:

curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/saveas?format=pdf" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import SaveSpreadsheetAsRequest

instance = CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
instance.save_spreadsheet_as(
    SaveSpreadsheetAsRequest("Book1.xlsx", format="pdf", folder="Reports"))
# Result is saved directly in cloud storage; returns CellsCloudResponse(Code=200, Status="OK")

È possibile passare opzioni di salvataggio dettagliate tramite il corpo della richiesta SaveOptionsData e controllare nome file di output, archiviazione di output, caratteri personalizzati, regione/locale, password, ecc. tramite parametri di query — maggiori dettagli su questi nella sezione Dettagli tecnici qui sotto.

7. Altri endpoint “online convert” pronti all’uso

Oltre alle conversioni a livello di cartella di lavoro sopra riportate, il controller espone un set completo di endpoint dedicati local-file → specific-target (stessa procedura di upload del corpo della richiesta di Scenario 1), che sono più granulari e più economici in termini di larghezza di banda:

Ad esempio, “esporta solo questo intervallo come CSV per il sistema a valle”:

curl -X PUT "https://api.aspose.cloud/v4.0/cells/convert/range/csv" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "worksheet=Sheet1" \
  --data-urlencode "range=A1:C100" \
  -F "file=@data.xlsx" \
  -o data.csv

Questi endpoint utilizzano lo stesso schema di upload nel corpo come convert/spreadsheet. Nell’SDK .NET i casi chart hanno wrapper tipizzati che mappano a queste route v4.0 — ConvertChartToImage (convert/chart/image) e ConvertChartToPdf (convert/chart/pdf). Le varianti worksheet/*, range/* e table/* non hanno ancora un wrapper v4.0, quindi chiamale tramite REST puro esattamente come fa il cURL sopra.

8. Dettagli di ingegneria e gestione degli errori

Opzioni di conversione da conoscere (parametri di query)

• password — aprire cartelle di lavoro protette da password;
• fontsLocation / supporto per font personalizzati — mantenere corretti i glifi durante il rendering di PDF/immagini;
• adattamento automatico di righe/colonne e se stampare le intestazioni di riga/colonna (printHeadings), impostazione di regione/pagina (region), ecc.;
• lato output: outPath / outStorageName decidono dove il risultato viene salvato nello storage cloud.

Codici di errore (il contratto documentato dal controller)

Autenticazione

Tutti gli SDK si autenticano automaticamente con OAuth 2.0 client_credentials e un JWT; quando si utilizza cURL grezzo, chiamare /connect/token una volta prima (vedi Scenario 1, ① sopra).

9. Perché Aspose.Cells Cloud Convert?

• ✅ Zero dipendenze locali — nessun Office/Excel, nessun COM. Richiamabile da qualsiasi linguaggio e qualsiasi piattaforma (Linux, container, serverless);
• ✅ Rendering ad alta fedeltà — alimentato dal motore Aspose.Cells, quindi formule, grafici, stili e impaginazione vengono renderizzati con qualità professionale in PDF/immagini;
• ✅ Cloud-native — i file possono rimanere nel cloud durante la conversione per evitare l’invio di grandi payload; la conversione puramente online non richiede alcuna archiviazione cloud;
• ✅ Granularità flessibile — cartella di lavoro / foglio di lavoro / intervallo / tabella / grafico: converti esattamente la parte di cui hai bisogno;
• ✅ Una forma coerente tra gli SDK — gli esempi cURL, .NET, Python e Java corrispondono 1:1, così puoi letteralmente copiare lo schema che ti piace.

Inizia subito: registrati sul Aspose Cloud Dashboard, crea un’Applicazione, inserisci le tue credenziali in uno qualsiasi degli snippet sopra e eseguilo — avrai il tuo “convertitore Excel cloud” in pochi minuti.

Ti è stato utile? Metti una stella, aggiungi ai preferiti o condividilo — e raccontaci i tuoi casi d’uso di conversione di fogli di calcolo nei commenti.