Freigeben über


Hinzufügen von benutzerdefinierten Daten zu Gruppen mithilfe von Schemaerweiterungen

In diesem Tutorial erfahren Sie, wie Sie Schemaerweiterungen verwenden.

Stellen Sie sich vor, Sie sind Entwickler in einem Learning Management Software-Unternehmen namens Bellows College , das Schulungskurse und Materialien für Unternehmen erstellt. Sie verwenden die Zusammenarbeitserfahrung von Microsoft 365-Gruppen, um Kursinhalte bereitzustellen und Übungen zwischen Teilnehmern sowohl für Onlinekurse als auch für kursleitergeführte Kurse aufzuzeichnen. Sie möchten die microsoft 365-Gruppen, die für Schulungskurse verwendet werden, leicht als Schulungskurse identifizierbar machen, sodass andere Entwickler Ihre Gruppen entdecken und umfassende Erfahrungen auf Grundlage Ihrer Lernkurse erstellen können.

Für dieses Szenario wird in diesem Artikel Folgendes beschrieben:

  • Ermitteln Sie die verfügbaren Schemaerweiterungsdefinitionen, die Sie verwenden können.
  • Registrieren einer Schemaerweiterungsdefinition, die auf Gruppen für Schulungskurse abzielt
  • Erstellen Sie eine neue Gruppe mit benutzerdefinierten Daten basierend auf der schemaerweiterungsdefinition, die Sie registriert haben.
  • Hinzufügen, Aktualisieren oder Entfernen von benutzerdefinierten Daten in einer vorhandenen Gruppe basierend auf einer Schemaerweiterungsdefinition
  • Liest eine Gruppe und die Erweiterungsdaten.
  • Löschen Sie die Schemaerweiterungsdefinition und die Erweiterungsdaten.

Hinweis

Neben Gruppen werden auch Schemaerweiterungen unterstützt und können für andere Ressourcentypen verwaltet werden.

Voraussetzungen

Um die Schritte in diesem Artikel zu reproduzieren, benötigen Sie die folgenden Berechtigungen:

  • Melden Sie sich bei einem API-Client wie Graph-Explorer an.
  • Erteilen Sie der App die delegierten Berechtigungen Group.ReadWrite.All und Application.ReadWrite.All für den angemeldeten Benutzer.
  • Seien Sie der Besitzer einer Anwendung, der Sie den Besitz der Schemaerweiterungsdefinition in diesem Tutorial zuweisen. In diesem Tutorial heißt die Anwendung extensions-application und verfügt über appIdd1e6f196-fca3-48ad-8cd3-1a98e3bd46d2.

Schritt 1. Anzeigen verfügbarer Schemaerweiterungen

Als Entwickler sollten Sie zunächst alle vorhandenen Schemaerweiterungsdefinitionen wiederverwenden, wenn sie für den Zweck geeignet sind. Im folgenden Beispiel fragen Sie Schemaerweiterungen mit dem Namen (durch die ID) bellowscollege_coursesab. Angenommen, die Antwort zeigt, dass es keine Schemaerweiterungen gibt, die in Ihrem Mandanten benannt bellowscollege_courses sind.

Anforderung

GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'bellowscollege_courses'

Antwort

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET schemaExtensions?$select=description,owner",
    "value": []
}

Sie können auch nach der ID als Pfadparameter wie folgt abfragen: GET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses. Wenn keine Schemaerweiterungen vorhanden sind, die mit der ID übereinstimmen, lautet 404 Not Founddie Antwort .

Schritt 2. Registrieren einer Schemaerweiterungsdefinition

Sie möchten eine neue Erweiterungsdefinition für Schulungskurse für die Gruppenressource erstellen und registrieren. Geben Sie die folgenden Eigenschaften an:

  • id: Geben Sie eine Zeichenfolge für diese Eigenschaft auf eine von zwei Arten an:
    • Option 1: Verketten Sie einen überprüften Vanity-Domänennamen für Ihren Mandanten mit einem Namen für die Schemaerweiterung. Wenn die Domäne beispielsweise ist bellowscollege.comund der Name der Schemaerweiterung ist courses, können Sie die IDbellowscollege_courses verwenden.

    • Option 2: Eine alternative Möglichkeit besteht darin, nur einen Schemanamen anzugeben, z courses. B. , und Microsoft Graph die ID automatisch generieren zu lassen, indem dem angegebenen Namen eine zufällige alphanumerische Zeichenfolge vorangestellt wird.

      Diese ID wird zum Namen der Schemaerweiterungseigenschaft für eine Gruppe.

  • description
  • targetTypes: Geben Sie die Ressourcentypen an, auf die die Schemaerweiterung angewendet werden kann. In diesem Beispiel ist Groupder Ressourcentyp . Sie können weitere Ressourcentypen hinzufügen, indem Sie die Schemaerweiterungsdefinition später aktualisieren.
  • properties: Geben Sie die benutzerdefinierten Eigenschaften an, aus denen das Schema besteht. Geben Sie in diesem Beispiel die courseIdbenutzerdefinierten Eigenschaften , courseName und courseType sowie deren Typen an. Nach dem Erstellen der Schemaerweiterungsdefinition sind nur additive Änderungen zulässig.
  • owner: Geben Sie die Anwendung an, die besitzer der Schemaerweiterungsdefinition ist. Wenn Sie dieses Beispiel von einer App aus ausführen, der Sie nicht als Besitzer zugewiesen sind, geben Sie die appId der Anwendung an, die Ihnen in der Eigenschaft owner zugewiesen ist.

Anforderung

POST https://graph.microsoft.com/v1.0/schemaExtensions
Content-type: application/json

{
    "id": "bellowscollege_courses",
    "description": "Bellows College training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

Antwort

Das folgende Beispiel zeigt die Antwort.

In der Antwort lautet InDevelopmentder standard initiale Status der Schemaerweiterung . Während Sie die Erweiterung entwickeln, können Sie sie in diesem Status beibehalten, wobei nur die App, die sie erstellt hat, sie mit zusätzlichen Änderungen aktualisieren oder löschen kann. Wenn Sie bereit sind, die Erweiterung für die Verwendung durch andere Apps freizugeben, legen Sie den Status auf Verfügbar fest.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions/$entity",
    "id": "bellowscollege_courses",
    "description": "Bellows College training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

Schritt 3: Erweitern einer Gruppe mit benutzerdefinierten Daten

Sie können eine Gruppe entweder während der Gruppenerstellung oder durch Aktualisieren einer vorhandenen Gruppe mit benutzerdefinierten Daten erweitern.

Option 1: Erstellen einer neuen Gruppe mit erweiterten Daten

Die folgende Anforderung erstellt eine neue Gruppe und verwendet die bellowscollege_courses Schemaerweiterung, um die Gruppe mit benutzerdefinierten Daten zu erweitern. Wenn Sie über eine vorhandene Gruppe verfügen, können Sie sie auch mit benutzerdefinierten Daten erweitern, indem Sie die Gruppe mit den Erweiterungsdaten aktualisieren.

Die Antwort spiegelt keine Datenerweiterungen zurück. Sie müssen die Erweiterung mithilfe eines GET /group/{id} Vorgangs explizit $select anhand des Namens angeben.

Anforderung

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "displayName": "New Managers March 2024",
    "description": "New Managers training course for March 2024",
    "groupTypes": [
        "Unified"
    ],
    "mailEnabled": true,
    "mailNickname": "newMan202403",
    "securityEnabled": false,
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

Antwort

Das folgende Beispiel zeigt die Antwort. Die Antwort enthält die neue Erweiterung nicht. Sie müssen die Erweiterung mithilfe eines GET /group/{id} Vorgangs explizit $select anhand des Namens angeben.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "8fb45944-4085-449f-b95d-f7dd74a1b081",
    "createdDateTime": "2024-01-24T09:09:03Z",
    "description": "New Managers training course for March 2024",
    "displayName": "New Managers March 2024",
    "groupTypes": [
        "Unified"
    ],
    "mail": "newMan202403@bellowscollege.com",
    "mailEnabled": true,
    "mailNickname": "newMan202403"
}

Option 2: Aktualisieren einer vorhandenen Gruppe mit erweiterten Daten

Wenn Sie über eine vorhandene Gruppe verfügen, können Sie diese auch wie folgt mit benutzerdefinierten Daten erweitern. Die Anforderung gibt eine 204 No Content Antwort zurück.

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

Schritt 4. Aktualisieren von benutzerdefinierten Daten in einer Gruppe

Die folgende Anforderung aktualisiert die courseType-Eigenschaft in der bellowscollege_courses Erweiterung für die Gruppe in Hybrid. Obwohl Sie nur die courseType-Eigenschaft aktualisieren möchten, müssen Sie auch die anderen Eigenschaften und ihre vorhandenen Werte in den Anforderungstext einschließen. Andernfalls legt Microsoft Graph sie auf fest null und entfernt ihre Daten.

Die folgende Anforderung gibt eine 204 No Content Antwort zurück.

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Hybrid"
    }
}

Schritt 5. Abrufen einer Gruppe und ihrer Erweiterungsdaten

Um die benutzerdefinierten Daten in einer Gruppe abzurufen, verwenden Sie $select , um die Erweiterung anhand des Namens einzuschließen.

Neben der Filterung nach der ID der Schemaerweiterung können Sie auch nach den Erweiterungseigenschaftswerten filtern. Im folgenden Beispiel wird nach der Gruppe gesucht, die über die bellowscollege_courses Erweiterung mit einem courseId Eigenschaftswert verfügt, der mit übereinstimmt 123, und ruft die Erweiterungsdaten sowie die displayName-, id- und description-Eigenschaften der Gruppe ab.

Anforderung

GET https://graph.microsoft.com/v1.0/groups?$filter=bellowscollege_courses/courseId eq '123'&$select=displayName,id,description,bellowscollege_courses

Antwort

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(displayName,id,description,bellowscollege_courses)",
    "value": [
        {
            "displayName": "New Managers March 2024",
            "id": "8fb45944-4085-449f-b95d-f7dd74a1b081",
            "description": "New Managers training course for March 2024",
            "bellowscollege_courses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Hybrid",
                "courseName": "New Managers",
                "courseId": 123
            }
        }
    ]
}

Schritt 6: Löschen von Erweiterungsdaten und Schemaerweiterungsdefinition

Sie können eine Schemaerweiterungsdefinition löschen, wenn Sie sie nicht mehr benötigen. Wenn auf Ressourceninstanzen die Erweiterungseigenschaft angewendet wurde, werden durch das Löschen der Schemaerweiterungsdefinition die Erweiterungsdaten in den Ressourceninstanzen nicht gelöscht. Stattdessen sind die Erweiterungsdaten verfügbar, aber nicht mehr zugänglich. Sie können die Schemaerweiterungsdefinition mit der gleichen Konfiguration neu erstellen , wenn Sie die überprüfte Domäne für die Schemaerweiterungs-ID verwendet haben, um die Erweiterungsdaten löschen zu können.

Die folgende Anforderung löscht die bellowscollege_courses Schemaerweiterungseigenschaft und die zugehörigen Daten aus der Gruppe. Die Anforderung gibt eine 204 No Content Antwort zurück.

PATCH https://graph.microsoft.com/v1.0/groups/8fb45944-4085-449f-b95d-f7dd74a1b081

{
    "bellowscollege_courses": null
}

Die folgende Anforderung löscht die bellowscollege_courses Schemaerweiterungsdefinition. Die Anforderung gibt eine 204 No Content Antwort zurück.

DELETE https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses