schemaExtension-Ressourcentyp (Schemaerweiterungen)

  • Artikel

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 Erstellen Sie eine Schemaerweiterungsdefinition und die zugehörige Schemaerweiterungseigenschaft.
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. Verwenden Sie diesen Vorgang, um die Beschreibung, status, Zieltypen zu aktualisieren oder der Schemaerweiterungsdefinition weitere Eigenschaften hinzuzufügen.
Delete Keine Dient zum Löschen einer schemaExtension-Definition.

Eigenschaften

Eigenschaft Typ Beschreibung
description String 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 lassen Sie Microsoft Graph diesen Schemanamen verwenden, um die ID-Zuweisung im folgenden Format abzuschließen: ext{8-random-alphanumeric-chars}_{schema-name}. Ein Beispiel wäre 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.

Unterstützt $filter (eq).
owner Zeichenfolge Die appId der Anwendung, die der Besitzer der Schemaerweiterung ist. Der Besitzer der Schemadefinition muss während der Erstellungs- und Aktualisierungsvorgänge explizit angegeben werden. Andernfalls wird er implizit und automatisch von Microsoft Entra ID wie folgt zugewiesen:
  • Beim delegierten Zugriff:
    • Der angemeldete Benutzer muss der Besitzer der App sein, die Microsoft Graph aufruft, um die Schemaerweiterungsdefinition zu erstellen.
    • Wenn der angemeldete Benutzer nicht der Besitzer der aufrufenden App ist, muss er explizit die Besitzereigenschaft angeben und ihr die appId einer App zuweisen, die er besitzt.
  • Nur App-Zugriff:
    • Die eigenschaft owner ist im Anforderungstext nicht erforderlich. Stattdessen wird der aufrufenden App der Besitz der Schemaerweiterung zugewiesen.

Wenn Sie also beispielsweise eine neue Schemaerweiterungsdefinition mithilfe von Graph Explorer erstellen, müssen Sie die Eigenschaft owner 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 mehrinstanzenfähigen Besitzer-App kann nur der instance der Besitzer-App, die sich in einem anderen Verzeichnis als dem Basisverzeichnis 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 Eigentümer-App kann die Erweiterungsdefinition löschen.
  • Die Besitzer-App kann die Erweiterung von InDevelopment in den Available Zustand verschieben.
Available
  • Die Schemaerweiterung kann von allen Apps in jedem beliebigen Mandanten verwendet werden.
  • Nachdem die Besitzer-App die Erweiterung auf Availablefestgelegt hat, kann jede App benutzerdefinierte Daten zu Instanzen dieser Ressourcentypen hinzufügen, die in der Erweiterung angegeben sind (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 von Available in den Deprecated Zustand verschieben.
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 jedoch weiterhin die vorhandenen Erweiterungseigenschaftswerte lesen, aktualisieren oder löschen.

Hinweis

Schemaerweiterungsdefinitionen (als Availablegekennzeichnet), 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

Die folgende JSON-Darstellung zeigt den Ressourcentyp.

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

Verwandte Inhalte