Eseguire query in Microsoft Graph tramite REST

  • 3 minuti

Microsoft Graph è un'API Web RESTful che consente di accedere alle risorse del servizio Microsoft Cloud. Dopo aver registrato l'app e aver acquisito i token di autenticazione per un utente o un servizio, è possibile effettuare richieste all'API Microsoft Graph.

L'API Microsoft Graph definisce la maggior parte delle risorse, dei metodi e delle enumerazioni nello spazio dei nomi OData, microsoft.graph, nei metadati di Microsoft Graph. Alcuni set di API vengono definiti nei relativi spazi dei nomi secondari, ad esempio l'API dei record di chiamata che definisce risorse come callRecord in microsoft.graph.callRecords.

A meno che non venga specificato in modo esplicito nell'argomento corrispondente, si supponga che tipi, metodi ed enumerazioni facciano parte dello spazio dei nomi microsoft.graph.

Chiamare un metodo API REST

Per leggere o scrivere in una risorsa, ad esempio un messaggio utente o di posta elettronica, si crea una richiesta simile alla seguente:

{HTTP method} https://graph.microsoft.com/{version}/{resource}?{query-parameters}

I componenti di una richiesta includono:

  • {HTTP method}: il metodo HTTP usato nella richiesta per Microsoft Graph.
  • {version}: la versione dell'API Microsoft Graph usata dall'applicazione.
  • {resource}: la risorsa in Microsoft Graph a cui si fa riferimento.
  • {query-parameters}: le opzioni di query OData facoltative o i parametri del metodo REST che personalizzano la risposta.

Dopo aver eseguito una richiesta, viene restituita una risposta che include:

  • Codice di stato: un codice di stato HTTP che indica l'esito positivo o negativo.
  • Messaggio di risposta: i dati richiesti o il risultato dell'operazione. Il messaggio di risposta può essere vuoto per alcune operazioni.
  • nextLink: se la richiesta restituisce numerosi dati, è necessario consultarla usando l'URL restituito in @odata.nextLink.

Metodi HTTP

Microsoft Graph usa il metodo HTTP nella richiesta per determinare le operazioni eseguite. L'API supporta i metodi seguenti.

Metodo Descrizione
GET Legge i dati da una risorsa.
POST Crea una nuova risorsa o esegue un'azione.
PATCH Aggiorna una risorsa con nuovi valori.
PUT Sostituisce una risorsa con una nuova.
DELETE Rimuove una risorsa.
  • Per i metodi CRUD GET e DELETE non è necessario alcun corpo della richiesta.
  • I metodi POST, PATCH e PUT richiedono un corpo della richiesta, specificato in formato JSON, che contiene informazioni aggiuntive, ad esempio i valori per le proprietà della risorsa.

Versione

Microsoft Graph supporta attualmente due versioni: v1.0 e beta.

  • v1.0 include API disponibili a livello generale. Usare la versione 1.0 per tutte le app di produzione.
  • beta include le API attualmente in anteprima. Poiché è possibile che vengano introdotte modifiche di rilievo alle API beta, è consigliabile usare la versione beta solo per testare le app in fase di sviluppo. Non usare le API beta nelle app di produzione.

Risorsa

Una risorsa può essere un'entità o un tipo complesso, definito comunemente con proprietà. Le entità differiscono dai tipi complessi perché includono sempre una proprietà id.

L'URL include la risorsa con cui si interagisce nella richiesta, ad esempio me, user, group, drive e site. Spesso, le risorse di primo livello includono anche relazioni, che è possibile usare per accedere ad altre risorse, ad esempio me/messages o me/drive. È anche possibile interagire con le risorse usando metodi. Ad esempio, per inviare un messaggio di posta elettronica, usare me/sendMail.

Ogni risorsa potrebbe richiedere autorizzazioni di accesso diverse. Spesso è necessario un livello di autorizzazioni superiore per creare o aggiornare una risorsa rispetto a quello necessario per leggerla. Per informazioni dettagliate sulle autorizzazioni necessarie, vedere l'argomento di riferimento sui metodi.

Parametri di query

I parametri di query possono essere opzioni di query di sistema OData oppure altre stringhe che un metodo accetta per personalizzare la risposta.

È possibile usare le opzioni facoltative di query di sistema OData per includere più o meno proprietà rispetto alla risposta predefinita, filtrare la risposta per gli elementi che corrispondono a una query personalizzata o specificare altri parametri per un metodo.

Ad esempio, l'aggiunta del parametro filter seguente limita i messaggi restituiti solo a quelli con la proprietà emailAddress uguale a jon@contoso.com.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq 'jon@contoso.com'

Altre risorse

Di seguito sono riportati i collegamenti ad alcuni strumenti che è possibile usare per compilare e testare le richieste usando le API Microsoft Graph.