Approfondimento: Modelli avanzati con l’Aspose.Cells Cloud Management API

Sai come creare una cartella di lavoro, rinominare un foglio e comprimere un file. Ma ManagementController ha strumenti più affilati nascosti in bella vista — un dump JSON strutturale completo di una cartella di lavoro, ispezione delle celle unite, accettazione delle revisioni e il modello di creazione basato su template che trasforma lo styling in una preoccupazione a una riga. È qui che la manutenzione smette di essere “cliccare su Excel” e inizia a diventare igiene programmatica del workbook.

In Part 1 abbiamo coperto i 15 endpoint con guide chiare. Questo post è per le situazioni che realmente creano problemi in produzione:

È necessario auditare un workbook prima di elaborarlo — contiene tabelle pivot, grafici, regioni unite che potrebbero bloccare il tuo codice?
È necessario accettare le modifiche tracciate su centinaia di file prima che entrino nella tua pipeline di archiviazione.
Vuoi creare un sistema di templating in cui diversi tenant ottengono output brandizzati differenti senza scrivere codice di stile.
È necessario ispezionare le regioni di celle unite per evitare di scrivere dati al loro interno (o per comprendere il layout di un workbook che non hai creato).
Vuoi concatenare crea → struttura → modifica → comprimi in una singola fabbrica di workbook.

Ogni esempio qui sotto è eseguibile. Il codice è in cURL; le stesse chiamate corrispondono 1:1 ai SDK .NET, Python e Java.

1. Ottenere la struttura completa di una cartella di lavoro come JSON

PUT /v4.0/cells/spreadsheet/structure (locale) e GET /v4.0/cells/{name}/structure (remoto) restituiscono un unico documento JSON che descrive tutto ciò che il motore conosce sulla cartella di lavoro: fogli di lavoro, tabelle, tabelle pivot, grafici, forme, regioni di celle unite e altro.

Locale

curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/structure" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mystery_workbook.xlsx"

Remoto

curl -X GET "https://api.aspose.cloud/v4.0/cells/mystery_workbook.xlsx/structure?folder=uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Cosa ottieni

{
  "FileName": "mystery_workbook.xlsx",
  "FileFormat": "Xlsx",
  "Worksheets": [
    {
      "Name": "Sheet1",
      "Type": "Worksheet",
      "Tables": [{ "Name": "SalesData", "Range": "A1:D120" }],
      "PivotTables": [{ "Name": "Pivot1", "Range": "F1:H20" }],
      "Charts": [{ "Name": "Chart1", "Type": "Column" }],
      "MergedCells": [
        { "StartRow": 0, "StartColumn": 0, "EndRow": 0, "EndColumn": 3 }
      ]
    }
  ]
}

Perché è importante

Validazione preliminare. Prima di eseguire le importazioni di DataProcessingController su una cartella di lavoro, chiama structure per verificare che il foglio di lavoro e la tabella di destinazione esistano effettivamente.
Scoperta del layout. Lavori con una cartella di lavoro che non hai creato? structure ti dice esattamente cosa contiene senza scaricarla e armeggiare in Excel.
Rendering dell’interfaccia utente. Guida un selettore di foglio di lavoro / tabella / grafico nella tua app direttamente dalla risposta di structure.

2. Ispezione delle regioni di celle unite

Le celle unite sono i killer silenziosi dell’automazione dei fogli di calcolo — scrivere in una regione unita può sovrascrivere silenziosamente l’intera area o generare errori criptici. ManagementController espone due endpoint per interrogarle.

Foglio di lavoro locale

curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/mergedcells?worksheet=Sheet1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@my_workbook.xlsx"

Foglio di lavoro remoto

curl -X GET "https://api.aspose.cloud/v4.0/cells/my_workbook.xlsx/worksheets/Sheet1/mergedcells?folder=uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Risposta

[
  { "StartRow": 0, "StartColumn": 0, "EndRow": 0, "EndColumn": 3 },
  { "StartRow": 5, "StartColumn": 1, "EndRow": 7, "EndColumn": 1 }
]

Ogni voce è un CellArea — un rettangolo nelle coordinate di riga/colonna. La prima regione sopra è un’intestazione unita da A1–D1; la seconda è un’unione verticale in B6–B8.

Usalo per evitare le mine antiuomo

Prima di scrivere dati in un foglio di lavoro (tramite l’importazione di CellsController o DataProcessingController), chiama questo endpoint e filtra tutti i valori startcell che ricadono in un’area unita. Oppure, al contrario, utilizza le regioni unite per scoprire le righe di intestazione e i titoli di sezione in modo programmatico.

3. Accettare le modifiche tracciate (revisioni)

Quando i collaboratori attivano “Track Changes” in Excel, ogni modifica diventa una revisione — una modifica in sospeso con autore, timestamp e stato di accettazione/rifiuto. Se il tuo pipeline elabora tali file e ha bisogno di versioni pulite e finalizzate, hai due opzioni:

Locale: PUT /v4.0/cells/spreadsheet/accept-all-revisions
Remoto: PUT /v4.0/cells/{name}/accept-all-revisions

Locale

curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/accept-all-revisions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@collaborative_draft.xlsx" \
  --output finalized.xlsx

Remoto

curl -X PUT "https://api.aspose.cloud/v4.0/cells/collaborative_draft.xlsx/accept-all-revisions?folder=drafts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --output finalized.xlsx

Dopo questa chiamata, il documento non mostra più le marcature di modifiche tracciate. Tutte le modifiche vengono incorporate come se fossero state digitate direttamente nella versione finale.

Flusso di lavoro di massa

Combina con le API di elencazione dei file sul tuo provider di storage per elaborare ogni file in una cartella:

for name in $(list_files_in drafts/); do
  curl -X PUT "https://api.aspose.cloud/v4.0/cells/$name/accept-all-revisions?folder=drafts" \
    -H "Authorization: Bearer $TOKEN"
done

(Il codice di produzione reale userebbe l’SDK e parallelizzerebbe con async/await — la chiamata REST è identica.)

4. Creazione guidata da template su larga scala

Il parametro template su spreadsheet/create è più di una semplice comodità — è la base di un sistema di templating. Il server carica la cartella di lavoro modello, ne copia il tema, gli stili, gli intervalli denominati e qualsiasi tabella preformattata, e restituisce una nuova cartella di lavoro che puoi immediatamente popolare con i dati tramite DataProcessingController/import/data.

Modello: un modello per tenant

Archivia i modelli nello storage cloud in un percorso basato sul tenant:

templates/tenant_acme/invoice.xlsx
templates/tenant_globex/invoice.xlsx
templates/tenant_initech/invoice.xlsx

Quando il sistema di un inquilino genera una fattura:

# 1) Create from tenant template
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/create\
?format=xlsx\
&template=templates/tenant_acme/invoice.xlsx" \
  -H "Authorization: Bearer $TOKEN" \
  --output blank_acme.xlsx

# 2) Hydrate with this invoice's line items
curl -X PUT "https://api.aspose.cloud/v4.0/cells/import/data/json\
?worksheet=Items\
&startcell=A10\
&insert=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@blank_acme.xlsx" \
  -F "file=@line_items.json" \
  --output invoice_ACME_2026_09_001.xlsx

Ogni tenant ottiene un output pixel‑perfect nel proprio brand — zero logica di styling nel tuo codice.

Modello: fabbrica di report

Un lavoro notturno deve produrre 30 report regionali, tutti con lo stesso layout ma con dati diversi:

for region in north south east west ...; do
  create(template=regional_template.xlsx) |
  import(data=region_$region.csv, worksheet=Data, startcell=A2) |
  compress(level=6) |
  save("reports/2026/09/$region.xlsx")
done

Ogni fase del pipe è una chiamata API. L’intera fabbrica si adatta a un ciclo shell.

5. Compressione con intento

PUT /v4.0/cells/spreadsheet/compress?level=N accetta qualsiasi livello da 0 a 9. Scegliere il livello giusto è una piccola decisione che ha effetti a valle.

Level	Caso d’uso tipico
0	Debug — output della cartella di lavoro senza alcuna compressione
1–3	Pipeline quasi in tempo reale in cui il costo della CPU è più importante della dimensione
4–6	Raccomandazione predefinita. Buona compressione per una CPU modesta.
7–9	Archiviazione, allegati email, deliverable — la dimensione è più importante della velocità

Una compressione di livello 6 su un file XLSX da 30 MB di solito si aggira intorno a 8–12 MB. Il livello 9 spesso elimina un altro 10–15 %, a circa il doppio del costo CPU. Per la maggior parte delle app, level=6 è il punto ottimale.

6. Riparazione: cosa fa realmente

PUT /v4.0/cells/spreadsheet/repair è intenzionalmente semplice — nessun parametro, nessuna configurazione. Sotto il cofano, fa:

Analizza la cartella di lavoro tramite il lettore rigoroso del motore.
Scarta le parti strutturalmente non valide (relazioni orfane, XML malformato, riferimenti di cella non validi).
Ri-serializza in un nuovo contenitore XLSX.

Il risultato è un file che si apre correttamente in Excel. Ciò che non può correggere: la corruzione a livello di dati (una cella il cui valore è #REF! a causa di una formula rotta), immagini perse (se il flusso dell’immagine è corrotto) o macro VBA perse (se il vbaProject.bin non è leggibile). Ma per l'80 % dei casi — “Excel dice che questo file è corrotto e offre di ripararlo” — questo endpoint esegue la stessa riparazione, lato server, senza un’interfaccia grafica.

Quando eseguire la riparazione

Durante l’ingestione. Se la tua app accetta caricamenti da parte degli utenti, esegui repair prima di qualsiasi altra elaborazione. Il costo è una chiamata extra, ma previene errori a catena più avanti nella pipeline.
In caso di errori di esportazione. Se una conversione a valle (ConversionController) fallisce con un errore criptico, esegui prima repair, quindi riprova la conversione.

7. Modelli di integrazione

Pattern: la fabbrica di cartelle di lavoro

Combina tutte le funzionalità di ManagementController in un unico endpoint factory nella tua app:

POST /api/reports/{tenantId}
  1. Create from template: templates/{tenantId}/report.xlsx
  2. Import data into the "Data" sheet starting at A2
  3. Rename "Sheet1" → "Cover"
  4. Accept all revisions (in case template had tracked changes)
  5. Compress level 6
  6. Return final XLSX

Ogni passaggio è una chiamata API a ManagementController o DataProcessingController. Il tuo endpoint è un orchestratore leggero.

Modello: audit-before-process

Prima di eseguire operazioni costose a livello di cella:

[1] GET {name}/structure            # understand what's inside
[2] GET {name}/worksheets/X/mergedcells  # know where NOT to write
[3] DataProcessing/...              # run the real work

Le due chiamate di ispezione costano quasi nulla, ma impediscono i fallimenti costosi da debug che derivano dallo scrivere in regioni unite o dal puntare a tabelle non esistenti.

8. Considerazioni sulle prestazioni

structure è economico. Scorre i metadati, non il contenuto delle celle. Sicuro da chiamare su cartelle di lavoro grandi.
mergedcells è economico. Stessa ragione.
compress è legato alla CPU. Livelli più alti costano di più. Usa il livello 6 come predefinito a meno che tu non abbia un motivo per aumentare.
repair è una ricostruzione completa. Più costoso di compress. Eseguilo durante l’ingestione, non ad ogni richiesta.
accept-all-revisions scala con il numero di revisioni. Centinaia di revisioni in un file vanno bene; decine di migliaia richiederanno un attimo.
Le varianti remote battono i round‑trip locali. Quando i file sono già nello storage cloud, GET {name}/structure evita di scaricare il file sul tuo computer solo per ispezionarlo.

9. Risoluzione dei problemi comuni

Symptom	Cause	Fix
`400` on `add/worksheet`	Il nome del foglio esiste già o è vuoto	Scegli un nome univoco, oppure lascia che il server ne assegni uno automaticamente
`400` on `rename/worksheet`	`sourceName` non corrisponde a nessun foglio esistente	I nomi sono sensibili al maiuscolo/minuscolo; chiama `worksheets` prima per elencarli
`500` on `compress` with `level=10`	Il livello deve essere compreso tra 0 e 9	Usa `level=9` per la massima compressione
`repair` returns a file that still won’t open	La corruzione è nello stream immagine/VBA, non nell’XML strutturale	`repair` non può correggere la corruzione a livello di dati; chiedi all’utente di fornire un’esportazione pulita
`structure` returns empty `Worksheets` array	Il file caricato non è affatto una cartella di lavoro valida	Verifica l’estensione e il contenuto del file; esegui prima `repair`
`accept-all-revisions` is a no-op	La cartella di lavoro non ha il tracciamento abilitato	Va bene — nessuna revisione significa che non c’è nulla da accettare
`mergedcells` returns empty array	Nessuna area unita nel foglio di lavoro	Usa questo segnale per scrivere in modo sicuro ovunque

10. Mettere tutto insieme

Gli endpoint di ManagementController sono individualmente piccoli. Il loro potere deriva dalla composizione:

Crea una cartella di lavoro da un modello → importa dati tramite DataProcessingController → rinomina fogli → comprimi → consegna. Questo è un pipeline SaaS completo per report in cinque chiamate HTTP.
Structure + mergedcells + cells → uno strato di ispezione che comprende qualsiasi cartella di lavoro che gli lanci, senza Excel.
Ripara all’ingestione → accept-all-revisions → il resto della tua pipeline vede solo cartelle di lavoro pulite e finalizzate.

Non ti serve una server farm. Non ti serve Excel installato. Ti serve curl e un piano.

Approfondimento: Modelli avanzati con l’Aspose.Cells Cloud Management API#

1. Ottenere la struttura completa di una cartella di lavoro come JSON#

Locale#

Remoto#

Cosa ottieni#

Perché è importante#

2. Ispezione delle regioni di celle unite#

Foglio di lavoro locale#

Foglio di lavoro remoto#

Risposta#

Usalo per evitare le mine antiuomo#

3. Accettare le modifiche tracciate (revisioni)#

Locale#

Remoto#

Flusso di lavoro di massa#

4. Creazione guidata da template su larga scala#

Modello: un modello per tenant#

Modello: fabbrica di report#

5. Compressione con intento#

6. Riparazione: cosa fa realmente#

Quando eseguire la riparazione#

7. Modelli di integrazione#

Pattern: la fabbrica di cartelle di lavoro#

Modello: audit-before-process#

8. Considerazioni sulle prestazioni#

9. Risoluzione dei problemi comuni#

10. Mettere tutto insieme#

Approfondimento: Modelli avanzati con l’Aspose.Cells Cloud Management API

1. Ottenere la struttura completa di una cartella di lavoro come JSON

Locale

Remoto

Cosa ottieni

Perché è importante

2. Ispezione delle regioni di celle unite

Foglio di lavoro locale

Foglio di lavoro remoto

Risposta

Usalo per evitare le mine antiuomo

3. Accettare le modifiche tracciate (revisioni)

Locale

Remoto

Flusso di lavoro di massa

4. Creazione guidata da template su larga scala

Modello: un modello per tenant

Modello: fabbrica di report

5. Compressione con intento

6. Riparazione: cosa fa realmente

Quando eseguire la riparazione

7. Modelli di integrazione

Pattern: la fabbrica di cartelle di lavoro

Modello: audit-before-process

8. Considerazioni sulle prestazioni

9. Risoluzione dei problemi comuni

10. Mettere tutto insieme