Hinzufügen von benutzerdefinierten Daten zu Ressourcen mithilfe von ErweiterungenAdd custom data to resources using extensions

Microsoft Graph stellt einen zentralen API-Endpunkt bereit, der Ihnen über verschiedene Ressourcen wie user und message Zugriff auf umfassende personenzentrierte Daten und Erkenntnisse ermöglicht. Sie können auch Microsoft Graph um eigene Anwendungsdaten erweitern. Sie können Microsoft Graph-Ressourcen benutzerdefinierte Eigenschaften hinzufügen, ohne dass dafür ein externer Datenspeicher nötig wäre.Microsoft Graph provides a single API endpoint that gives you access to rich people-centric data and insights through a number of resources such as user and message. You can also extend Microsoft Graph with your own application data. You can add custom properties to Microsoft Graph resources without requiring an external data store.

So könnten Sie sich beispielsweise entscheiden, Ihre App schlank zu halten und App-spezifische Benutzerprofildaten in Microsoft Graph zu speichern, indem Sie die Ressource user erweitern.For example, you might decide to keep your app lightweight and store app-specific user profile data in Microsoft Graph by extending the user resource. Alternativ könnten Sie den vorhandenen Benutzerprofilspeicher Ihrer App auch beibehalten und der Ressource user einfach einen App-spezifischen Speicherbezeichner hinzufügen.Alternatively, you might want to retain your app’s existing user profile store, and simply add an app-specific store identifier to the user resource.

Microsoft Graph bietet zwei Arten von Erweiterungen. Wählen Sie den Erweiterungstyp aus, der Ihren Anwendungsanforderungen am besten entspricht:Microsoft Graph offers two types of extensions. Choose the extension type that best suits your application needs:

  • Offene Erweiterungen: Dieser Erweiterungstyp ist ideal für die ersten Schritte mit Erweiterungen.Open extensions: A good way for developers to get started.
  • Schemaerweiterungen: Bei diesem Erweiterungstyp handelt es sich um einen flexibleren Mechanismus für Entwickler, die typisierte Daten speichern, ihr Schema erkennbar und gemeinsam nutzbar machen, Filteroptionen nutzen und später auch Autorisierung und die Überprüfung von Eingabedaten implementieren möchten.Schema extensions: A more versatile mechanism for developers who care about storing typed data, making their schema discoverable and shareable, being able to filter, and in the future, being able to perform input data validation and authorization.

Wichtig: Sie sollten Erweiterungen nicht zur Speicherung vertraulicher personenbezogener Informationen wie Kontoanmeldeinformationen, Behördenkennnummern, Karteninhaberdaten, Bankkontonummern, Krankendaten oder vertraulichen Hintergrundinformationen verwenden.Important: You should not use extensions to store sensitive personally identifiable information, such as account credentials, government identification numbers, cardholder data, financial account data, healthcare information, or sensitive background information.

Unterstützte RessourcenSupported resources

In der folgenden Tabelle sind die Ressourcen aufgeführt, die offene Erweiterungen und Schemaerweiterungen unterstützen und angeben, ob sie die allgemeine Verfügbarkeit (GA) erreicht haben (verfügbar sowohl in v1.0- und Beta-Endpunkten) oder sich in der Vorschau befinden (nur im Beta-Endpunkt verfügbar).The following table lists the resources that support open and schema extensions, and indicates whether they have reached general availability (GA - available in both the v1.0 and beta endpoints) or are in preview (available only in the beta endpoint).

RessourceResource Offene ErweiterungenOpen extensions SchemaerweiterungenSchema extensions
Administrative EinheitAdministrative unit Nur VorschauPreview only Nur VorschauPreview only
KalenderereignisCalendar event Allgemein verfügbarGA Allgemein verfügbarGA
GerätDevice Allgemein verfügbarGA Allgemein verfügbarGA
GruppeGroup Allgemein verfügbarGA Allgemein verfügbarGA
Kalenderereignis für GruppeGroup calendar event Allgemein verfügbarGA Allgemein verfügbarGA
Beitrag zu GruppenunterhaltungGroup conversation post Allgemein verfügbarGA Allgemein verfügbarGA
NachrichtMessage Allgemein verfügbarGA Allgemein verfügbarGA
OrganisationOrganization Allgemein verfügbarGA Allgemein verfügbarGA
Privater KontaktPersonal contact Allgemein verfügbarGA Allgemein verfügbarGA
BenutzerUser Allgemein verfügbarGA Allgemein verfügbarGA

Sie können Erweiterungen für alle diese Ressourcen verwenden, wenn Sie mit einem Geschäfts-, Schul- oder Unikonto angemeldet sind.You can use extensions on all these resources when signed in with a work or school account. Darüber hinaus können Sie Erweiterungen für die folgenden Ressourcen verwenden, wenn Sie mit einem persönlichen Konto angemeldet sind: event, post, group, message, contact und user.In addition, you can use extensions on the event, post, group, message, contact, and user resources when signed in with a personal account.

Offene ErweiterungenOpen extensions

Offene Erweiterungen (früher als Office 365-Datenerweiterungen bezeichnet) sind offene Typen, die eine flexible Möglichkeit zum direkten Hinzufügen nicht typisierter App-Daten zu Ressourceninstanzen bieten.Open extensions (formerly known as Office 365 data extensions) are open types that offer a flexible way to add untyped app data directly to a resource instance.

Offene Erweiterungen und die zugehörigen benutzerdefinierten Daten sind über die Navigationseigenschaft extensions der Ressourceninstanz verfügbar.Open extensions, together with their custom data, are accessible through the extensions navigation property of the resource instance. Die Eigenschaft extensionName ist die einzige vordefinierte beschreibbare Eigenschaft einer offenen Erweiterung.The extensionName property is the only pre-defined, writable property in an open extension. Bei der Erstellung einer offenen Erweiterung müssen Sie der Eigenschaft extensionName einen Namen zuweisen, der innerhalb des Mandanten eindeutig ist.When creating an open extension, you must assign the extensionName property a name that is unique within the tenant.

Eine Möglichkeit hierfür ist die Verwendung eines umgekehrten DNS (Domain Name System)-Formats, das von Ihrer eigenen Domäne abhängt, zum Beispiel Com.Contoso.ContactInfo.One way to do this is to use a reverse domain name system (DNS) format that is dependent on your own domain, for example, Com.Contoso.ContactInfo.

Verwenden Sie in Erweiterungsnamen auf keinen Fall die Microsoft-Domäne (Com.Microsoft oder Com.OnMicrosoft).Do not use the Microsoft domain (Com.Microsoft or Com.OnMicrosoft) in an extension name.

Sie können im Rahmen ein und desselben Vorgangs eine offene Erweiterung in einer Ressourceninstanz erstellen und benutzerdefinierte Daten in ihr speichern. (Beachten Sie dabei die bekannte Einschränkung für einige der unterstützten Ressourcen.)You can create an open extension in a resource instance and store custom data to it all in the same operation (note known limitation for some of the supported resources).

Anschließend können Sie die Erweiterung und ihre Daten lesen, aktualisieren und löschen.You can subsequently read, update, or delete the extension and its data.

Beispiel für eine offene Erweiterung: Hinzufügen von benutzerdefinierten Daten zu Benutzern mithilfe offener ErweiterungenOpen extension example: Add custom data to users using open extensions

SchemaerweiterungenSchema extensions

Mithilfe von Schemaerweiterungen können Sie ein Schema definieren, das einen Ressourcentyp erweitert. Zunächst erstellen Sie eine Schemaerweiterungsdefinition. Diese verwenden Sie dann, um Ressourceninstanzen um stark typisierte benutzerdefinierte Daten zu erweitern. Sie können auch den Status Ihrer Schemaerweiterung steuern und sie so für andere Apps erkennbar machen. Die Apps können die Erweiterung dann auf ihre eigenen Daten anwenden und auf ihrer Grundlage weitere Funktionen implementieren.Schema extensions allow you to define a schema that you can use to extend a resource type. First, you create your schema extension definition. Then, use it to extend resource instances with strongly-typed custom data. In addition, you can control the status of your schema extension and let it be discoverable by other apps. These apps can in turn use the extension for their data and build further experiences on top of it.

Beim Erstellen einer Schemaerweiterungsdefinition müssen Sie einen eindeutigen Namen für die ID angeben. Es stehen zwei Benennungsoptionen zur Verfügung:When creating a schema extension definition, you must provide a unique name for its id. There are two naming options:

  • Wenn Sie bereits über eine Vanity-.com-, .net-, .gov-, .edu- oder .org-Domäne verfügen, die Sie für Ihren Mandanten überprüft haben, können Sie den Domänennamen zusammen mit dem Schemanamen verwenden, um einen eindeutigen Namen im folgenden Format zu definieren: {Domänenname}_{Schemaname}.If you already have a vanity .com,.net, .gov, .edu or a .org domain that you have verified with your tenant, you can use the domain name along with the schema name to define a unique name, in this format {domainName}_{schemaName}. Wenn Ihre Vanity-Domäne beispielsweise „contoso.com“ ist, können Sie eine ID mit dem Wert contoso_mySchema definieren.For example, if your vanity domain is contoso.com, you can define an id of, contoso_mySchema. Dies ist die bevorzugte Option.This is the preferred option.
  • Wenn Sie nicht über eine überprüfte Vanity-Domäne verfügen, können Sie die ID einfach auf einen Schemanamen festlegen (ohne Domänennamenpräfix), z. B. mySchema. Microsoft Graph weist eine Zeichenfolgen-ID anhand des angegebenen Namens im folgenden Format zu: ext{8-zufällige-alphanumerische-Zeichen}_{Schemaname}. Beispiel: extkvbmkofy_mySchema.If you don’t have a verified vanity domain, you can just set the id to a schema name (without a domain name prefix), for example, mySchema. Microsoft Graph will assign a string ID for you based on the supplied name, in this format: ext{8-random-alphanumeric-chars}_{schema-name}. For example, extkvbmkofy_mySchema.

Sie sehen diesen eindeutigen Namen in der ID, wo er als Name des komplexen Typs verwendet wird, der Ihre benutzerdefinierten Daten in der erweiterten Ressourceninstanz speichert.You will see this unique name in id used as the name of the complex type that will store your custom data on the extended resource instance.

Anders als bei offenen Erweiterungen handelt es sich bei der Verwaltung von Schemaerweiterungsdefinitionen (Auflisten, Erstellen, Abrufen, Aktualisieren und Löschen) und der Verwaltung ihrer Daten (Hinzufügen, Abrufen, Aktualisieren und Löschen) um unterschiedliche Sätze von API-Vorgängen.Unlike open extensions, managing schema extension definitions (list, create, get, update, and delete) and managing their data (add, get, update, and delete data) are separate sets of API operations.

Da Schemaerweiterungen als komplexe Typen in Instanzen der Zielressourcen zugänglich sind, können Sie wie folgt CRUD-Vorgänge auf die benutzerdefinierten Daten in einer Schemaerweiterung anwenden:Because schema extensions are accessible as complex types in instances of the targeted resources, you can do CRUD operations on the custom data in a schema extension in the following ways:

  • Sie können die POST-Methode der Ressource verwenden, um bei der Erstellung einer neuen Ressourceninstanz benutzerdefinierte Daten anzugeben.Use the resource POST method to specify custom data when creating a new resource instance. Beachten Sie, dass ein bekanntes Problem für die Ressourcen contact, event, message und post vorhanden ist, für das Sie eine Schemaerweiterung über einen PATCH-Vorgang erstellen müssen.Note that there is a known issue on the contact, event, message, and post resources that requires creating a schema extension using a PATCH operation.
  • Sie können die GET-Methode der Ressource verwenden, um die benutzerdefinierten Daten zu lesen.Use the resource GET method to read the custom data.
  • Sie können die PATCH-Methode der Ressource verwenden, um einer vorhandenen Ressourceninstanz benutzerdefinierte Daten hinzuzufügen oder benutzerdefinierte Daten aus einer vorhandenen Ressourceninstanz zu löschen.Use the resource PATCH method to add or update custom data in an existing resource instance.
  • Sie können die PATCH-Methode der Ressource verwenden, um den komplexen Typ auf „null“ festzulegen und so die benutzerdefinierten Daten in der Ressourceninstanz zu löschen.Use the resource PATCH method to set the complex type to null, to delete the custom data in the resource instance.

Beispiel für eine Schemaerweiterung: Hinzufügen von benutzerdefinierten Daten zu Gruppen mithilfe von SchemaerweiterungenSchema extension example: Add custom data to groups using schema extensions

Lebenszyklus von SchemaerweiterungenSchema extensions lifecycle

Wenn Ihre App eine Schemaerweiterungsdefinition erstellt, wird sie als Besitzer dieser Schemaerweiterung markiert.When your app creates a schema extension definition, the app is marked as the owner of that schema extension.

Die Besitzer-App kann anschließend einen PATCH-Vorgang auf die Erweiterungseigenschaft status anwenden, um die Erweiterung auf den jeweils gewünschten Lebenszyklusstatus zu setzen. Je nach dem aktuellen Status kann die Besitzer-App die Erweiterung möglicherweise aktualisieren oder löschen. Jegliche Aktualisierungen einer Schemaerweiterung sollten stets ausschließlich additiv und nicht destruktiv sein.The owner app can move the extension through different states of a lifecycle, using a PATCH operation on its status property. Depending on the current state, the owner app may be able to update or delete the extension. Any updates to a schema extension should always only be additive and non-breaking.

StatusState Verhalten des LebenszyklusstatusLifecycle state behavior
InDevelopmentInDevelopment
  • Anfänglicher Status nach der Erstellung. Die Besitzer-App entwickelt die Schemaerweiterung noch. Initial state after creation. The owner app is still developing the schema extension.
  • In diesem Status kann jede App Ressourceninstanzen mit dieser Schemadefinition erweitern, und das nur in dem Verzeichnis, in dem die Besitzer-App registriert ist.In this state, any app in the same directory where the owner app is registered can extend resource instances with this schema definition (as long as the app has permissions to that resource).
  • Nur die Besitzer-App kann die Erweiterungsdefinition mit additiven Änderungen aktualisieren oder sie löschen.Only the owner app can update the extension definition with additive changes or delete it.
  • Die Besitzer-App kann die Schemaerweiterung aus dem Status InDevelopment in den Status Available versetzen.The owner app can move the extension from InDevelopment to the Available state.
AvailableAvailable
  • Die Schemaerweiterung kann von allen Apps in jedem beliebigen Mandanten verwendet werden.The schema extension is available for use by all apps in any tenant.
  • Nachdem die Besitzer-App die Erweiterung auf Available festlegt, kann jede App benutzerdefinierte Daten zu Instanzen der in der Erweiterung angegebenen Ressourcentypen hinzufügen (vorausgesetzt, die App ist zum Zugriff auf die betreffende Ressource berechtigt).After the owner app sets the extension to Available, any app can simply add custom data to instances of those resource types specified in the extension (as long as the app has permissions to that resource). Die App kann benutzerdefinierte Daten bei der Erstellung einer neuen Instanz oder bei der Aktualisierung einer bereits vorhandenen Instanz zuweisen.The app can assign custom data when creating a new instance or updating an existing instance.
  • Nur die Besitzer-App kann die Erweiterungsdefinition mit additiven Änderungen aktualisieren.Only the owner app can update the extension definition with additive changes. Die Erweiterungsdefinition kann in diesem Status von keiner App gelöscht werden.No app can delete the extension definition in this state.
  • Die Besitzer-App kann die Schemaerweiterung aus dem Status Available in den Status Deprecated versetzen.The owner app can move the schema extension from Available to the Deprecated state.
DeprecatedDeprecated
  • Die Schemaerweiterungsdefinition kann nicht mehr gelesen und auch nicht mehr geändert werden.The schema extension definition can no longer be read or modified.
  • Die Erweiterung kann von keiner App angezeigt, aktualisiert, um neue Eigenschaften ergänzt oder gelöscht werden.No app can view, update, add new properties, or delete the extension.
  • Apps können vorhandene Eigenschaftswerte der Erweiterung jedoch weiterhin lesen, aktualisieren oder löschen.Apps can, however, still read, update, or delete existing extension property values.

Unterstützte Datentypen für EigenschaftenSupported property data types

Die folgenden Datentypen werden beim Definieren einer Eigenschaft in einer Schemaerweiterung unterstützt:The following data types are supported when defining a property in a schema extension:

EigenschaftentypProperty Type BemerkungenRemarks
BinärBinary Maximal 256 Bytes.256 bytes maximum.
Boolescher WertBoolean Nicht unterstützt für Nachrichten, Ereignisse und Beiträge.Not supported for messages, events and posts.
DateTimeDateTime Muss im ISO 8601-Format angegeben werden. Wird in UTC gespeichert.Must be specified in ISO 8601 format. Will be stored in UTC.
Ganze ZahlInteger 32-Bit-Wert. Nicht unterstützt für Nachrichten, Ereignisse und Beiträge.32-bit value. Not supported for messages, events and posts.
ZeichenfolgeString Maximal 256 Zeichen.256 characters maximum.

Hinweis: Eigenschaften mit mehreren Werten werden nicht unterstützt.Note: Multi-value properties are not supported.

Azure AD-VerzeichnisschemaerweiterungenAzure AD directory schema extensions

Azure AD unterstützt einen ähnlichen Erweiterungstyp namens Verzeichnisschemaerweiterung für einige directoryObject-Ressourcen. Zur Erstellung und Verwaltung der Definitionen von Verzeichnisschemaerweiterungen müssen Sie die Azure AD Graph-API verwenden. Das Hinzufügen, Abrufen, Aktualisieren und Löschen von Daten in den Eigenschaften dieser Erweiterungen ist jedoch auch über die Microsoft Graph-API möglich.Azure AD supports a similar type of extension, known as directory schema extensions, on a few directoryObject resources. Although you have to use the Azure AD Graph API to create and manage the definitions of directory schema extensions, you can use the Microsoft Graph API to add, get, update and delete data in the properties of these extensions.

BerechtigungenPermissions

Um Erweiterungsdaten aus einer Ressource auslesen oder in eine Ressource schreiben zu können, benötigen Sie dieselben Berechtigungen wie zum Lesen der Ressource und zum Schreiben in die Ressource.The same permissions that are required to read from or write to a specific resource are also required to read from or write to any extensions data on that resource. Damit eine App beispielsweise das Profil des angemeldeten Benutzers mit benutzerdefinierten App-Daten aktualisieren kann, muss sie die Berechtigung User.ReadWrite.All besitzen.For example, for an app to be able to update the signed-in user's profile with custom app data, the app must have been granted the User.ReadWrite.All permission.

Zusätzlich muss einer App die Berechtigung Directory.AccessAsUser.All gewährt werden, um Schemaerweiterungsdefinitionen zu erstellen und zu verwalten.Additionally, to create and manage schema extension definitions, an application must be granted the Directory.AccessAsUser.All permission.

Beschränkungen für DatenData limits

Beschränkungen für offene ErweiterungenOpen extension limits

Die folgenden Beschränkungen gelten für Verzeichnisressourcen (z. B. user, group, device):The following limits apply to directory resources (such as user, group, device):

  • Jede offene Erweiterung kann bis zu 2 KB Daten enthalten (einschließlich der Erweiterungsdefinition selbst).Each open extension can have up to 2 KB of data (including the extension definition itself).
  • Eine Anwendung kann bis zu zwei offene Erweiterungen pro Ressourceninstanz hinzufügen.An application can add up to two open extensions per resource instance.

Die folgenden Grenzwerte gelten für Outlook-Ressourcen (z.B. Nachricht, Ereignis und Kontakt):The following limits apply to Outlook resources (such as message, event, and contact):

Beschränkungen für SchemaerweiterungenSchema extension limits

Eine Anwendung kann nicht mehr als fünf Schemaerweiterungsdefinitionen erstellen.An application may create no more than five schema extension definitions.

Bekannte EinschränkungenKnown limitations

Bekannte Einschränkungen bei der Verwendung von Erweiterungen finden Sie im Abschnitt zu Erweiterungen im Artikel über bekannte Probleme.For known limitations using extensions, see the extensions section in the known issues article.

ErweiterungsbeispieleExtension examples

Siehe auchSee also