presence: setPresence
Namespace: microsoft.graph
Legen Sie den Status der Anwesenheitssitzung eines Benutzers als Anwendung fest.
Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.
Weltweiter Service | US Government L4 | US Government L5 (DOD) | China, betrieben von 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ❌ |
Anwesenheitssitzungen
Ein Benutzer kann mehrere Anwesenheitssitzungen haben, da sich der Benutzer auf mehreren Teams-Clients (Desktop, Mobilgeräte und Web) befinden kann. Jeder Teams-Client verfügt über eine unabhängige Anwesenheitssitzung, und die Anwesenheit des Benutzers ist ein aggregierter Zustand aller Hintersitzungen.
Ebenso kann eine Anwendung über eine eigene Anwesenheitssitzung für einen Benutzer verfügen und den Zustand aktualisieren.
Die folgende Rangfolge wird für die Aggregation von Sitzungszuständen verwendet:
- Vom Benutzer konfigurierte > App (vom Benutzer konfigurierter Zustand überschreibt andere)
- Unter app-konfiguriert: DoNotDisturb > Busy > Available > Away
Anmerkung: Wenn sich die Anwesenheit eines Benutzers in Microsoft Graph ändert, weil der Teams-Client den Abfragemodus verwendet, dauert es einige Minuten, bis die Anwesenheitsinformationen status aktualisiert wurden.
Timeout, Ablauf und Keep Alive
Bei einer Anwesenheitssitzung kann ein Timeoutauftreten und ablaufen, sodass die Anwendung diese API vor dem Timeout aufrufen muss, um den Zustand für die Sitzung beizubehalten. oder vor dem Ablauf, um die Sitzung aktiv zu halten.
Für eine Anwesenheitssitzung kann ein Timeout auftreten, wenn die Verfügbarkeit ist Available
und das Timeout 5 Minuten beträgt. Wenn ein Zeitüberschreitung auftritt, verblasst der Anwesenheitszustand stufenweise. Wenn eine Anwendung beispielsweise die Anwesenheitssitzung als Available/Available
festlegt, würde sich der Zustand in 5 Minuten mit dem ersten Timeout und dann Away/Away
in weitere 5 Minuten mit dem zweiten Timeout ändernAvailable/AvailableInactive
.
Verwenden Sie expirationDuration
, um den Ablauf einer Anwesenheitssitzung zu konfigurieren. Andernfalls beträgt der Standardablauf 5 Minuten. Gültige Werte reichen von 5 Minuten bis 4 Stunden, danach wird Offline
die Sitzung zu .
Berechtigungen
Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.
Berechtigungstyp | Berechtigungen mit den geringsten Berechtigungen | Berechtigungen mit höheren Berechtigungen |
---|---|---|
Delegiert (Geschäfts-, Schul- oder Unikonto) | Presence.ReadWrite | Nicht verfügbar. |
Delegiert (persönliches Microsoft-Konto) | Nicht unterstützt | Nicht unterstützt |
Application | Presence.ReadWrite.All | Nicht verfügbar. |
HTTP-Anforderung
POST /users/{userId}/presence/setPresence
Anforderungsheader
Name | Beschreibung |
---|---|
Authorization | Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung. |
Content-Type | application/json. Erforderlich. |
Anforderungstext
Geben Sie im Anforderungstext ein JSON-Objekt mit den folgenden Parametern an.
Parameter | Typ | Beschreibung |
---|---|---|
sessionId | string | Die ID der Anwesenheitssitzung der Anwendung. |
availability | string | Die Basis-Anwesenheitsinformationen. |
Aktivität | string | Die zusätzlichen Informationen zur Verfügbarkeit. |
expirationDuration | Dauer | Der Ablauf der App-Anwesenheitssitzung. Der Wert wird für die Dauer im ISO 8601-Format dargestellt.Wenn nicht angegeben, wird ein Standardablauf von 5 Minuten angewendet. Der gültige Dauerbereich liegt zwischen 5 und 240 Minuten (PT5M bis PT4H). |
Wichtig
Geben Sie die ID der Anwendung wie sessionId
in der Anforderung an.
Unterstützte Kombinationen von availability
und activity
sind:
availability | Aktivität | Beschreibung |
---|---|---|
Verfügbar | Verfügbar | Updates die Anwesenheitssitzung als Verfügbar aus. |
Gebucht | InACall | Updates die Anwesenheitssitzung als Beschäftigt, InACall aus. |
Gebucht | InAConferenceCall | Updates die Anwesenheitssitzung als Beschäftigt, InAConferenceCall. |
Weg | Weg | Updates die Anwesenheitssitzung als Abwesend aus. |
DoNotDisturb | Darbietend | Updates die Anwesenheitssitzung als DoNotDisturb, Präsentieren. |
Antwort
Wenn die Methode erfolgreich verläuft, wird der Antwortcode 200 OK
zurückgegeben.
Beispiele
Die folgende Anforderung zeigt die Anwendung mit der ID 22553876-f5ab-4529-bffb-cfe50aa89f87
, die ihre Anwesenheitssitzung für den Benutzer fa8bf3dc-eca7-46b7-bad1-db199b62afc3
festlegt.
Anforderung
POST https://graph.microsoft.com/v1.0/users/fa8bf3dc-eca7-46b7-bad1-db199b62afc3/presence/setPresence
Content-Type: application/json
{
"sessionId": "22553876-f5ab-4529-bffb-cfe50aa89f87",
"availability": "Available",
"activity": "Available",
"expirationDuration": "PT1H"
}
Antwort
HTTP/1.1 200 OK