Die Microsoft Graph API ist derzeit in aller Munde und wird zum Zentraleneinstiegspunkt für Datenaggregierung und -manipulation der Microsoft 365 Services. Nicht umsonst, denn die Graph API ist ziemlich mächtig. Dieser Blog erklärt das Wichtigste und hält konkrete Einsatzbeispiele der Graph API bereit. Genau das richtige für alle, die von Buzzword-Kennern zu Drückern werden wollen.
Was ist die Microsoft Graph API?
Microsoft Graph API ist ein einziger Endpunkt, der Zugriff auf mehrere Microsoft-Dienste wie Microsoft 365, Azure AD und mehr bietet. Dadurch können Entwickler einfach auf diese Dienste zugreifen und deren Daten manipulieren, ohne mit mehreren APIs arbeiten zu müssen. Die API basiert auf den REST-Prinzipien und verwendet OAuth 2.0 für die Authentifizierung und Autorisierung.
Microsoft Graph kommt auch im KI-Assistenten M365 Copilot zum Einsatz. Dank Graph kann der Copilot auf einen eingegebenen Prompt mit relevanten Kontextinformationen antworten. Beispielsweise Auszüge aus kürzlich gesendeten E-Mails und natürlich themenverwandte Dokumente.
Mit Graph API auf Daten aus Microsoft 365 zugreifen
Eine der wichtigsten Fähigkeiten der Microsoft Graph API ist, Daten aus Microsoft 365-Diensten abzurufen. Dazu gehören E-Mail, Kalender, Kontakte und mehr. Entwickler können die API verwenden, um Daten von diesen Diensten zu lesen und zu schreiben sowie andere Aktionen auszuführen, wie zum Beispiel E-Mails senden oder Meetings planen. Eine weitere wichtige Fähigkeit der Microsoft Graph API ist der Zugriff auf Daten aus Azure AD. Dazu gehören Informationen zu Benutzern und Gruppen sowie Informationen über Anwendungen und Dienste, die bei Azure AD registriert sind.
Einstieg in die Microsoft Graph API
Der Einstieg in die Microsoft Graph API ist relativ einfach. Der erste Schritt besteht darin, eine Anwendung bei Azure AD zu registrieren, die Ihnen eine Anwendungs-ID und ein Client-Geheimnis bereitstellt. Diese werden verwendet, um Ihre Anwendung für den Zugriff auf Daten von Microsoft-Diensten zu authentifizieren und zu autorisieren. Sobald Sie Ihre Anwendung registriert haben, können User damit beginnen, API-Aufrufe an Microsoft Graph zu senden. Am einfachsten kann Graph mit dem Graph Explorer ausprobiert werden, wo die Registrierung einer Anwendung nicht notwendig ist, sondern direkt mit einem User-Account auf die API zugegriffen werden kann.
Kommunikation mit der Graph API
Die API verwendet eine standardisierte REST-Architektur mit Anfragen und Antworten im JSON-Format. Es können jede Programmiersprache oder jedes Framework verwendet werden das HTTP-Anfragen unterstützt, um API-Aufrufe zu senden, wie beispielsweis Python, Node.js, C# oder PowerShell. Es gibt eine Reihe von Bibliotheken und SDKs für verschiedene Programmiersprachen und Plattformen, die das Arbeiten mit der Microsoft Graph API vereinfachen. Beispielsweise bietet das Microsoft Graph SDK für .NET eine Reihe von Klassen und Methoden, die das Arbeiten mit der API in .NET-Anwendungen vereinfachen.
Ebenfalls gibt es für die Verwendung Actions in Power Automate. Um es EntwicklerInnen einfacher zu machen, mit der Microsoft Graph API zu arbeiten, stellt Microsoft eine Reihe von Ressourcen und Werkzeugen wie Dokumentation, Beispielen und Tutorials zur Verfügung. Diese Ressourcen finden sich im Microsoft Graph Developer Center und umfassen alles von Einstiegsanleitungen bis hin zu detaillierten Referenzdokumentationen.
Verwendung der Graph API
Um die Graph API zu testen oder auszuprobieren, wird am einfachsten der Graph Explorer oder ein API-Client wie Postman verwendet. In einem einfachen Power Automate Workflow können die Abfragen ebenfalls mittels HTTP-Action ausgeführt werden.
Die Domain der Graph API ist immer dieselbe: https://graph.microsoft.com/<version>, egal ob ich nun auf Emails, Aufgaben oder Dateien zugreifen möchte. Ich muss nicht den Service unterscheiden, sondern kann bequem, oft User-zentriert, auf die einzelnen Relationen innerhalb des Graph-Kosmos zugreifen.
Microsoft Graph API Beispiel 1: Userinformationen abfragen
Nachfolgend ist ein Beispiel für eine einfache Anfrage mit der Methode GET, um die Profilinformationen des authentifizierten Benutzers von der Microsoft Graph API abzurufen:
GET https://graph.microsoft.com/v1.0/meDiese Anfrage verwendet den Endpunkt /me, der sich auf den authentifizierten Benutzer bezieht. Die v1.0 in der URL gibt an, dass wir die v1.0-Version der API verwenden. Es kann auch der Beta-Endpoint verwendet werden.
Außerdem müssen Sie einen Authorization-Header mit einem gültigen Zugriffstoken zur Authentifizierung der Anfrage einschließen. Das Format des Header sollte so aussehen:
Authorization: Bearer <access_token>Wenn Sie Informationen über einen bestimmten Benutzer abrufen möchten, können Sie den Endpunkt /users/{id} verwenden, wobei id die eindeutige ID des Benutzers ist, für den Sie die Informationen abrufen möchten. Die {id} wäre in diesem Fall entweder eine GUID oder der UPN des abzufragenden Users, z.B. reto.stadelmann@ioz.ch:
GET https://graph.microsoft.com/v1.0/users/{id}Es ist zu beachten, dass die spezifischen Berechtigungen des Access-Tokens bestimmen, welche Informationen Sie mit dieser Anfrage abrufen können.
Microsoft Graph API Beispiel 2: Emails gefiltert abfragen
Ein Beispiel für einen praxisorientierten Aufruf der Microsoft Graph API könnte zum Beispiel sein, alle E-Mails eines bestimmten Benutzers abzurufen, die bestimmte Schlagwörter enthalten. Hier könnte der Use-Case sein, E-Mails eines Service-Postfachs abzufragen, welche bspw. zu einem bestimmten Thema gehören. Hier ist ein mögliches Beispiel in Node:
const https = require('https');
// Konfiguriert die Anfrageoptionen
const options = {
hostname: 'graph.microsoft.com',
port: 443,
path: '/v1.0/users/user@example.com/messages?$search=%22Wichtig%22+OR+%22Dringend%22',
method: 'GET',
headers: {
'Authorization': 'Bearer ' + accessToken,
'Content-Type': 'application/json'
}
};
// Führt die Anfrage aus
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
if (res.statusCode === 200) {
const emails = JSON.parse(data).value;
emails.forEach((email) => {
console.log(email.subject);
});
} else {
console.log(`Fehler beim Abrufen der E-Mails: ${data}`);
}
});
});
req.on('error', (e) => {
console.error(`
Respektive nur den Endpoint:
GET https://graph.microsoft.com/v1.0/users/user@example.com/messages?$search='Wichtig' OR 'Dringend'In diesem Beispiel werden alle E-Mails des Benutzers «user@example.com» abgerufen, die entweder das Schlagwort «wichtig» oder «dringend» enthalten. Dabei werden Abfrageparameter verwendet, um die gewünschten E-Mails zu filtern. Es braucht Berechtigungen, um auf das jeweilige Postfach zugreifen zu können.
Microsoft Graph API Beispiel 3: Export von Daten
Dieses Beispiel ruft alle Termine eines bestimmten Benutzers für den aktuellen Monat ab und erstellt dann eine CSV-Datei mit den Terminen:
const https = require('https');
const moment = require('moment');
const csvWriter = require('csv-write-stream');
const fs = require('fs');
// Konfiguriert den Request
const options = {
hostname: 'graph.microsoft.com',
port: 443,
path: `/v1.0/users/user@example.com/calendarView?startDateTime=${moment().startOf('month').format()}&endDateTime=${moment().endOf('month').format()}`,
method: 'GET',
headers: {
'Authorization': 'Bearer ' + accessToken,
'Content-Type': 'application/json'
}
};
// Führt die Anfrage aus
const req = https.request(options, (res) => {
let data = '';
res.on('data', (chunk) => {
data += chunk;
});
res.on('end', () => {
if (res.statusCode === 200) {
const appointments = JSON.parse(data).value;
// Erstellt eine CSV-Datei mit den Terminen
const writer = csvWriter();
writer.pipe(fs.createWriteStream('appointments.csv'));
appointments.forEach((appointment) => {
writer.write({
Subject: appointment.subject,
Start: appointment.start.dateTime,
End: appointment.end.dateTime,
Location: appointment.location.displayName
});
});
writer.end();
console.log('CSV-Datei erfolgreich erstellt.');
} else {
console.log(`Fehler beim Abrufen der Termine: ${data}`);
}
});
});
req.on('error', (e) => {
console.error(`Fehler beim Ausführen der Anfrage: ${e.message}`);
});
req.end();
Respektive nur den Endpoint:
GET https://graph.microsoft.com/v1.0/users/user@example.com/calendarView?startDateTime=XXXX&endDateTime=XXXXIn diesem Beispiel werden alle Termine des Benutzers „user@example.com“ für den aktuellen Monat abgerufen. Mit der Hilfe von der `csv-write-stream` und `fs` Bibliotheken werden die Termine dann in eine CSV-Datei geschrieben und gespeichert.
Es kann also schnell komplex werden, gerade, wenn mit den Daten auch noch weitergearbeitet werden soll.
Fazit
Wir verwenden in unseren Projekten die Graph API beinahe täglich. Sie bietet viele Möglichkeiten und macht das Verknüpfen von Informationen zu einem Kinderspiel. Die Integration in Power Automate oder Azure Functions erfordert zwar Grundwissen, ist jedoch keine Rocket Science.
Als zentraler Einstiegspunkt vereinfacht es im Vergleich zu früher das Handling und insbesondere auch die Authentifizierung ungemein. Werden die Abfragen noch verkettet verwendet bspw. alle Teams nach einem Team mit einem bestimmten Namen filtern, die ID des Teams extrahieren, und dann mit dieser ID beispielsweise alle Channels oder Members des spezifischen Teams auflisten, werden durch die Kombination die Möglichkeiten beinahe unendlich.
Wir verwenden die Graph API vor allem zum Abfragen von Benutzerinformationen, auslesen von Gruppenzugehörigkeiten oder der Verwaltung von Gruppen und Teams in Power Automate oder individuell erstellten Azure Functions und haben damit gute Erfahrungen gemacht. Oft lohnt es sich, mehr Aufwand für eine stabilere Lösung zu betreiben und die Daten aus Graph sauber in die jeweiligen Workflows zu integrieren.
Wir kommen jedoch auch oft an die Grenzen von Graph. Einige Services sind einfach nicht so weit entwickelt, dass man sie praxistauglich benutzen könnte. Beispielsweise die Planner-API von Graph, welche sehr umständlich zu verwenden ist. Es gilt jeweils den Anwendungsfall zu betrachten und genau zu prüfen, ob die jeweiligen Anforderungen mit Graph-API-Aufrufen abgedeckt werden können.
Häufig gestellte Fragen und Antworten
Was ist die Microsoft Graph API?
Die Microsoft Graph API ist eine einzige Schnittstelle, die Zugriff auf mehrere Microsoft-Dienste wie Office 365, Azure AD und mehr bietet. Entwickler können die API verwenden, um Daten von diesen Diensten zu lesen, zu schreiben und zu manipulieren.
Was sind die Vorteile der Verwendung der Microsoft Graph API?
Die Microsoft Graph API bietet eine einzige Schnittstelle für den Zugriff auf mehrere Microsoft-Dienste, was die Entwicklung vereinfacht und die Integrationszeit verkürzt. Es implementiert eine einheitliche RESTful-Architektur und die selbe OAuth 2.0-Authentifizierung für alle Endpoints.
Wie kann ich mit der Microsoft Graph API arbeiten?
Um mit der Microsoft Graph API zu arbeiten, müssen Sie zuerst eine Anwendung bei Azure AD registrieren, um eine Anwendungs-ID und ein Client-Geheimnis zu erhalten. Damit holen sie vom Auth-Dienst von Microsoft ein Access-Token. Dann können Sie API-Aufrufe an die Microsoft Graph API senden.
Welche Art von Daten kann ich mit der Microsoft Graph API abrufen?
Mit der Microsoft Graph API können Sie Daten aus Microsoft 365-Diensten wie E-Mail, Kalender, Kontakte und mehr abrufen. Sie können auch Daten aus Azure AD wie Benutzer- und Gruppeninformationen sowie Informationen über registrierte Anwendungen und Dienste abrufen. Es bietet auch Zugriff auf andere Microsoft-Dienste wie OneDrive, OneNote und SharePoint.
Welche Anfragetypen unterstützt die Microsoft Graph API?
Die Microsoft Graph API unterstützt Anfragetypen wie GET, POST, PATCH, PUT, DELETE, je nach spezifischem Endpunkt und der zu durchführenden Operation.
Wo finde ich weitere Ressourcen und Unterstützung für die Microsoft Graph API?
Microsoft stellt eine Reihe von Ressourcen und Werkzeugen wie Dokumentation, Beispiele und Tutorials auf dem Microsoft Graph Developer Center zur Verfügung. Sie können auch die Microsoft Graph-Entwicklercommunity auf GitHub und anderen sozialen Medien besuchen, um Hilfe und Unterstützung von anderen Entwicklern zu erhalten.
Beitrag teilen
Geschrieben von
Reto Stadelmann
Content Services Developer
Profil anzeigen