Le API di SharePoint sono strumenti essenziali per sviluppare soluzioni personalizzate, integrazioni e applicazioni all'interno dell'ecosistema SharePoint, la piattaforma di collaborazione e gestione dei documenti di Microsoft. Le API consentono agli sviluppatori di interagire con i dati e i servizi di SharePoint in vari modi, estenderne le funzionalità e favorire le integrazioni con altri software e l’automazione dei processi aziendali. In questo articolo andremo a dare una panoramica generale di cosa sono, come funzionano e quali sono le loro caratteristiche principali.
API è l'acronimo di Application Programming Interface, ovvero un'interfaccia di programmazione delle applicazioni: un intermediario software che consente a due applicazioni di comunicare tra loro. Le API sono un modo accessibile per estrarre e condividere dati all'interno e tra le organizzazioni.
Le API moderne aderiscono a standard specifici (tipicamente HTTP e REST), che permettono loro di essere developer-friendly, facilmente accessibili e comprensibili e sono trattate molto di più rispetto al passato come prodotti per il consumo da parte di audience come, ad esempio, gli sviluppatori di app mobili.
Sono documentate e versionate in modo tale da consentire agli utenti di avere aspettative chiare sulla loro manutenzione e ciclo di vita ed essendo molto più standardizzate rispetto al passato il focus su prestazioni e sicurezza delle stesse è notevolmente aumentato nel tempo.
Le API di SharePoint non fanno eccezione e permettono di interagire con i dati e le funzionalità della piattaforma per creare soluzioni personalizzate, automatizzare processi, migliorare la gestione dei contenuti, l’amministrazione dei siti, il controllo dei permessi e gestire la comunicazione tra SharePoint e le altre applicazioni dell’ambiente Microsoft 365 in maniera fluida ed efficiente.
Per farci un’idea di cosa siano nel pratico andiamo quindi a vedere quali sono, cosa le differenzia e come funzionano.
Attualmente ci sono due tipi di API disponibili per SharePoint: una è la SharePoint REST API e l'altra è la Microsoft Graph API.
L'API Graph e l'API REST, pur essendo basate sulla stessa architettura, sono due modi diversi di accedere ai dati da SharePoint e ad altri servizi di Microsoft 365. La differenza principale tra le due è che l'API Graph è un'API più generale e unificata che può accedere ai dati da vari servizi di Microsoft 365, mentre la SharePoint REST API è progettata per funzionare specificamente con siti e contenuti di SharePoint.
La API Graph fornisce un'esperienza coerente per gli sviluppatori per l'autenticazione, la documentazione, gli SDK e offre funzionalità come le notifiche di modifica, le query delta e le richieste batch. Oltre a coprire la maggior parte degli scenari comuni per lavorare con siti, liste, cartelle, elementi e documenti di SharePoint, Graph supporta inoltre l'accesso basato sull'identità, il che significa che è possibile utilizzare lo stesso URL per accedere a risorse diverse in base ai permessi dell'utente.
Il rovescio della medaglia è che non supporta alcune delle funzionalità specifiche di SharePoint e potrebbe avere alcuni problemi di latenza o prestazioni rispetto all'API REST di SharePoint, poiché è un proxy per l'effettiva API di SharePoint.
La API REST di SharePoint fornisce invece maggiore funzionalità e controllo sulle funzionalità specifiche di SharePoint, come impostazioni del sito, modelli di sito, flussi di lavoro, ricerca, ecc.
Potrebbe avere prestazioni e reattività migliori rispetto all'API Graph, poiché accede direttamente alla fonte dati di SharePoint ma c’è da tenere presente che l’utilizzo della API REST richiede endpoint e metodi di autenticazione diversi per i diversi servizi Microsoft 365, il che può aumentare la complessità e la manutenzione dell'app e utilizza modalità di accesso basate sulle funzioni, il che significa che è necessario conoscere il nome esatto e i parametri della funzione per accedere a una specifica risorsa.
Quindi quale scegliere? Dipende sostanzialmente da quelle che sono le proprie esigenze e preferenze e da quanto controllo capillare sulle funzionalità di SharePoint si desidera. Tuttavia, è necessario tenere a mente che Microsoft negli ultimi tempi sta spingendo moltissimo sull’utilizzo di Graph nell’ottica della moderna politica della casa di Redmond che vuole la massima integrazione tra tutti i prodotti dell’ambiente di lavoro digitale Microsoft 365.
Dato uno sguardo generale a quali sono i tipi di API disponibili per SharePoint, andiamo adesso a vedere più nello specifico cosa li caratterizza singolarmente. Cominciamo dalla SharePoint REST API.
Questa è progettata specificamente per interagire con i dati e le funzionalità della piattaforma di collaborazione di Microsoft. Ciò significa che è ottimizzata per fornire accesso diretto e dettagliato ai dati e alle operazioni specifiche di SharePoint, come liste, documenti, metadati e impostazioni del sito.
Mediante il suo utilizzo, gli sviluppatori hanno dunque un controllo diretto e dettagliato sulle risorse di SharePoint, consentendo loro di eseguire operazioni specifiche e ottimizzate per le esigenze dell'applicazione, senza doversi preoccupare di livelli di astrazione aggiuntivi che potrebbero complicare lo sviluppo o impattare negativamente sulle prestazioni della soluzione che si desidera implementare.
REST (acronimo di Representational State Transfer), è uno stile architetturale che guida la progettazione e lo sviluppo di sistemi di rete. Uno dei principali vantaggi delle API REST è che forniscono un grande livello di flessibilità. I dati non sono legati a risorse o metodi, quindi REST può gestire diversi tipi di chiamate e restituire formati di dati differenti.
L'architettura REST si concentra sul concetto di risorse, che sono identificate da URL unici, e si basa sul protocollo standard Open Data Protocol (OData) permettendo agli sviluppatori di eseguire operazioni base di creazione, lettura, aggiornamento e eliminazione (o CRUD) tramite una richiesta HTTP RESTful.
Nel contesto di SharePoint, le risorse possono essere elementi in una lista di SharePoint, documenti in una libreria di SharePoint o persino il sito SharePoint stesso. Interagendo con queste risorse utilizzando richieste HTTP, i client possono recuperare informazioni, apportare modifiche ed eseguire altre azioni.
Le risorse di SharePoint, come liste, librerie o siti, sono esposte tramite URL specifici chiamati endpoint. Questi endpoint rappresentano i punti di ingresso per interagire con le risorse di SharePoint utilizzando l'API REST.
Per lavorare con l'API REST di SharePoint, è necessario creare e inviare richieste HTTP agli endpoint appropriati dell'API di SharePoint, con al loro interno tutte le informazioni necessarie (come l'endpoint di destinazione, gli header e talvolta i corpi delle richieste). Le richieste vengono inviate al server SharePoint, che le elabora e restituisce risposte. Queste risposte contengono i dati richiesti, la conferma di un'operazione riuscita o messaggi di errore in caso di problemi.
Queste richieste HTTP utilizzano diversi metodi per eseguire operazioni di base:
Ad esempio, se facciamo una richiesta HTTP GET a questo endpoint, la richiesta ci permetterà di recuperare un elenco di elementi da un sito di SharePoint:
https://example.sharepoint.com/_api/web/lists/getbytitle('ListName')/items
L'API REST di SharePoint fornisce funzionalità che corrispondono a vari modelli di oggetti client, inclusi:
Ogni modello di oggetto client permette di interagire con tutte le entità di SharePoint, come liste, librerie di SharePoint e tanti altri tipi di contenuto.
Abbiamo realizzato intranet.ai, che conta 200+ installazioni.
È la soluzione pronta all'uso e personalizzabile per digitalizzare i processi e la comunicazione di qualunque azienda.
Ti aiuteremo a:
Contattaci se hai in mente un progetto SharePoint Online!
Passiamo adesso a dare uno sguardo più nel dettaglio alla seconda opzione trattata in precedenza (nonché attualmente quella preferita da Microsoft per lo sviluppo nel suo ambiente digitale), ovvero Microsoft Graph API.
Progettata per fornire un'esperienza coerente e semplificata per gli sviluppatori che desiderano integrare le funzionalità di Microsoft 365 e altre risorse cloud nei propri progetti, l'API Microsoft Graph fornisce un singolo endpoint API che può essere utilizzato per accedere ai dati da più servizi (tra cui ovviamente anche SharePoint Online), rendendo più facile per gli sviluppatori creare applicazioni multipiattaforma che eseguono una varietà di compiti, come leggere e scrivere email, gestire calendari, accedere a file e cartelle e che funzionano senza problemi su diversi dispositivi.
L'API segue come la REST API lo standard Open Data Protocol (OData), permettendo agli sviluppatori di eseguire operazioni CRUD su entità di SharePoint utilizzando comandi HTTP come GET, POST, PUT e DELETE.
Nello specifico contesto di SharePoint, Microsoft Graph API offre un modo potente per gli sviluppatori di interagire con i dati e le funzionalità dei siti SharePoint e altri servizi connessi e arricchisce enormemente l’operatività delle intranet basate su SharePoint Online.
Un esempio di quest’arricchimento delle funzionalità dedicate alle intranet è la possibilità di espandere la people directory, sfruttando le informazioni che Graph mette a disposizione e che provengono dagli account Microsoft 365 dei dipendenti. Il vantaggio di tale integrazione risiede nel fatto che i dati personali vengono trasferiti in tempo reale da Microsoft 365 alla intranet, aggiornando automaticamente i profili presenti in quest’ultima.
Gli sviluppatori possono inoltre sfruttare funzionalità avanzate come le notifiche di modifica per essere informati quando i dati di SharePoint vengono modificati, query delta per recuperare solo le modifiche recenti e richieste batch per ottimizzare le prestazioni delle chiamate API.
La API consente agli sviluppatori non solo di accedere ai dati di SharePoint, come siti, liste, documenti, cartelle e altro ancora, utilizzando le richieste API standardizzate ma, poiché Microsoft Graph API unifica l'accesso ai dati di SharePoint insieme ad altri servizi Microsoft (come Outlook, OneDrive, Teams e Azure Active Directory), gli sviluppatori possono anche creare applicazioni che integrano dati da diverse fonti senza dover gestire molteplici endpoint API e che funzionano su una vasta gamma di piattaforme e dispositivi, inclusi smartphone e tablet.
Per quanto riguarda invece le funzionalità di ricerca, sia la SharePoint REST Search API che Microsoft Graph API offrono caratteristiche, vantaggi e limiti differenti a seconda di quelle che sono le proprie necessità.
La scelta tra le due dipende dai requisiti specifici dell'applicazione e dall'ambito della ricerca. Per ricerche altamente specializzate e dettagliate nei contenuti di SharePoint, la SharePoint REST Search API è spesso preferita. Per scenari che richiedono l'integrazione di dati da diversi servizi Microsoft 365, Microsoft Graph API è generalmente la scelta migliore. Ma vediamo le loro caratteristiche un po’ più nel dettaglio.
Come abbiamo già accennato più sopra (e come si può evincere dal nome), la SharePoint Rest API è ottimizzata per SharePoint e consente consente di eseguire query di ricerca su contenuti di SharePoint, come documenti, elenchi, siti e tutti i tipi di file che possono essere archiviati nei suoi spazi, offrendo opzioni avanzate specifiche per la personalizzazione delle query, inclusi affinamenti, ordinamenti e operatori logici complessi e (in alcuni casi) può offrire prestazioni migliori per le ricerche specifiche su SharePoint rispetto all'API unificata di Graph.
La richiesta viene solitamente effettuata utilizzando il metodo HTTP GET di cui avevamo fatto un piccolo esempio nella sezione dedicata alle caratteristiche della REST API e che adesso vedremo di approfondire meglio.
GET http://server/_api/search/query?query_parameter
Le richieste GET come quella nell’esempio sono adatte per query relativamente semplici. Richieste più complesse possono essere assemblate come documenti JSON contenenti le coppie chiave/valore appropriate per ciascun elemento della richiesta.
Le risposte possono essere limitate a un numero fisso di documenti, oppure si può scegliere di impaginare i dati di risposta, caricando blocchi di risultati mentre gli utenti passano da una pagina all'altra o aggiungendo nuovi risultati mentre scorrono attraverso un'applicazione web a singola pagina.
Anche se le API hanno la propria sintassi, è comunque necessario pensare a KQL (Keyword Query Language) e FQL (FAST Query Language) quando si costruiscono i termini di query. Questi consentono di scegliere i documenti restituiti nel set di risultati. Utilizzando l'API GET si è limitati a un solo filtro. Per utilizzarne di più, si può utilizzare ad esempio POST per inviare un array di filtri FQL al server di ricerca.
A differenza della maggior parte degli ambienti di ricerca, l'API di SharePoint offre molte opzioni per personalizzare i risultati e garantire che i ruoli e altri meccanismi di controllo degli accessi siano applicati, oltre a dare agli amministratori la possibilità di applicare un certo livello di controllo editoriale sui risultati per impostare come vengono ordinati e visualizzati.
Una funzionalità utile è l'opzione che consente di restituire query suggerite basate su ciò che altri utenti hanno cercato. L'API di ricerca di SharePoint offre un semplice endpoint Suggest per questo, utilizzando parametri per fornire possibili termini di ricerca che possono attivare un suggerimento. Questi sono probabilmente i termini di ricerca attuali dell'utente e possono aiutarlo a raffinare rapidamente le query prima o dopo l'esecuzione di una ricerca.
Anche se non c'è una data di fine vita per le attuali API di ricerca esistenti, visto il progetto di migrazione di Microsoft verso una API unificata per tutto l’ambiente Microsoft 365, le nuove funzionalità saranno disponibili solo attraverso Microsoft Graph API.
Come parte di questo cambiamento, tutte le ricerche passeranno attraverso un'unica API. Ciò significa che il codice scritto per SharePoint funzionerà anche con altri servizi Microsoft 365, ovunque ci sia un indice di ricerca. Utilizzare un'API di ricerca comune per tutti i propri contenuti Microsoft 365 ha senso, specialmente considerato il focus di Microsoft sull'AI generativa e i modelli linguistici di grandi dimensioni.
L'istituzione di un'API di ricerca comune per tutti i servizi di Microsoft 365 rappresenta un passo da tempo necessario lontano nella gestione della documentazione aziendale. Con buone capacità di ricerca e un'efficace indicizzazione dei metadati, non c'è davvero bisogno di una struttura artificiale per navigare tra i file. Invece, le informazioni vengono fornite al momento necessario da un unico indice, fornendo un ponte trasparente tra gli spazi delle varie applicazioni.
Il Microsoft Graph API è una tipica API REST, che utilizza POST con un payload JSON. Ogni payload JSON è composto da un insieme di richieste, che vengono eseguite contro entità e che contengono query. Le query sono stringhe e possono essere utilizzate per definire l'ambito delle tue richieste. In questo modo, puoi includere siti specifici di SharePoint nel tuo tenant o escludere sezioni del tuo tenant che non desideri siano cercate.
Una volta costruito il proprio JSON di query di base, si può iniziare a perfezionarne il funzionamento, per esempio ordinando i risultati utilizzando tecniche di impaginazione familiari e applicando filtri aggiuntivi, come finestre temporali specifiche su cui basare la ricerca.
È da menzionare che non si è limitati alla struttura gerarchica delle query di Graph, poiché è possibile utilizzare il Keyword Query Language (KQL) come parte delle proprie query. Le query possono quindi essere aggregate, offrendo la possibilità di costruire query complesse che funzionano su diverse entità di Microsoft 365. Questo approccio consente di raccogliere non solo i documenti relativi a una query, ma anche, per esempio, email pertinenti ed elenchi di persone.
Oltre a una libreria di connettori predefiniti per le proprie applicazioni, Microsoft fornisce strumenti che è possibile utilizzare per creare i propri connettori personalizzati per applicazioni su misura, o per lavorare con dati legacy in mainframe o minicomputer.
Si pensi al lavoro sullo sfondo di Microsoft Graph come a un indice dinamico e costantemente aggiornato dei propri dati non relazionali. Man mano che vengono memorizzati nuovi contenuti in Microsoft 365 e in piattaforme come SharePoint Online, questo indice si aggiorna automaticamente e rende i contenuti disponibili in tutto il proprio tenant Microsoft 365 per tutti gli utenti aziendali.
Un'altra valida ragione per utilizzare una singola API di ricerca è che può contribuire a garantire che ai dati regolamentati venga garantito l’accesso solo a utenti autorizzati. Avvolgere le query di Microsoft Graph in uno schema di autenticazione basato su ruoli aiuta a fare in modo che l'accesso ai dati venga registrato, monitorato e che gli utenti possano accedere solo ai dati consentiti per il loro ruolo o il loro gruppo.
Microsoft è attualmente impegnata nella sostituzione dei processi di autenticazione legacy (autenticazione tramite nome utente e password) per i suoi servizi Microsoft 365. Questo passaggio è stato fatto dalla casa di Redmond per migliorare la sicurezza generale dei suoi software, in quanto l'autenticazione legacy è ormai fin troppo vulnerabile ad attacchi malevoli orientati al furto dei dati di accesso degli utenti.
Sia la SharePoint REST API che la Microsoft Graph API utilizzano OAuth 2.0 come metodo di autenticazione standard. OAuth 2.0 riduce il rischio di compromissione delle credenziali rispetto alle autenticazioni basate su nome utente e password e permette una gestione granulare delle autorizzazioni, specificando esattamente quali risorse e operazioni un'applicazione può accedere utilizzando un sistema basato su token di accesso a breve termine e revocabili in qualsiasi momento che migliorano moltissimo la sicurezza complessiva dei dati.
Mentre il processo di autenticazione di base è simile per entrambe le API, Microsoft Graph API offre, come abbiamo già potuto osservare, un punto di accesso unificato a una vasta gamma di servizi Microsoft 365, fornendo una maggiore flessibilità e integrazione.
L'autenticazione per la SharePoint REST API può essere effettuata utilizzando diversi metodi, ma con la transizione verso protocolli di sicurezza migliori di cui abbiamo parlato sopra, OAuth 2.0 è appunto diventato lo standard raccomandato.
Prima di tutto, è necessario registrare l'applicazione in Azure Active Directory (AAD). Durante la registrazione, si ottiene un client ID e un client secret, che vengono utilizzati per l'autenticazione.
L'applicazione deve richiedere un token di accesso a AAD. Questo può essere fatto tramite un flusso di autorizzazione OAuth 2.0. Un esempio comune è il flusso di credenziali del client: l'applicazione invia una richiesta POST all'endpoint del token AAD con il client ID, il client secret e l'ambito (scope) desiderato (ad esempio, https://{tenant}.sharepoint.com/.default).
Se le credenziali sono corrette, AAD restituisce un token di accesso JSON Web Token (JWT). L'applicazione utilizzerà quindi questo token di accesso per effettuare chiamate autenticate alla SharePoint REST API. Il token viene inviato nell'intestazione della richiesta HTTP come
Authorization: Bearer {access_token}
L'autenticazione per la Microsoft Graph API segue un processo simile (se non per certi versi identico), con l'utilizzo di OAuth 2.0, ma con alcuni dettagli specifici per l'accesso ai servizi Microsoft 365.
Dove SharePoint REST API richiede token direttamente dall'endpoint di Azure Active Directory con specifiche per il tenant di SharePoint, Graph, pur utilizzando l'endpoint di Azure Active Directory, specifica l'ambito di Graph per ottenere un token (esempio: https://graph.microsoft.com/.default).
Gli scope sono più ampi rispetto a quelli di SharePoint REST API e possono coprire diverse risorse all'interno di Microsoft 365. Questo consente dunque l'accesso a una varietà di servizi, non solo a SharePoint, ma anche a Outlook, OneDrive, Teams e altre applicazioni Microsoft 365.
Le autorizzazioni sono dunque molto più centralizzate e coprono una gamma più ampia di servizi e gli scope possono includere permessi come User.Read, Files.ReadWrite.All, Mail.Read, oltre ai permessi specifici per SharePoint.
Si conclude qui la nostra panoramica sulle API attualmente disponibili per SharePoint, ma ci teniamo comunque a fare una piccola precisazione finale su quelli che saranno gli sviluppi successivi riguardanti l’argomento.
Con Microsoft che continua a concentrare i propri sforzi di sviluppo e aggiornamento su Microsoft Graph, è chiaro che questa API rappresenta il futuro dell'integrazione e della gestione dei dati per tutto l'ecosistema Microsoft 365, a scapito della più vetusta (seppur più specializzata) SharePoint REST API.
Sfruttando le potenzialità di una singola interfaccia di programmazione per accedere a tutte le risorse e i servizi necessari gli sviluppatori potranno ridurre significativamente la complessità di gestione di più endpoint e migliorare la coerenza delle applicazioni sviluppate, facilitando allo stesso tempo l'implementazione di soluzioni basate su intelligenza artificiale e machine learning, campi su cui Microsoft ha ormai deciso di investire significativamente.
Sviluppatori e aziende sono quindi incoraggiati a iniziare la transizione verso Microsoft Graph API, per poter sfruttare appieno le nuove opportunità offerte dalla stretta integrazione tra i software dell’ambiente Microsoft 365 e garantire che le loro applicazioni restino al passo con l'evoluzione tecnologica dei digital workplace contemporanei.
Il team Modern Work risponde in maniera efficace e veloce alle necessità IT, in cui lo sviluppo software rappresenta la componente principale. Le figure tecniche hanno tutte una formazione incentrata sulla realizzazione di progetti software su stack tecnologici Microsoft e possiedono competenze nella gestione di progetti agili o di lunga durata.
