Freigeben über

Optimale Methoden für das Arbeiten mit Microsoft Graph

  • Artikel

In diesem Artikel werden bewährte Methoden beschrieben, die Sie anwenden können, um Ihre Anwendungen dabei zu unterstützen, Microsoft Graph optimal zu nutzen– ganz gleich, ob sie sich mit Microsoft Graph vertraut machen, die App-Leistung verbessern oder Ihre Anwendung für Endbenutzer zuverlässiger machen.

Verwenden von Graph-Explorer, um die API kennenzulernen

Der einfachste Weg, um die über Microsoft Graph verfügbaren Daten zu erkunden, besteht darin, Graph-Explorer zu verwenden. Mit Graph-Explorer können Sie REST-Abfragen (mit voller CRUD-Unterstützung) erstellen, die HTTP-Anforderungsheader anpassen und die Datenantworten anzeigen. Um Ihnen den Einstieg zu erleichtern, stellt Graph-Explorer auch eine Reihe von Beispielabfragen bereit.

Experimentieren Sie mit neuen APIs, bevor Sie sie in Ihre Anwendung integrieren.

Authentifizierung

Um auf Daten über Microsoft Graph zuzugreifen, muss Ihre Anwendung ein OAuth 2.0-Zugriffstoken abrufen und dieses Microsoft Graph mit einer der folgenden Optionen übergeben:

  • Dem HTTP-Anforderungsheader für die Autorisierung, als Bearertoken
  • Dem Graph-Clientkonstruktor, wenn Sie eine Microsoft Graph-Clientbibliothek verwenden

Verwenden Sie die API der Microsoft-Authentifizierungsbibliothek, MSAL, um das Zugriffstoken für Microsoft Graph zu erhalten.

Wenden Sie die folgenden bewährten Methoden für Zustimmung und Autorisierung in Ihrer App an:

  • Wenden Sie die niedrigsten Berechtigungen an. Erteilen Sie Benutzern und Apps nur die niedrigste Berechtigung, die sie zum Aufrufen der API benötigen. Überprüfen Sie den Abschnitt über Berechtigungen im Thema zu den Methoden (sehen Sie sich beispielsweise Erstellen eines Benutzers an, und wählen Sie die Berechtigungen mit den geringsten Rechten aus). Wenn die App beispielsweise nur das Profil des aktuell angemeldeten Benutzers liest, erteilen Sie die User.Read- anstelle der User.ReadBasic.All-Berechtigung. Wenn eine App den Kalender des Benutzers nicht liest, erteilen Sie ihm nicht die Berechtigung Calendars.Read. Eine vollständige Liste von Berechtigungen finden Sie unter Berechtigungsreferenz.

  • Verwenden Sie den entsprechenden Berechtigungstyp basierend auf Szenarien. Vermeiden Sie die Verwendung von Anwendungsberechtigungen und delegierten Berechtigungen in derselben App. Wenn Sie eine interaktive Anwendung erstellen, bei der es einen angemeldeten Benutzer gibt, sollte die Anwendung delegierte Berechtigungen verwenden. Wenn Ihre Anwendung jedoch ohne angemeldeten Benutzer ausgeführt wird, z. B. als Hintergrunddienst oder Daemon, sollte die Anwendung Anwendungsberechtigungen verwenden.

    Achtung

    Die Verwendung von Anwendungsberechtigungen für interaktive Szenarien kann für Ihre Anwendung ein Compliance- und Sicherheitsrisiko darstellen. Die Berechtigungen eines Benutzers könnten versehentlich erhöht werden, sodass dieser auf Daten zugreifen kann, wodurch die von einem Administrator konfigurierten Richtlinien umgangen werden.

  • Gehen Sie beim Konfigurieren Ihr App mit Bedacht vor. Dies wirkt sich direkt auf die Erfahrung von Endbenutzern und Administratoren sowie auf die Akzeptanz und die Sicherheit der Anwendung aus. Beispiel:

    • Name, Logo, Domäne, Herausgeberüberprüfungsstatus, Datenschutzbestimmungen und Nutzungsbedingungen Ihrer Anwendung werden in Zustimmungs- und anderen Oberflächen angezeigt. Konfigurieren Sie diese Einstellungen sorgfältig, damit sie von Ihren Endbenutzern verstanden werden.
    • Überlegen Sie sich, wer Ihrer Anwendung zustimmen soll: Endbenutzer oder Administratoren. Konfigurieren Sie die Anwendung dann so, dass Berechtigungen entsprechend angefordert werden.
    • Sie müssen den Unterschied zwischen statischer, dynamische und inkrementeller Zustimmung verstehen.

  • Erwägen Sie Anwendungen mit mehreren Mandanten. Gehen Sie davon aus, dass Kunden verschiedene Anwendungs- und Zustimmungssteuerungen in unterschiedlichen Zuständen haben. Beispiel:

    • Mandantenadministratoren können die Möglichkeit für Endbenutzer zum Zustimmen von Anwendungen deaktivieren. In diesem Fall müsste ein Administrator im Namen seiner Benutzer zustimmen.
    • Mandantenadministratoren können benutzerdefinierte Autorisierungsrichtlinien festlegen, z. B., dass Benutzer nicht die Profile anderer Benutzer lesen können, oder das Beschränken der Self-Service-Gruppenerstellung auf eine eingeschränkte Gruppe von Benutzern. In diesem Fall sollte Ihre Anwendung die Fehlerantwort 403 Forbidden verarbeiten können, wenn sie im Auftrag eines Benutzers handelt.

Effizientes Verarbeiten von Anworten

In Abhängigkeit von den Anforderungen, die an Microsoft Graph gestellt werden, sollten Ihre Anwendungen in der Lage sein, verschiedene Antworttypen zu verarbeiten. Nachfolgend finden Sie einige der wichtigsten Methoden, um sicherzustellen, dass Ihre Anwendung für die Endbenutzer zuverlässig und vorhersehbar reagiert.

Paginierung

Beim Abfragen einer Ressourcensammlung sollten Sie davon ausgehen, dass Microsoft Graph das Resultset aufgrund von serverseitigen Beschränkungen der Seitengröße auf mehreren Seiten zurückgibt. Wenn sich ein Resultset über mehrere Seiten erstreckt, gibt Microsoft Graph eine @odata.nextLink-Eigenschaft in der Antwort zurück, die eine URL zu der nächsten Seite mit Ergebnissen enthält.

Eine Auflistung der Nachrichten angemeldeter Benutzer:

GET https://graph.microsoft.com/v1.0/me/messages

Würde eine Antwort mit einer @odata.nextLink-Eigenschaft zurückgeben, wenn das Resultset die serverseitige Beschränkung der Seitengröße überschreitet.

"@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=23"

Hinweis

Ihre Anwendung sollte immer mit der Möglichkeit umgehen, dass die Antworten seitenweise sind, und die @odata.nextLink Eigenschaft verwenden, um die nächste seitenweise Ergebnismenge zu erhalten, bis alle Seiten der Ergebnismenge gelesen worden sind. Die letzte Seite enthält keine @odata.nextLink-Eigenschaft. Sie sollten die gesamte URL in die @odata.nextLink-Eigenschaft in Ihrer Anforderung für die nächste Seite mit Ergebnissen einschließen, wobei die gesamte URL als opake Zeichenfolge behandelt wird.

Weitere Informationen finden Sie unter Paginierung.

Behandlung erwarteter Fehler

Ihre Anwendung sollte zwar alle Fehlerantworten (in den Bereichen 400 und 500) behandeln, besonderes Augenmerk liegt jedoch auf bestimmten erwarteten Fehlern und Antworten, die in der folgenden Tabelle aufgeführt sind.

Thema HTTP-Fehlercode Bewährte Methode
Benutzer hat keinen Zugriff 403 Wenn Ihre Anwendung läuft, könnte dieser Fehler auch dann auftreten, wenn diese die erforderlichen Berechtigungen über eine Zustimmungsoberfläche erhalten hat. In diesem Fall ist es sehr wahrscheinlich, dass der angemeldete Benutzer nicht über Berechtigungen zum Zugreifen auf die angeforderte Ressource verfügt. Ihre Anwendung sollte den generischen Fehler „Zugriff verweigert“ für den angemeldeten Benutzer ausgeben.
Nicht gefunden (Not Found) 404 In bestimmten Fällen wird die angeforderte Ressource möglicherweise nicht gefunden. Vielleicht ist eine Ressource nicht vorhanden, weil sie noch nicht bereitgestellt wurde (z. B. das Foto eines Benutzers) oder weil sie gelöscht wurde. Einige gelöschte Ressourcen können innerhalb von 30 Tagen nach dem Löschen vollständig wiederhergestellt werden – z. B. Benutzer, Gruppen und Anwendungsressourcen, Ihre Anwendung sollte dies daher auch berücksichtigen.
Drosselung 429 APIs können aus unterschiedlichen Gründen jederzeit eine Drosselung vornehmen, Ihre Anwendung muss daher immer in der Lage sein, 429-Antworten zu behandeln. Im HTTP-Antwortheader der Fehlerantwort ist das Feld Retry-After enthalten. Das Zurückziehen von Anforderungen mithilfe der Verzögerung Retry-After ist die schnellste Möglichkeit zur Wiederherstellung nach einer Drosselung. Weitere Informationen finden Sie unter Drosselung.
Dienst nicht verfügbar (Service Unavailable) 503 Dieser Fehler tritt wahrscheinlich auf, weil der Dienst ausgelastet ist. In diesem Fall sollten Sie die Strategie des Zurückziehens ähnlich wie bei Fehler 429 anwenden. Außerdem sollten Sie immer neue Wiederholanforderungen über eine neue HTTP-Verbindung ausführen.

Behandeln zukünftiger Member in optimierbaren Enumerationen

Das Hinzufügen von Membern zu vorhandenen Enumerationen kann Anwendungen unterbrechen, die diese Enumerationen bereits verwenden. Die optimierbaren Enumerationen sind ein Mechanismus, den Microsoft Graph API verwendet, um vorhandenen Enumerationen neue Member hinzuzufügen, ohne dass dies zu einer Breaking Change für Anwendungen führt.

Für optimierbaren Enumerationen gibt es einen gemeinsamen Sentinel-Member namens unknownFutureValue, der bekannte Member abgrenzt, die anfänglich in der Enumeration definiert wurden, und unbekannte Member, die später hinzugefügt werden oder in Zukunft definiert werden. Intern werden bekannte Member numerischen Werten zugeordnet, die kleiner als der Sentinelmember sind, und unbekannte Member sind größer als der Sentinelmember. In der Dokumentation für eine optimierbaren Enumerationen werden die möglichen Zeichenfolgen-Werte in aufsteigender Reihenfolge aufgelistet: bekannte Member, gefolgt von unknownFutureValue, gefolgt von unbekannten Elementen. Wie bei anderen Enumerationstypen sollten Sie Member von optimierbaren Enumerationen immer nach ihren Zeichenfolge-Werten referenzieren.

Standardmäßig gibt ein GET-Vorgang nur bekannte Member für Eigenschaften von optimierbaren Enumerationstypen zurück, und Ihre Anwendung muss nur die bekannten Member behandeln. Wenn Sie Ihre Anwendung so entwerfen, dass sie auch unbekannte Member behandelt, können Sie sich für den Empfang dieser Member anmelden, indem Sie einen HTTPPrefer-Anforderungsheader verwenden:

Prefer: include-unknown-enum-members

Lokales Speichern von Daten

Im Idealfall sollte Ihre Anwendung Aufrufe von Microsoft Graph zum Abrufen von Daten in Echtzeit tätigen, wenn erforderlich. Daten sollten nur dann zwischengespeichert oder lokal gespeichert werden, wenn dies für ein bestimmtes Szenario erforderlich ist und wenn dieser Anwendungsfall von Ihren Nutzungsbedingungen und Ihrer Datenschutzbestimmung abgedeckt ist und nicht gegen die Nutzungsbedingungen von Microsoft APIs verstößt. Ihre Anwendung sollte auch entsprechende Aufbewahrungs- und Löschrichtlinien implementieren.

Optimierungen

Im Allgemeinen sollten Sie aus Leistungs-, Sicherheits- und Datenschutzgründen nur die Daten abrufen, die Ihre Anwendung wirklich benötigt und nicht mehr.

Verwenden von Prognosen

Wählen Sie nur die Eigenschaften aus, die Ihre Anwendung wirklich benötigt, da dadurch unnötiger Netzwerkverkehr und unnötige Datenverarbeitungen in Ihrer Anwendung (und im Dienst) verhindert werden.

Hinweis

Verwenden Sie den $select Abfrageparameter, um die von einer Abfrage zurückgegebenen Eigenschaften auf diejenigen zu beschränken, die von Ihrer Anwendung benötigt werden.

Wenn Sie z. B. die Nachrichten des angemeldeten Benutzers abrufen, können Sie angeben, dass nur die Eigenschaften from und subject zurückgegeben werden:

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject

Wenn Sie eine GET-Anforderung ausführen, ohne $select die Menge der Eigenschaftendaten zu begrenzen, enthält Microsoft Graph eine @microsoft.graph.tips-Eigenschaft , die eine Empfehlung für bewährte Methoden für die Verwendung $select ähnlich der folgenden Meldung bietet:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Abrufen minimaler Antworten

Für einige Vorgänge, z. B. PUT und PATCH (und in einigen Fällen POST), können Sie die API auffordern, minimale Daten zurückzugeben, wenn die Anwendung keine Antwortnutzlast nutzen muss. Beachten Sie, dass einige Dienste bereits eine 204 No Content Antwort für PUT- und PATCH-Vorgänge zurückgeben.

Hinweis

Fordern Sie Minimale Darstellungsantworten an, indem Sie den auf festgelegten return=minimalPrefer-Header verwenden, sofern dies unterstützt wird. Für Erstellungsvorgänge ist die Verwendung dieses Headers möglicherweise nicht geeignet, da Ihre Anwendung möglicherweise erwartet, dass der Dienst in der Antwort für das neu erstellte Objekt generiert wird id .

Nachverfolgen von Änderungen: Delta-Abfrage und Webhook-Benachrichtigungen

Wenn Ihre Anwendung über Änderungen an Daten informiert sein muss, können Sie eine Webhook-Benachrichtigung erhalten, wenn sich Daten geändert haben. Dies ist effizienter als das bloße Abfragen in regelmäßigen Abständen.

Verwenden Sie Webhook-Benachrichtigungen, um Pushbenachrichtigungen zu erhalten, wenn sich Daten geändert werden.

Wenn Ihre Anwendung Microsoft Graph-Daten lokal zwischenspeichern oder speichern, diese Daten auf dem neuesten Stand halten oder aus anderen Gründen Änderungen an Daten verfolgen muss, sollten Sie eine Delta-Abfrage verwenden. Dadurch werden übermäßige Berechnungen von Ihrer Anwendung zum Abrufen von Daten verhindert, über die die Anwendung bereits verfügt, der Netzwerkdatenverkehr minimiert und die Wahrscheinlichkeit reduziert, dass ein Drosselungsschwellenwert erreicht wird.

Verwenden Sie eine Delta-Abfrage, um Daten effizient auf dem neuesten Stand zu halten.

Gemeinsames Verwenden von Webhooks und Delta-Abfragen

Webhooks und Delta-Abfragen werden häufig in Kombination besser verwendet, denn wenn Sie eine Delta-Abfrage alleine verwenden, müssen Sie das richtige Abfrageintervall ermitteln: wenn dieses zu kurz ist, kommt es zu leeren Antworten, wodurch Ressourcen verschwendet werden, wenn es zu lang ist, führt dies zu veralteten Daten. Wenn Sie Webhook-Benachrichtigungen als Auslöser für Aufrufe von Delta-Abfragen verwenden, können Sie die Vorteile von beiden Ansätzen nutzen.

Verwenden Sie Webhook-Benachrichtigungen als Auslöser für Aufrufe von Delta-Abfragen. Sie sollten auch sicherstellen, dass Ihre Anwendung einen Abfrageschwellenwert aufweist, für den Fall, dass keine Benachrichtigungen ausgelöst werden.

Batchverarbeitung

Die JSON-Batchverarbeitung ermöglicht es Ihnen, Ihre Anwendung durch Kombinieren von mehreren Anforderungen in einem einzigen JSON-Objekt zu optimieren. Indem Sie die einzelnen Anforderungen in einer einzigen Batchanforderung kombinieren, können Sie die Netzwerklatenz der Anwendung erheblich reduzieren und Verbindungsressourcen einsparen.

Verwenden Sie die Batchverarbeitung, wenn eine erhebliche Netzwerklatenz wesentliche Auswirkungen auf die Leistung haben kann.

Zuverlässigkeit und Support

So stellen Sie sicher, dass Zuverlässigkeit und Support für Ihre Anwendung gewährleistet sind:

  • Verwenden Sie TLS 1.2, um alle Funktionen von Microsoft Graph zu unterstützen. Weitere Informationen zur Einstellung von Microsoft Graph TLS 1.0 und 1.1 finden Sie unter Aktivieren der Unterstützung für TLS 1.2 in Ihrer Umgebung.
  • Berücksichtigen Sie die DNS-TTL, und legen Sie die Verbindungs-TTL entsprechend fest. Dadurch wird die Verfügbarkeit im Falle eines Failovers sichergestellt.
  • Öffnen Sie Verbindungen für alle angekündigten DNS-Antworten.
  • Generieren Sie eine eindeutige GUID, und senden Sie sie bei jeder Microsoft Graph-REST- Anforderung mit. Dies hilft Microsoft bei der Untersuchung von Fehlern, wenn Sie ein Problem mit Microsoft Graph melden müssen.
    • Generieren Sie bei jeder Anforderung an Microsoft Graph eine eindeutige GUID, senden Sie diese im client-request-id-HTTP-Anforderungs-Header, und protokollieren Sie diese in Ihren Anwendungsprotokollen.
    • Protokollieren Sie immer und request-idDate aus den HTTP-Antwortheadern. Diese sind zusammen mit der client-request-id erforderlich, wenn Sie Probleme in Microsoft Q&A oder dem Microsoft-Support melden.