Verwenden der Microsoft Graph-API für die Arbeit mit Viva Engage
Wichtig
Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.
Mit der Microsoft Graph-API können Apps Communitys in Viva Engage verwalten. Viva Engage ist ein social fabric für die Microsoft Viva-App-Suite, die Personen in der gesamten Organisation zum Teilen und Lernen verbindet. Es ist ein Ort, an dem Mitarbeiter sich mit Führungskräften, Kollegen und Communitys verbinden, ihr Wissen und ihre Ideen teilen und bei der Arbeit Zugehörigkeit finden können.
Wichtig
Die Viva Engage-API in Microsoft Graph wird nur für Viva Engage-Netzwerke im einheitlichen Modus unterstützt. Sie können diese API nicht zum Verwalten von Legacy- oder externen Viva Engage-Netzwerken verwenden.
Authorization
Zum Aufrufen der Viva Engage-API in Microsoft Graph muss Ihre App ein Zugriffstoken abrufen. Weitere Informationen zu Zugriffstoken finden Sie unter Abrufen von Zugriffstoken zum Aufrufen von Microsoft Graph. Ihre App benötigt auch die entsprechenden Berechtigungen. Weitere Informationen finden Sie in der Referenz zu den Microsoft Graph-Berechtigungen.
Allgemeine Anwendungsfälle
In der folgenden Tabelle sind häufige Anwendungsfälle für die Viva Engage-API aufgeführt.
| Anwendungsfall | API | Anmerkungen |
|---|---|---|
| Erstellen einer Community | POST /employeeExperience/communities | Bei erfolgreicher Ausführung gibt die Methode einen 202 Accepted Antwortcode zurück, der einen Link zu einem engagementAsyncOperation-Objekt enthält. |
| Abrufen des Communityerstellungsstatus | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | Bei erfolgreicher Ausführung gibt die Methode den 200 OK Antwortcode und ein engagementAsyncOperation-Objekt im Antworttext zurück. Überprüfen Sie regelmäßig den Status des Vorgangs, indem Sie eine GET-Anforderung an diesen Speicherort stellen. warten Sie >30 Sekunden zwischen den Überprüfungen. Wenn die Anforderung erfolgreich abgeschlossen wurde, wird der Status angezeigt succeeded , und resourceLocation verweist auf die erstellte oder geänderte Ressource. |
| Nach der Erstellung eine Community erhalten | GET /employeeExperience/communities/{communityId} | Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und ein Communityobjekt im Antworttext zurückgegeben. Das Communityobjekt verweist auf die zugeordnete Microsoft 365-Gruppen-ID , die Sie für die Communitymitgliedschafts- und Besitzverwaltung verwenden können. |
| Abrufen einer Liste von Communitys | GET /employeeExperience/communities | Wenn die Methode erfolgreich verläuft, werden der 200 OK Antwortcode und eine Sammlung von Viva Engage-Communityobjekten im Antworttext zurückgegeben. |
| Aktualisieren einer Community | PATCH /employeeExperience/communities/{communityId} | Bei erfolgreicher Ausführung aktualisiert diese Methode eine vorhandene Viva Engage-Community und gibt einen 204 No Content Antwortcode zurück. |
| Löschen einer Community | DELETE /employeeExperience/communities/{communityId} | Bei erfolgreicher Ausführung löscht diese Methode eine Viva Engage-Community zusammen mit allen zugehörigen Microsoft 365-Inhalten, einschließlich der verbundenen Microsoft 365-Gruppe, oneNote-Notizbuch und Planner-Plänen. Weitere Informationen finden Sie unter Was geschieht, wenn ich eine Viva Engage-Community lösche, die mit Microsoft 365-Gruppen verbunden ist. |
| Hinzufügen von Mitgliedern zu einer Community | POST /groups/{groupId}/members/$ref | Wenn einer Gruppe neue Mitglieder hinzugefügt werden, wird die zugeordnete Mitgliedschaft der Community automatisch aktualisiert. |
| Entfernen eines Mitglieds aus einer Community | DELETE /groups/{groupId}/members/{userId}/$ref | Wenn ein Mitglied aus einer Gruppe entfernt wird, wird die zugeordnete Mitgliedschaft der Community automatisch aktualisiert. |
| Hinzufügen eines Communityadministrators | POST /groups/{groupId}/owners/$ref | Wenn ein Benutzer als Gruppenbesitzer hinzugefügt wird, wird er automatisch zu einem Administrator der zugeordneten Community. |
| Entfernen eines Communityadministrators | DELETE /groups/{groupId}/owners/{userId}/$ref | Wenn ein Gruppenbesitzer entfernt wird, ist er nicht mehr Administrator für die zugeordnete Community. Sie können den letzten Besitzer (Benutzerobjekt ) einer Gruppe nicht entfernen. |
Communitys und Gruppen
Für Viva Engage-Netzwerke im einheitlichen Modus führt die Erstellung einer neuen Viva Engage-Community auch zur Erstellung einer verbundenen Microsoft 365-Gruppe sowie einer neuen SharePoint-Website, eines OneNote-Notizbuchs und eines Planner-Plans. Verwenden Sie die zugeordnete Gruppe, um Vorgänge in einer Community zu verwalten, z. B.:
- Hinzufügen oder Entfernen von Gruppenmitgliedern
- Verwalten des Gruppenbesitzes
- Löschen einer Gruppe
- Umbenennen einer Gruppe
- Aktualisieren der Gruppenbeschreibung
Weitere Informationen zur Beziehung zwischen Viva Engage-Communitys und Microsoft 365-Gruppen finden Sie unter Viva Engage und Microsoft 365-Gruppen.
Anmerkung: Sie können die API zum Erstellen einer Gruppe nicht verwenden, um eine Viva Engage-Community bereitzustellen.
API-Grenzwerte
Viva Engage-API-Aufrufe unterliegen einer Ratenbegrenzung, sodass 10 Anforderungen pro Benutzer und App innerhalb eines Zeitraums von 30 Sekunden zulässig sind. Wenn Sie das Ratenlimit überschreiten, geben alle nachfolgenden Anforderungen einen 429 Too Many Requests Antwortcode zurück.
Eine Anleitung zum Umgang mit der Drosselung in Microsoft Graph finden Sie unter Microsoft Graph-Drosselungsleitfaden.
Nächste Schritte
- Verwenden Sie die Microsoft Graph-API, um Communitys in Viva Engage zu verwalten.
- Testen Sie die Viva Engage-API im Graph-Explorer.