Feedback Bearbeiten

schemaExtension-Ressourcentyp (Schemaerweiterungen)

  • Artikel
  • 4 Minuten Lesedauer

Namespace: microsoft.graph

Wichtig

APIs unter der /beta Version in Microsoft Graph können geändert werden. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in Version 1.0 verfügbar ist, verwenden Sie die Versionsauswahl .

MitHilfe von Schemaerweiterungen können Sie ein Schema definieren, um stark typisierte benutzerdefinierte Daten zu einem Ressourcentyp zu erweitern und hinzuzufügen. Die benutzerdefinierten Daten werden als komplexer Typ für die erweiterte Ressource angezeigt. Schemaerweiterungen werden von den folgenden Ressourcentypen unterstützt:

Verwenden Sie diese Ressource und die zugehörigen Methoden, um die Schemaerweiterungsdefinitionen zu verwalten. Verwenden Sie zum Verwalten der Schemaerweiterungsdaten in der erweiterten Ressourceninstanz dieselbe REST-Anforderung, die Sie zum Verwalten der Ressourceninstanz verwenden. Im Beispiel für Schemaerweiterungen erfahren Sie, wie Sie benutzerdefinierte Daten zu Gruppen hinzufügen.

Weitere Informationen zur Erweiterbarkeit von Microsoft Graph, einschließlich Beschränkungen für Schemaerweiterungen, finden Sie unter Hinzufügen benutzerdefinierter Eigenschaften zu Ressourcen mithilfe von Erweiterungen.

Methoden

Methode Rückgabetyp Beschreibung
Create schemaExtension Dient zum Erstellen einer Schemaerweiterungsdefinition.
List schemaExtension Dient zum Auflisten der verfügbaren schemaExtension-Definitionen und ihrer Eigenschaften.
Get schemaExtension Dient zum Lesen der Eigenschaften einer bestimmten schemaExtension-Definition.
Update schemaExtension Dient zum Aktualisieren einer schemaExtension-Definition.
Delete Keine Dient zum Löschen einer schemaExtension-Definition.

Eigenschaften

Eigenschaft Typ Beschreibung
description Zeichenfolge Beschreibung für die Schemaerweiterung. Unterstützt $filter (eq).
id String Der eindeutige Bezeichner für die Schemaerweiterungsdefinition.
Sie können einen Wert mit einer von zwei Methoden zuweisen:
  • Verketten Sie den Namen einer Ihrer überprüften Domänen mit einem Namen für die Schemaerweiterung, um eine eindeutige Zeichenfolge in diesem Format zu bilden: {domainName}_{schemaName}. Beispiel: contoso_mySchema.
  • Geben Sie einen Schemanamen an, und verwenden Sie diesen Schemanamen in Microsoft Graph zum Vervollständigen der id-Zuweisung in diesem Format: ext{8-random-alphanumeric-chars}_{schema-name}. Zum Beispiel: extkvbmkofy_mySchema.
Diese Eigenschaft kann nach dem Erstellen nicht mehr geändert werden. Unterstützt $filter (eq).

Hinweis: Es wird empfohlen, dass Ihre ID mit einem alphabetischen Buchstaben zwischen A-Z beginnt, da die Abfragefunktionen für IDs die mit ganzen Zahlen beginnen, eingeschränkt sein können.
owner Zeichenfolge Die appId der Anwendung, die der Besitzer der Schemaerweiterung ist. Diese Eigenschaft kann bei der Erstellung bereitgestellt werden, um den Besitzer anzugeben. Wird Sie nicht bereitgestellt, wird die appId der aufrufenden Anwendung als Besitzer festgelegt. In beiden Fällen muss der angemeldete Benutzer angemeldet der Besitzer der Anwendung sein. Wenn Sie z. B. eine neue Definition für eine Schemaerweiterung mit dem Graph-Tester erstellen, müssen Sie die Besitzereigenschaft angeben. Wurde diese Eigenschaft einmal festgelegt, ist sie schreibgeschützt und kann nicht geändert werden. Unterstützt $filter (eq).
properties extensionSchemaProperty-Sammlung Die Sammlung von Eigenschaftennamen und Typen, die die Schemaerweiterungsdefinition bilden.
status String Der Lebenszyklusstatus der Schemaerweiterung. Mögliche Statuswerte sind: InDevelopment, Available und Deprecated. Wird bei der Erstellung automatisch auf InDevelopment festgelegt. Weitere Informationen zu möglichen Zustandsübergängen und -verhalten finden Sie unter Lebenszyklus von Schemaerweiterungen. Unterstützt $filter (eq).
targetTypes String-Sammlung Satz von Microsoft Graph-Typen (die Erweiterungen unterstützen können), auf die die Schemaerweiterung angewendet werden kann. Wählen Sie aus administrativeUnit, contact, device, event, group, message, organization, post, todoTask, todoTaskList oder user.

Lebenszyklus von Schemaerweiterungen

Wenn Ihre App eine Schemaerweiterungsdefinition erstellt, wird sie als Besitzer dieser Schemaerweiterung markiert.

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.

Status Verhalten des Lebenszyklusstatus
InDevelopment
  • Anfänglicher Status nach der Erstellung. Die Besitzer-App entwickelt die Schemaerweiterung noch.
  • In diesem Zustand kann jede App im selben Verzeichnis, in dem die Besitzer-App registriert ist, Ressourceninstanzen mit dieser Schemadefinition erweitern (wenn die App über Berechtigungen für diese Ressource verfügt).
  • Bei einer Besitzer-App mit mehreren Mandanten kann nur die Instanz der Besitzer-App, die sich in einem anderen Verzeichnis als dem Startverzeichnis befindet, Ressourceninstanzen mit dieser Schemadefinition erweitern (wenn die App über Berechtigungen für diese Ressource verfügt) oder die Erweiterungsdaten lesen.
  • Nur die Besitzer-App kann die Erweiterungsdefinition mit additiven Änderungen aktualisieren.
  • Nur die Besitzer-App kann die Erweiterungsdefinition löschen.
  • Die Besitzer-App kann die Schemaerweiterung aus dem Status InDevelopment in den Status Available versetzen.
Available
  • Die Schemaerweiterung kann von allen Apps in jedem beliebigen Mandanten verwendet werden.
  • Nachdem die Besitzer-App die Erweiterung auf "Verfügbar" festgelegt hat, kann jede App instanzen der in der Erweiterung angegebenen Ressourcentypen einfach benutzerdefinierte Daten hinzufügen (wenn die App über Berechtigungen für diese Ressource verfügt). Die App kann benutzerdefinierte Daten bei der Erstellung einer neuen Instanz oder bei der Aktualisierung einer bereits vorhandenen Instanz zuweisen.
  • Nur die Besitzer-App kann die Erweiterungsdefinition mit additiven Änderungen aktualisieren. Die Erweiterungsdefinition kann in diesem Status von keiner App gelöscht werden.
  • Die Besitzer-App kann die Schemaerweiterung aus dem Status Available in den Status Deprecated versetzen.
Deprecated
  • Die Schemaerweiterungsdefinition kann nicht mehr gelesen und auch nicht mehr geändert werden.
  • Die Erweiterung kann von keiner App angezeigt, aktualisiert, um neue Eigenschaften ergänzt oder gelöscht werden.
  • Apps können vorhandene Eigenschaftswerte der Erweiterung jedoch weiterhin lesen, aktualisieren oder löschen.

Hinweis: Schemaerweiterungsdefinitionen (gekennzeichnet als Available), die von anderen Entwicklern aus anderen Mandanten erstellt wurden, sind für alle Entwickler sichtbar (durch Auflisten aller Schemaerweiterungen). Dies unterscheidet sich von anderen APIs, die nur mandantenspezifische Daten zurückgeben. Andererseits sind Erweiterungsdaten, die auf Grundlage von Schemaerweiterungsdefinitionen erstellt wurden, mandantenspezifisch und können nur von Apps aufgerufen werden, denen diese Berechtigung explizit erteilt wurde.

JSON-Darstellung

Es folgt eine JSON-Darstellung der Ressource.

{
  "description": "String",
  "id": "String (identifier)",
  "owner": "String",
  "properties": [{"@odata.type": "microsoft.graph.extensionSchemaProperty"}],
  "status": "String",
  "targetTypes": ["String"]
}

Siehe auch