Optimale Methoden für das Arbeiten mit Microsoft GraphBest practices for working with Microsoft Graph

In diesem Artikel werden bewährte Methoden beschrieben, die Sie anwenden können, damit Ihre Anwendungen Microsoft Graph optimal nutzen, ganz gleich, ob es dabei um mehr Informationen zu Microsoft Graph, das Verbessern der App-Leistung oder darum geht, die Anwendung für Endbenutzer zuverlässiger zu gestalten.This article describes best practices that you can apply to help your applications get the most out of Microsoft Graph - whether that involves learning about Microsoft Graph, improving app performance, or making your application more reliable for end users.

Verwenden von Graph-Explorer, um die API kennenzulernenUse Graph Explorer to get to know the API

Der einfachste Weg, um die über Microsoft Graph verfügbaren Daten zu erkunden, besteht darin, Graph-Explorer zu verwenden.The easiest way to start exploring the data available through Microsoft Graph is to use Graph Explorer. Mit Graph-Explorer können Sie REST-Abfragen (mit voller CRUD-Unterstützung) erstellen, die HTTP-Anforderungsheader anpassen und die Datenantworten anzeigen.Graph Explorer lets you craft REST requests (with full CRUD support), adapt the HTTP request headers, and see the data responses. Um Ihnen den Einstieg zu erleichtern, stellt Graph-Explorer auch eine Reihe von Beispielabfragen bereit.To help you get started, Graph Explorer also provides a set of sample queries.

Experimentieren Sie mit neuen APIs, bevor Sie sie in Ihre Anwendung integrieren.Experiment with new APIs before you integrate them into your application.

AuthentifizierungAuthentication

Um auf die Daten in Microsoft Graph zuzugreifen, muss Ihre Anwendung ein OAuth 2.0-Zugriffstoken abrufen und dieses Microsoft Graph in einem der folgenden Elemente präsentieren:To access the data in Microsoft Graph, your application will need to acquire an OAuth 2.0 access token, and present it to Microsoft Graph in either of the following:

  • Dem HTTP-Anforderungsheader für die Autorisierung, als BearertokenThe HTTP Authorization request header, as a Bearer token
  • Dem Graph-Clientkonstruktor, wenn Sie eine Microsoft Graph-Clientbibliothek verwendenThe graph client constructor, when using a Microsoft Graph client library

Verwenden Sie die API der Microsoft-Authentifizierungsbibliothek, MSAL, um das Zugriffstoken für Microsoft Graph zu erhalten.Use the Microsoft Authentication Library API, MSAL to acquire the access token to Microsoft Graph.

Wenden Sie die folgenden bewährten Methoden für Zustimmung und Autorisierung in Ihrer App an:Apply the following best practices for consent and authorization in your app:

  • Verwenden Sie die niedrigsten Berechtigungen.Use least privilege. Fordern Sie nur Berechtigungen an, die unbedingt notwendig sind, und nur dann, wenn Sie sie benötigen.Only request permissions that are absolutely necessary, and only when you need them. Für die APIs in Ihren Anwendungsaufrufen überprüfen Sie den Berechtigungsabschnitt im Thema mit den Methoden (sehen Sie sich beispielsweise Erstellen eines Benutzers an, und wählen Sie die Berechtigungen mit den geringsten Rechten aus).For the APIs your application calls, check the permissions section in the method topics (for example, see creating a user, and choose the least privileged permissions. Eine vollständige Liste von Berechtigungen finden Sie unter Berechtigungsreferenz.For a full list of permissions, see permissions reference.

  • Verwenden Sie den entsprechenden Berechtigungstyp basierend auf Szenarien.Use the correct permission type based on scenarios. Wenn Sie eine interaktive Anwendung erstellen, bei der es einen angemeldeten Benutzer gibt, sollte die Anwendung delegierte Berechtigungen verwenden, sodass der Anwendung die Berechtigung delegiert wird, bei Aufrufen von Microsoft Graph als angemeldeter Benutzer zu fungieren.If you're building an interactive application where a signed in user is present, your application should use delegated permissions, where the application is delegated permission to act as the signed-in user when making calls to Microsoft Graph. Wenn Ihre Anwendung jedoch ohne angemeldeten Benutzer ausgeführt wird, z. B. als Hintergrunddienst oder Daemon, sollte die Anwendung Anwendungsberechtigungen verwenden.If, however, your application runs without a signed-in user, such as a background service or daemon, your application should use application permissions.

    Hinweis: Die Verwendung von Anwendungsberechtigungen für interaktive Szenarien kann für Ihre Anwendung ein Compliance- und Sicherheitsrisiko darstellen.Note: Using application permissions for interactive scenarios can put your application at compliance and security risk. 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.It can inadvertantly elevate a user's privileges to access data, circumnavigating policies configured by an administrator.

  • Gehen Sie beim Konfigurieren Ihr App mit Bedacht vor.Be thoughtful when configuring your app. Dies wirkt sich direkt auf die Erfahrung von Endbenutzern und Administratoren sowie auf die Akzeptanz und die Sicherheit der Anwendung aus.This will directly affect end user and admin experiences, along with application adoption and security. Beispiel:For example:

    • Die Datenschutzrichtlinie Ihrer Anwendung, die Nutzungsbedingungen, der Name, das Logo und die Domäne werden in Zustimmungs- und anderen Oberflächen angezeigt. Stellen Sie daher sicher, dass sie diese sorgfältig konfigurieren, damit bei Ihren Endbenutzern keine Missverständnisse entstehen.Your application's privacy statement, terms of use, name, logo and domain will show up in consent and other experiences - so make sure to configure these carefully so they are understood by your end-users.
    • Überlegen Sie sich, wer Ihrer Anwendung zustimmen soll: Endbenutzer oder Administratoren. Konfigurieren Sie die Anwendung dann so, dass Berechtigungen entsprechend angefordert werden.Consider who will be consenting to your application - either end users or administrators - and configure your application to request permissions appropriately.
    • Sie müssen den Unterschied zwischen statischer, dynamische und inkrementeller Zustimmung verstehen.Ensure that you understand the difference between static, dynamic and incremental consent.
  • Erwägen Sie Anwendungen mit mehreren Mandanten.Consider multi-tenant applications. Gehen Sie davon aus, dass Kunden verschiedene Anwendungs- und Zustimmungssteuerungen in unterschiedlichen Zuständen haben.Expect customers to have various application and consent controls in different states. Beispiel:For example:

    • Mandantenadministratoren können die Möglichkeit für Endbenutzer zum Zustimmen von Anwendungen deaktivieren.Tenant administrators can disable the ability for end users to consent to applications. In diesem Fall müsste ein Administrator im Namen seiner Benutzer zustimmen.In this case, an administrator would need to consent on behalf of their users.
    • 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.Tenant administrators can set custom authorization policies such as blocking users from reading other user's profiles, or limiting self-service group creation to a limited set of users. In diesem Fall sollte Ihre Anwendung die Fehlerantwort 403 verarbeiten können, wenn sie im Auftrag eines Benutzers handelt.In this case, your application should expect to handle 403 error response when acting on behalf of a user.

Effizientes Verarbeiten von AnwortenHandle responses effectively

In Abhängigkeit von den Anforderungen, die an Microsoft Graph gestellt werden, sollten Ihre Anwendungen in der Lage sein, verschiedene Antworttypen zu verarbeiten.Depending on the requests you make to Microsoft Graph, your applications should be prepared to handle different types of responses. Nachfolgend finden Sie einige der wichtigsten Methoden, um sicherzustellen, dass Ihre Anwendung für die Endbenutzer zuverlässig und vorhersehbar reagiert.The following are some of the most important practices to follow to ensure that your application behaves reliably and predictably for your end users.

PaginierungPagination

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.When querying a resource collection, you should expect that Microsoft Graph will the return result set in multiple pages, due to server-side page size limits. 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.When a result set spans multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results.

Eine Auflistung der Nachrichten angemeldeter Benutzer:For example, listing the signed-in users messages:

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.Would return a response containing an @odata.nextLink property, if the result set exceeds the server-side page size limit.

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

Hinweis: Ihre Anwendung sollte immer die Möglichkeit verarbeiten, dass die Antworten paginiert sind, und die @odata.nextLink-Eigenschaft verwenden, um die nächste paginierte Reihe von Ergebnissen zu erhalten, bis alle Seiten des Resultsets gelesen wurden.Note: Your application should always handle the possibility that the responses are paged in nature, and use the @odata.nextLink property to obtain the next paged set of results, until all pages of the result set have been read. Die letzte Seite enthält keine @odata.nextLink-Eigenschaft.The final page will not contain an @odata.nextLink property. 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.You should include the entire URL in the @odata:nextLink property in your request for the next page of results, treating the entire URL as an opaque string.

Weitere Informationen finden Sie unter Paginierung.For more details, see paging.

Behandlung erwarteter FehlerHandling expected errors

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.While your application should handle all error responses (in the 400 and 500 ranges), pay special attention to certain expected errors and responses, listed in the following table.

ThemaTopic HTTP-FehlercodeHTTP error code Bewährte MethodeBest practice
Benutzer hat keinen ZugriffUser does not have access 403403 Wenn Ihre Anwendung läuft, könnte dieser Fehler auch dann auftreten, wenn diese die erforderlichen Berechtigungen über eine Zustimmungsoberfläche erhalten hat.If your application is up and running, it could encounter this error even if it has been granted the necessary permissions through a consent experience. In diesem Fall ist es sehr wahrscheinlich, dass der angemeldete Benutzer nicht über Berechtigungen zum Zugreifen auf die angeforderte Ressource verfügt.In this case, it's most likely that the signed-in user does not have privileges to access the resource requested. Ihre Anwendung sollte den generischen Fehler „Zugriff verweigert“ für den angemeldeten Benutzer ausgeben.Your application should provide a generic "Access denied" error back to the signed-in user.
Nicht gefunden (Not Found)Not found 404404 In bestimmten Fällen wird die angeforderte Ressource möglicherweise nicht gefunden.In certain cases, a requested resource might not be found. Vielleicht ist eine Ressource nicht vorhanden, weil sie noch nicht bereitgestellt wurde (z. B. das Foto eines Benutzers) oder weil sie gelöscht wurde.For example a resource might not exist, because it has not yet been provisioned (like a user's photo) or because it has been deleted. 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.Some deleted resources might be fully restored within 30 days of deletion - such as user, group and application resources, so your application should also take this into account.
DrosselungThrottling 429429 APIs können aus unterschiedlichen Gründen jederzeit eine Drosselung vornehmen, Ihre Anwendung muss daher immer in der Lage sein, 429-Antworten zu behandeln.APIs might throttle at any time for a variety of reasons, so your application must always be prepared to handle 429 responses. Im HTTP-Antwortheader der Fehlerantwort ist das Feld Retry-After enthalten.This error response includes the Retry-After field in the HTTP response header. Das Zurückziehen von Anforderungen mithilfe der Verzögerung Retry-After ist die schnellste Möglichkeit zur Wiederherstellung nach einer Drosselung.Backing off requests using the Retry-After delay is the fastest way to recover from throttling. Weitere Informationen finden Sie unter Drosselung.For more information, see throttling.
Dienst nicht verfügbar (Service Unavailable)Service unavailable 503503 Dieser Fehler tritt wahrscheinlich auf, weil der Dienst ausgelastet ist.This is likely because the services is busy. In diesem Fall sollten Sie die Strategie des Zurückziehens ähnlich wie bei Fehler 429 anwenden.You should employ a back-off strategy similar to 429. Außerdem sollten Sie immer neue Wiederholanforderungen über eine neue HTTP-Verbindung ausführen.Additionally, you should always make new retry requests over a new HTTP connection.

Entwickelbare EnumerationenEvolvable enums

Clientanwendungen können durch das Hinzufügen von Membern zu einer vorhandenen Enumeration beschädigt werden.Client applications can be broken by the addition of members to an existing enum. Für einige neuere Enumerationen in Microsoft Graph gibt es einen Mechanismus, der das Hinzufügen neuer Member ermöglicht, ohne das hierfür eine wesentliche Änderung erforderlich ist.For some newer enums in Microsoft Graph, a mechanism is available to allow for adding new members without incurring a breaking change. In diesen neueren Enumerationen werden Sie ein sentinel-Element namens unknownFutureValue bemerken, das bekannte und unbekannte Enumerationsmember abgrenzt.On these newer enums, you'll see a common sentinel member called unknownFutureValue that demarcates known and unknown enum members. Bekannte Member weisen eine niedrigeren Wert als das Sentinel-Member auf, unbekannte Member hingegen einen größeren Wert.Known members will have a number less than the sentinel member, while unknown members will be greater in value. Unbekannte Member werden standardmäßig nicht von Microsoft Graph zurückgegeben.By default, unknown members are not returned by Microsoft Graph. Wenn Ihre Anwendung jedoch so geschrieben wurde, dass das Vorkommen unbekannter Member verarbeitet wird, können unbekannte Enumerationsmember mithilfe des HTTP-Anforderungsheaders Prefer empfangen werden.If, however, your application is written to handle the appearance of unknown members, it can opt-in to receive unknown enum members, using an HTTP Prefer request header.

Hinweis: Wenn Ihre Anwendung in der Lage ist, unbekannte Enumerationsmember zu verarbeiten, sollte das Abonnieren über den HTTP-Anforderungsheader prefer erfolgen: Prefer: include-unknown-enum-members.Note: If your application is prepared to handle unknown enum members, it should opt-in by using an HTTP prefer request header: Prefer: include-unknown-enum-members.

Lokales Speichern von DatenStoring data locally

Im Idealfall sollte Ihre Anwendung Aufrufe von Microsoft Graph zum Abrufen von Daten in Echtzeit tätigen, wenn erforderlich.Your application should ideally make calls to Microsoft Graph to retrieve data in real time as necessary. 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.You should only cache or store data locally if required for a specific scenario, and if that use case is covered by your terms of use and privacy policy, and does not violate the Microsoft Graph terms of use. Ihre Anwendung sollte auch entsprechende Aufbewahrungs- und Löschrichtlinien implementieren.Your application should also implement proper retention and deletion policies.

OptimierungenOptimizations

Im Allgemeinen sollten Sie aus Leistungs-, Sicherheits- und Datenschutzgründen nur die Daten abrufen, die Ihre Anwendung wirklich benötigt und nicht mehr.In general, for performance and even security or privacy reasons, you should only get the data your application really needs, and nothing more.

Verwenden von PrognosenUse projections

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.Choose only the properties your application really needs and no more, because this saves unnecessary network traffic and data processing in your application (and in the service).

Hinweis: Verwenden Sie den $select-Abfrageparameter, um die von einer Abfrage zurückgegebenen Eigenschaften auf diejenigen zu beschränken, die von Ihrer App benötigt werden.Note: Use the $select query parameter to limit the properties returned by a query to those needed by your application.

Wenn Sie z. B. die Nachrichten des angemeldeten Benutzers abrufen, können Sie angeben, dass nur die Eigenschaften from und subject zurückgegeben werden:For example, when retrieving the messages of the signed-in user, you can specify that only the from and subject properties be returned:

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

Abrufen minimaler AntwortenGetting minimal responses

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.For some operations, such as PUT and PATCH (and in some cases POST), if your application doesn't need to make use of a response payload, you can ask the API to return minimal data. Beachten Sie, dass einige Dienste bereits die Antwort 204 „Kein Inhalt“ für PUT- und PATCH-Vorgänge zurückgeben.Note that some services already return a 204 No Content response for PUT and PATCH operations.

Hinweis: Fordern Sie ggf. minimale Darstellungsantworten mithilfe eines HTTP-Anforderungsheaders an: Prefer: return=minimal.Note: Request minimal representation responses using an HTTP request header where appropriate: Prefer: return=minimal. Beachten Sie, dass dies für Erstellungsvorgänge möglicherweise nicht geeignet ist, da Ihre Anwendung vielleicht erwartet, dass der Dienst id für das neu erstellte Objekt in der Antwort generiert wird.Note that for creation operations, this might not be appropriate because your application may expect to get the service generated id for the newly created object in the response.

Nachverfolgen von Änderungen: Delta-Abfrage und Webhook-BenachrichtigungenTrack changes: delta query and webhook notifications

Wenn Ihre Anwendung über Änderungen an Daten informiert sein muss, können Sie eine Webhook-Benachrichtigung erhalten, wenn sich Daten geändert haben.If your application needs to know about changes to data, you can get a webhook notification whenever data of interest has changed. Dies ist effizienter als das bloße Abfragen in regelmäßigen Abständen.This is more efficient than simply polling on a regular basis.

Verwenden Sie Webhook-Benachrichtigungen, um Pushbenachrichtigungen zu erhalten, wenn sich Daten geändert werden.Use webhook notifications to get push notifications when data changes.

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.If your application is required to cache or store Microsoft Graph data locally, and keep that data up to date, or track changes to data for any other reasons, you should use delta query. 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.This will avoid excessive computation by your application to retrieve data your application already has, minimize network traffic, and reduce the likelihood of reaching a throttling threshold.

Verwenden Sie eine Delta-Abfrage, um Daten effizient auf dem neuesten Stand zu halten.Use delta query to efficiently keep data up to date.

Gemeinsames Verwenden von Webhooks und Delta-AbfragenUsing webhooks and delta query together

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.Webhooks and delta query are often used better together, because if you use delta query alone, you need to figure out the right polling interval - too short and this might lead to empty responses which wastes resources, too long and you might end up with stale data. Wenn Sie Webhook-Benachrichtigungen als Auslöser für Aufrufe von Delta-Abfragen verwenden, können Sie die Vorteile von beiden Ansätzen nutzen.If you use webhook notifications as the trigger to make delta query calls, you get the best of both worlds.

Verwenden Sie Webhook-Benachrichtigungen als Auslöser für Aufrufe von Delta-Abfragen.Use webhook notifications as the trigger to make delta query calls. Sie sollten auch sicherstellen, dass Ihre Anwendung einen Abfrageschwellenwert aufweist, für den Fall, dass keine Benachrichtigungen ausgelöst werden.You should also ensure that your application has a backstop polling threshold, in case no notifications are triggered.

BatchverarbeitungBatching

Die JSON-Batchverarbeitung ermöglicht es Ihnen, Ihre Anwendung durch Kombinieren von mehreren Anforderungen in einem einzigen JSON-Objekt zu optimieren.JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. Indem Sie die einzelnen Anforderungen in einer einzigen Batchanforderung kombinieren, können Sie die Netzwerklatenz der Anwendung erheblich reduzieren und Verbindungsressourcen einsparen.Combining individual requests into a single batch request can save the application significant network latency and can conserve connection resources.

Verwenden Sie die Batchverarbeitung, wenn eine erhebliche Netzwerklatenz wesentliche Auswirkungen auf die Leistung haben kann.Use batching where significant network latency can have a big impact on the performance.

Zuverlässigkeit und SupportReliability and support

So stellen Sie sicher, dass Zuverlässigkeit und Support für Ihre Anwendung gewährleistet sind:To ensure reliability and facilitate support for your application:

  • Berücksichtigen Sie die DNS-TTL, und legen Sie die Verbindungs-TTL entsprechend fest.Honor DNS TTL and set connection TTL to match it. Dadurch wird die Verfügbarkeit im Falle eines Failovers sichergestellt.This ensures availability in case of failovers.
  • Öffnen Sie Verbindungen für alle angekündigten DNS-Antworten.Open connections to all advertised DNS answers.
  • Generieren Sie eine eindeutige GUID, und senden Sie sie bei jeder Microsoft Graph-REST- Anforderung mit.Generate a unique GUID and send it on each Microsoft Graph REST request. Dies hilft Microsoft bei der Untersuchung von Fehlern, wenn Sie ein Problem mit Microsoft Graph melden müssen.This will help Microsoft investigate any errors more easily if you need to report an issue with Microsoft Graph.
    • 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.On every request to Microsoft Graph, generate a unique GUID, send it in the client-request-id HTTP request header, and also log it in your application's logs.
    • Protokollieren Sie immer request-id, timestamp und x-ms-ags-diagnostic aus dem HTTP-Antwort-Header.Always log the request-id, timestamp and x-ms-ags-diagnostic from the HTTP response headers. Diese sind zusammen mit der client-request-id erforderlich, wenn Sie Probleme in Stack Overflow oder dem Microsoft-Support melden.These, together with the client-request-id, are required when reporting issues in Stack Overflow or to Microsoft Support.