Feedback Bearbeiten

schemaExtension-Ressourcentyp (Schemaerweiterungen)

  • Artikel
  • 4 Minuten Lesedauer

Namespace: microsoft.graph

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

Diese Ressource und die zugehörigen Methoden verwenden, um die Schemaerweiterungsdefinitionen zu verwalten. Zum Verwalten der Schemaerweiterungsdaten auf der erweiterten Ressourceninstanz dieselbe REST-Anforderung verwenden, 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 von benutzerdefinierten 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 der Erstellung nicht geändert werden. Unterstützt $filter (eq). Hinweis: Wir empfehlen, dass Ihre ID mit einem Buchstaben zwischen A und Z beginnt, da die Abfragefunktionen für IDs, die mit Ganzzahlen beginnen, möglicherweise eingeschränkt sind.
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 den möglichen Zustandsübergängen und Verhaltensweisen 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 Berechtigungen für diese Ressource hat).
  • Bei einer mandantenfähigen Besitzer-App kann nur die Instanz der Besitzer-App, die sich in einem anderen Verzeichnis als dem Basisverzeichnis befindet, Ressourceninstanzen mit dieser Schemadefinition erweitern (wenn die App Berechtigungen für diese Ressource hat) oder die Erweiterungsdaten lesen.
  • Nur die Besitzer-App kann die Erweiterungsdefinition mit additiven Änderungen aktualisieren.
  • Nur die Eigentümer-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 Available festgelegt hat, kann jede App einfach benutzerdefinierte Daten zu Instanzen dieser Ressourcentypen hinzufügen, die in der Erweiterung angegeben sind (wenn die App Berechtigungen für diese Ressource hat). 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