Einstieg in das Microsoft-Graph-API

Was ist das Microsoft-Graph-API?

Microsoft Graph ist ein Zugang zu den Daten und Informationen in Microsoft 365. Es bietet eine einheitliche Programmierschnittstelle, mit dem Sie auf die enormen Datenmengen in Microsoft 365, Windows und Enterprise Mobility + Security zugreifen können.

Microsoft Graph ermöglicht diesen Datenzugriff über REST-APIs und Client-Bibliotheken auf die folgenden Microsoft Cloud-Dienste:

• Microsoft 365 Kern-Dienste: Bookings, Kalender, Delve, Excel, Microsoft 365 Compliance eDiscovery, Microsoft Search, OneDrive, OneNote, Outlook/Exchange, People (Outlook-Kontakte), Planner, SharePoint, Teams, To Do, Viva Insights
• Enterprise Mobility + Sicherheitsdienste: Advanced Threat Analytics, Advanced Threat Protection, Azure Active Directory, Identity Manager und Intune
• Windows-Dienste: Aktivitäten, Geräte, Benachrichtigungen, Universal Print
• Dynamics-365-Business-Central-Dienste

Mit Microsoft Graph können Sie eigene Anwendungen erstellen, um einen individuellen Benutzerkontext zu erstellen und Ihre Produktivität zu steigern. Stellen Sie sich z. B. eine App vor, die Folgendes kann:

• Wirft einen Blick auf Ihre nächste Besprechung und hilft Ihnen bei der Vorbereitung, indem sie Profilinformationen zu den Teilnehmern bereitstellt, einschließlich ihrer Berufsbezeichnungen, Vorgesetzten, Informationen über die neuesten Dokumente, an denen diese arbeiten, und die Personen, mit denen sie zusammenarbeiten.
• Scannt Ihren Kalender und schlägt die besten Zeiten für die nächste Teambesprechung vor.
• Holt die neueste Umsatzprognose aus einer Excel-Datei in Ihrem OneDrive und lässt Sie die Prognose in Echtzeit von Ihrem Telefon aus aktualisieren.
• Registriert Änderungen in Ihrem Kalender, sendet Ihnen eine Warnung, wenn Sie zu viel Zeit in Meetings verbringen, und gibt Ihnen Empfehlungen für Meetings, die Sie auslassen oder delegieren können, je nachdem, wie relevant die Teilnehmer für Sie sind.
• Hilft Ihnen dabei, persönliche und geschäftliche Informationen auf Ihrem Smartphone zu sortieren, z. B. durch Kategorisierung von Bildern, die in Ihrem persönlichen OneDrive gespeichert werden sollen, und von geschäftlichen Belegen, die in Ihrem OneDrive for Business gespeichert werden sollen.
• Analysiert umfangreiche Microsoft-365-Daten, sodass Entscheidungsträger wertvolle Einblicke in die Zeitaufteilung und Zusammenarbeitsmuster gewinnen können, die die Unternehmensproduktivität verbessern.
• Stellt benutzerdefinierte Geschäftsdaten in Microsoft Graph zur Verfügung und indiziert diese, um sie gemeinsam mit Daten aus Microsoft-365-Diensten durchsuchbar zu machen.

Ist Microsoft Graph API kostenlos?

Die Nutzungsgebühren für Microsoft Graph Data Connect werden verbrauchsabhängig monatlich abgerechnet. Die von Data Connect verwendete Abrechnungseinheit ist das Vielfache von 1000 Objekten, wobei 1 Objekt einer einzelnen Instanz einer Microsoft-365-Entität entspricht. Zum Beispiel: 1 E-Mail = 1 Objekt, 1 Datei = 1 Objekt, 1 Teams-Chat-Nachricht = 1 Objekt usw.

Es gibt einige Datensätze, die kostenlos zur Verfügung stehen bzw. derzeit in der Vorschau kostenlos sind, während andere Datensätze kostenpflichtig sind. Microsoft Graph Data Connect bietet Datensätze für mehrere verschiedene Microsoft-365-Produkte und Dienste.

Die Extraktion von Objekten aus den folgenden Datensätzen ist kostenlos:

• BasicDataSet_v0.User_v0
• BasicDataSet_v0.User_v1
• BasicDataSet_v0.MailboxSettings
• BasicDataSet_v0.Manager
• BasicDataSet_v0.DirectReport
• BasicDataSet_v0.GroupDetails
• BasicDataSet_v0.GroupMembers
• BasicDataSet_v0.GroupOwners

Wie beginnt man mit dem Microsoft-Graph-API?

Microsoft Graph ist eine RESTful Web-API, die Ihnen den Zugriff auf Microsoft-Cloud-Service-Ressourcen ermöglicht. Nachdem Sie Ihre App registriert und Authentifizierungs-Tokens für einen Benutzer oder Dienst erhalten haben, können Sie Anfragen an die Microsoft-Graph-API stellen.

Die Microsoft-Graph-API definiert die meisten ihrer Ressourcen, Methoden und Aufzählungen im OData-Namensraum, microsoft.graph, in den Microsoft-Graph-Metadaten. Eine kleine Anzahl von API-Sets wird in ihren Unter-Namensräumen definiert, wie z. B. die Call-Records-API, die Ressourcen wie callRecord in microsoft.graph.callRecords definiert.

Wie rufe ich eine REST-API-Methode auf?

Um von einer Ressource wie einem Benutzer oder einer E-Mail-Nachricht zu lesen oder in sie zu schreiben, erstellen Sie eine Anfrage, die wie folgt aussieht:

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

Die Bestandteile einer Anfrage sind:

• {HTTP method} – die HTTP-Methode, die bei der Anfrage an Microsoft Graph verwendet wird.
• {version} – die Version der Microsoft Graph API, die Ihre Anwendung verwendet.
• {resource} – die Microsoft-Graph-Ressource, auf die Sie zugreifen.
• {query-parameters} – optionale OData-Abfrageoptionen oder REST-Methodenparameter zur Anpassung der Antwort.

Nachdem Sie eine Anfrage gestellt haben, erhalten Sie eine Antwort, die Folgendes enthält:

• Statuscode – ein HTTP-Statuscode, der Erfolg oder Misserfolg anzeigt. Einzelheiten zu HTTP-Fehlercodes finden Sie unter Fehler.
• Antwortnachricht – die Daten, die Sie angefordert haben, oder das Ergebnis des Vorgangs. Bei einigen Vorgängen kann die Antwortnachricht leer sein.
• @odata.nextLink – wenn Ihre Anfrage eine große Menge an Daten zurückgibt, müssen Sie diese mithilfe der in @odata.nextLink zurückgegebenen URL durchblättern. Einzelheiten finden

HTTP-Methoden

Microsoft Graph verwendet die HTTP-Methode, um zu erfahren, was sie mit Ihrer Anfrage ausführen wollen. Je nach Ressource kann die API-Vorgänge wie Aktionen, Funktionen oder die unten beschriebenen CRUD-Vorgänge unterstützen.

• Für die CRUD-Methoden GET und DELETE ist kein Anfragerumpf erforderlich.
• Die POST-, PATCH- und PUT-Methoden erfordern einen Anfragerumpf, der in der Regel im JSON-Format angegeben wird und zusätzliche Informationen enthält, z. B. Werte für bestimmte Ressourcen-Eigenschaften.

Version

Microsoft Graph unterstützt derzeit zwei Versionen: v1.0 und beta.

• 0 umfasst allgemein verfügbare APIs. Verwenden Sie die Version v1.0 für alle Produktionsanwendungen.
• Beta enthält APIs, die derzeit in der Vorschau sind. Da diese APIs möglicherweise geändert werden, wird empfohlen, die Beta-Version nur zum Testen von Anwendungen zu verwenden, die sich in der Entwicklung befinden.

Ressource

Eine Ressource kann eine Entität oder ein komplexer Typ sein, der in der Regel über gewisse Eigenschaften definiert werden. Entitäten unterscheiden sich von komplexen Typen dadurch, dass sie immer eine id-Eigenschaft enthalten.

Ihre URL enthält die Ressource, mit der Sie in der Anfrage interagieren, z. B. me, user, group, drive und site. Oft enthalten die Ressourcen der obersten Ebene auch Beziehungen, über die Sie auf weitere Ressourcen zugreifen können, wie z. B. me/messages oder me/drive. Sie können auch über Methoden mit Ressourcen interagieren. Um beispielsweise eine E-Mail zu senden, verwenden Sie me/sendMail.

Für jede Ressource können unterschiedliche Zugriffsrechte erforderlich sein. Um eine solche Ressource zu erstellen oder zu aktualisieren, benötigen Sie oft eine höhere Berechtigungsstufe, als um diese zu lesen.

Abfrageparameter

Abfrageparameter können OData-Systemabfrageoptionen oder eine andere Zeichenkette sein, die eine Methode akzeptiert, um ihre Antwort anzupassen.

Sie können optionale OData-Systemabfrageoptionen verwenden, um mehr oder weniger Eigenschaften als die Standardantwort einzuschließen, die Antwort nach Elementen zu filtern, die einer benutzerdefinierten Abfrage entsprechen, oder zusätzliche Parameter für eine Methode anzugeben.

Wenn Sie zum Beispiel den folgenden filter-Parameter hinzufügen, werden nur die Nachrichten zurückgegeben, die die Eigenschaft emailAddress contact@impactory.de haben.

GET https://graph.microsoft.com/v1.0/me/messages?filter=emailAddress eq ‚contact@impactory.de‘

Abgesehen von den OData-Abfrageoptionen erfordern einige Methoden die Angabe von Parameterwerten als Teil der Abfrage-URL. Sie können zum Beispiel eine Sammlung von Ereignissen abrufen, die in einem bestimmten Zeitraum im Kalender eines Benutzers aufgetreten sind, indem Sie die calendarView-Beziehung eines Benutzers abfragen und die Werte startDateTime und endDateTime als Abfrageparameter angeben:

GET https://graph.microsoft.com/v1.0/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Werkzeuge zur Interaktion mit Microsoft Graph

Eines der Tools, die Sie zur Interaktion mit Microsoft Graph verwenden können, ist der Graph Explorer.

Graph Explorer

Graph Explorer ist ein webbasiertes Tool, mit dem Sie Anfragen an das Microsoft-Graph-API erstellen und testen können.

Sie können ohne Anmeldung auf die Demo-Daten zugreifen oder sich bei einem eigenen Mandanten anmelden. Gehen Sie wie folgt vor, um die Anfrage zu erstellen:

1. Wählen Sie die HTTP-Methode.
2. Wählen Sie die von Ihnen gewünschte API-Version aus.
3. Geben Sie die Anfrage in das Textfeld ein.
4. Wählen Sie dann Run Query.

Das folgende Beispiel zeigt eine Anfrage, die Informationen über Benutzer im Demo-Mandanten zurückgibt:

Im Graph Explorer werden Beispielabfragen bereitgestellt, damit Sie gängige Abfragen schneller ausführen können. Um die vorhandenen Beispiele zu sehen, wählen Sie show more samples. Wählen Sie dann die gewünschte Gruppe von Beispielen aus. Nachdem Sie das Auswahlfenster geschlossen haben, sollten Sie nun eine Liste mit vordefinierten Anfragen sehen.

Nach dem Senden einer Anfrage werden ein Statuscode und eine Meldung angezeigt. Die Antwort wird auf der Registerkarte Response preview angezeigt.

PowerShell Code-Schnipsel

Um Microsoft Graph mit PowerShell verwenden zu können, müssen Sie zunächst das Microsoft Graph PowerShell SDK installieren.

Die folgenden Voraussetzungen sind erforderlich, um das Microsoft Graph PowerShell SDK mit Windows PowerShell zu verwenden:

• Upgrade auf PowerShell 5.1 oder höher
• Installation von .NET Framework 4.7.2 oder höher
• Aktualisieren Sie PowerShellGet auf die neueste Version via Install-Module PowerShellGet -Force
• Die Richtlinie für die Ausführung von PowerShell-Skripten muss auf remote signed oder less restrictive eingestellt sein . Verwenden Sie Get-ExecutionPolicy, um die aktuelle Ausführungsrichtlinie zu ermitteln. Um die Ausführungsrichtlinie festzulegen, führen Sie Folgendes aus: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Sobald Sie die Voraussetzungen für die Installation geschaffen haben, können Sie Microsoft Graph für PowerShell installieren. Die Verwendung des cmdlets Install-Module ist die bevorzugte Installationsmethode für das Microsoft Graph PowerShell-Modul.

Führen Sie den folgenden Befehl aus, um das SDK in PowerShell Core oder Windows PowerShell zu installieren.

• Install-Module Microsoft.Graph

Nachdem die Installation abgeschlossen ist, können Sie die installierte Version mit dem folgenden Befehl überprüfen.

• Get-InstalledModule Microsoft.Graph

Nun steht Ihnen die PowerShell für Microsoft Graph zur Verfügung. Mit den erforderlichen Berechtigungen können Sie sich über den Befehl Connect-MgGraph anmelden. Jede API im Microsoft Graph ist durch einen oder mehrere Berechtigungsbereiche geschützt. Der sich anmeldende Benutzer muss einem der erforderlichen Geltungsbereiche für die APIs, die Sie verwenden möchten, zustimmen. Um die erforderlichen Bereiche zu genehmigen, müssen Sie sich dazu mit einem Administratorkonto anmelden. Sie werden dann aufgefordert, eine Webseite zu öffnen, um sich mit einem Gerätecode anzumelden. Ist dies geschehen, zeigt der Vorgang den Erfolg mit der Meldung Welcome To Microsoft Graph!  Sie müssen sich jeweils nur einmal pro Sitzung anmelden.

• Connect-MgGraph -Scopes „User.Read.All“,“Group.ReadWrite.All“

Mit dem Bereich User.Read.All können Sie z. B. Folgendes tun:

• List user , um die Benutzer-ID des angemeldeten Benutzers zu finden
• List joinedTeams , um die Teams zu erhalten, in denen der Benutzer Mitglied ist.

Verwenden Sie den Bereich Group.ReadWrite.All, um:

• Kanäle aufzulisten, um die Kanäle in einem Team zu erhalten.
• Nachricht senden, um eine Nachricht an einen Team-Kanal zu senden.

Wenn Sie nicht wissen, welche Art von Berechtigungen erforderlich sind, verwenden Sie Find-MgGraphCommand. Das cmdlet Find-MgGraphCommand kann verwendet werden, um die erforderlichen Berechtigungen für ein anderes cmdlet zu ermitteln. Um zum Beispiel alle Berechtigungen zu sehen, die zum Aufrufen von Get-MgUser verwendet werden können, führen Sie Folgendes aus:

Find-MgGraphCommand -command Get-MgUser | Select -First 1 -ExpandProperty Permissions

Die Ausgabe sieht in etwa so aus:

Außerdem finden Sie das entsprechende PowerShell-Codefragment im Graph Explorer, nachdem Sie Ihre Abfrage erfolgreich erstellt und ausgeführt haben:

Hier sehen Sie, welche Befehle Sie ausführen können, um die Ausgabe über PowerShell zu erhalten. Graph Explorer bietet Ihnen zudem auch Code-Snippets für CSharp, JavaScript, Java und Go.

Microsoft Graph API-Beispiele

Wo finden Sie einfache Abfragebeispiele für Microsoft Graph? Beachten Sie dazu die linke Seite im Graph Explorer. Graph-Abfragen sind nach Kategorien geordnet:

Erweitern Sie z. B. die Kategorie Applications, um die grundlegenden Abfragen zu sehen, die Sie gegen Ihre Anwendungen ausführen können, oder um eine neue Abfrage zu erstellen:

Wie in diesem Beispiel zu sehen ist, verwenden wir ein Beispielkonto. Um echte Daten zu erhalten, müssen Sie sich zuerst über das Personen-Icon in der oberen rechten Ecke anmelden. Da wir nicht angemeldet sind, sind auch einige der Graphabfragen gesperrt (eine neue Anwendung erstellen, Anwendungseigenschaften aktualisieren, eine Anwendung löschen und einen neuen Eigentümer erstellen).

Schlussfolgerung

Mit Microsoft Graph können Sie die Vorteile einer sicheren, einheitlichen API nutzen, um eine Verbindung zu Daten herzustellen, die sich in verschiedenen Microsoft-365-Diensten befinden. Durch den Zugriff auf diese Daten erhalten die Benutzer die Informationen, die sie benötigen, um schnell Entscheidungen zu treffen und dem Unternehmen einen Wettbewerbsvorteil zu verschaffen. Entwickler können sich schnell mit Microsoft Graph vertraut machen und unternehmensweit auf Daten zugreifen, ohne sich mit der Funktionsweise der einzelnen Microsoft-365-Dienste vertraut machen zu müssen.

Wenn Sie Microsoft Graph noch nicht kennen und nicht wissen, wie Sie in Ihrem Unternehmen anfangen sollen, zögern Sie nicht, uns bei Impactory GmbH zu kontaktieren. Wir verfügen über mehr als 10 Jahre Beratungspraxis in den Bereichen Microsoft 365 und SharePoint.

Zusätzliche Ressourcen

1. Weil Microsoft Viva immer besser wird, sollten Sie sich über die verschiedenen Microsoft-Viva-Module
2. Hier erfahren sie alles über SharePoint, wenn Sie gerade erst mit SharePoint beginnen.
3. Compliance ist ein wichtiges Thema in der Cloud. So machen Sie das SharePoint Intranet DSGVO-konform.