Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Namespace: microsoft.graph
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.
Achtung
Vorhandene Apps, die dieses Feature mit baseTask oder baseTaskList verwenden, sollten aktualisiert werden, da der auf diesen Ressourcen basierende To-Do-API-Satz ab dem 31. Mai 2022 veraltet ist. Dieser API-Satz wird ab dem 31. August 2022 keine Daten mehr zurückgeben. Bitte verwenden Sie den API-Satz, der auf todoTask basiert.
Stellt ein Abonnement dar, das es einer Client-App ermöglicht, Änderungsbenachrichtigungen zu Änderungen an Daten in Microsoft Graph zu empfangen.
Weitere Informationen zu Abonnements und Änderungsbenachrichtigungen, einschließlich Ressourcen, die Änderungsbenachrichtigungen unterstützen, finden Sie unter Einrichten von Benachrichtigungen für Änderungen in Ressourcendaten.
Methoden
| Methode | Rückgabetyp | Beschreibung |
|---|---|---|
| List | Abonnement | Aktive Abonnements auflisten. |
| Create | Abonnement | Abonnieren Sie eine Listeneranwendung, um Änderungsbenachrichtigungen zu erhalten, wenn sich Microsoft Graph-Daten ändern. Wenn eine Anwendung erstellt und erfolgreich bewertet wurde, sendet Microsoft Graph der App jedes Mal, wenn eine Änderung an der abonnierten Ressource erfolgt, mindestens ein changeNotificationCollection-Objekt . |
| Get | Abonnement | Lesen Sie Eigenschaften und Beziehungen des Abonnementobjekts. |
| Update | Abonnement | Verlängern Sie ein Abonnement, indem Sie die Ablaufzeit aktualisieren. |
| Löschen | Keine | Löschen Sie ein Abonnementobjekt. |
| Neu bevollmächtigen | Keine | Autorisieren Sie ein Abonnement erneut, wenn Sie eine reauthorizationRequired-Herausforderung erhalten. |
| Get VAPID | Zeichenfolge | Rufen Sie den öffentlichen Schlüssel Voluntary Application Server Identification (VAPID) ab, der zum Erstellen des Abonnements nach RFC8292 verwendet werden soll. |
Eigenschaften
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
| applicationId | Zeichenfolge | Optional. Bezeichner der Anwendung, die zum Erstellen des Abonnements verwendet wird. Schreibgeschützt. |
| changeType | Zeichenfolge | Erforderlich. Gibt den Typ der Änderung in der abonnierten Ressource an, die eine Änderungsbenachrichtigung auslöst. Unterstützte Werte sind: created, updated, deleted. Es können mehrere Werte mithilfe einer durch Trennzeichen getrennten Liste zusammen verwendet werden. Hinweis:
|
| clientState | Zeichenfolge | Optional. Gibt den Wert der clientState-Eigenschaft an, die vom Dienst in jeder Änderungsbenachrichtigung gesendet wird. Die maximale Länge ist 255 Zeichen. Der Client kann überprüfen, ob die Änderungsbenachrichtigung vom Dienst stammt, indem er den Wert der clientState-Eigenschaft , die mit dem Abonnement gesendet wird, mit dem Wert der clientState-Eigenschaft vergleicht, die mit jeder Änderungsbenachrichtigung empfangen wird. |
| creatorId | Zeichenfolge | Optional. Bezeichner des Benutzers oder Dienstprinzipals, der das Abonnement erstellt hat. Wenn die App delegierte Berechtigungen zum Erstellen des Abonnements verwendet hat, enthält dieses Feld die ID des angemeldeten Benutzers, für den die App sie aufgerufen hat. Wenn die App Anwendungsberechtigungen verwendet hat, enthält dieses Feld die ID des Dienstprinzipals, der der App entspricht. Schreibgeschützt. |
| encryptionCertificate | Zeichenfolge | Optional. Eine Base64-codierte Darstellung eines Zertifikats mit einem öffentlichen Schlüssel zum Verschlüsseln von Ressourcendaten in Änderungsbenachrichtigungen. Optional, aber erforderlich, wenn includeResourceData auf true festgelegt ist. |
| encryptionCertificateId | Zeichenfolge | Optional. Eine benutzerdefinierte App-bereitgestellte ID zur Identifizierung des Zertifikats, das zum Entschlüsseln von Ressourcendaten erforderlich ist. Erforderlich, wenn includeResourceData ist true. |
| expirationDateTime | DateTimeOffset | Erforderlich. Gibt Datum und Uhrzeit für das Ablaufen des Webhook-Abonnements an. Die Zeit wird in UTC angegeben und kann eine Dauer aus der Erstellung des Abonnements sein, die von der abonnierten Ressource abweicht. Jeder Wert unter 45 Minuten nach dem Zeitpunkt der Anforderung wird automatisch auf 45 Minuten nach dem Zeitpunkt der Anforderung festgelegt. Informationen über die maximal unterstützte Abonnementdauer finden Sie unter Abonnementlebensdauer. |
| id | Zeichenfolge | Optional. Eindeutige ID für das Abonnement. Schreibgeschützt. |
| includeResourceData | Boolescher Wert | Optional. Wenn auf truefestgelegt wird, ändern Sie Benachrichtigungen, Ressourcendaten miteinschließen (z. b. den Inhalt einer Chatnachricht). |
| latestSupportedTlsVersion | Zeichenfolge | Optional. Gibt die aktuelle Version von Transport Layer Security (TLS) an, die von dem durch notificationUrl angegebenen Benachrichtigungsendpunkt unterstützt wird. Mögliche Werte sind: v1_0, v1_1, v1_2, v1_3.
Für Abonnenten, deren Benachrichtigungsendpunkt eine Version unterstützt, die niedriger ist als die derzeit empfohlene Version (TLS 1.2), ermöglicht die Angabe dieser Eigenschaft durch eine festgelegte Zeitleiste, vorübergehend ihre veraltete Version von TLS zu verwenden, bevor sie ihr Upgrade auf TLS 1.2 abschließen. Bei diesen Abonnenten würden Abonnementvorgänge fehlschlagen, wenn diese Eigenschaft nicht durch eine Zeitachse festgelegt würde. Für Abonnenten, deren Benachrichtigungsendpunkt TLS 1.2 bereits unterstützt, ist das Festlegen dieser Eigenschaft optional. In diesen Fällen ist die Eigenschaft von Microsoft Graph standardmäßig auf v1_2 festgelegt. |
| lifecycleNotificationUrl | Zeichenfolge | Für Teams-Ressourcen erforderlich, wenn der expirationDateTime Wert vor mehr als einer Stunde liegt, andernfalls optional. Die URL des Endpunkts, der Lebenszyklusbenachrichtigungen empfängt, einschließlich subscriptionRemoved, reauthorizationRequiredund missed Benachrichtigungen. Diese URL muss das HTTPS-Protokoll verwenden. Weitere Informationen finden Sie unter Reduzieren fehlender Abonnements und Änderungsbenachrichtigungen. |
| notificationContentType | Zeichenfolge | Optional. Gewünschter Inhaltstyp für Microsoft Graph-Änderungsbenachrichtigungen für unterstützte Ressourcentypen. Der Standardinhaltstyp ist application/json. |
| notificationQueryOptions | Zeichenfolge | Optional. OData-Abfrageoptionen zum Angeben des Werts für die Zielressource. Clients erhalten Benachrichtigungen, wenn die Ressource den Status erreicht, der den hier bereitgestellten Abfrageoptionen entspricht. Mit dieser neuen Eigenschaft in der Abonnementerstellungsnutzlast zusammen mit allen vorhandenen Eigenschaften liefern Webhooks Benachrichtigungen, wenn eine Ressource den gewünschten Zustand erreicht, der in der notificationQueryOptions-Eigenschaft erwähnt wird. Wenn beispielsweise der Druckauftrag abgeschlossen ist oder wenn der isFetchable-Eigenschaftswert eines Druckauftrags true wird usw. Nur für den universellen Druckdienst unterstützt. Weitere Informationen finden Sie unter Abonnieren von Änderungsbenachrichtigungen von Clouddruck-APIs mit Microsoft Graph. |
| notificationUrl | Zeichenfolge | Erforderlich. Die URL des Endpunkts, der die Änderungsbenachrichtigungen empfängt. Diese URL muss das HTTPS-Protokoll verwenden. Jeder Abfragezeichenfolgenparameter, der in der notificationUrl-Eigenschaft enthalten ist, ist in der HTTP POST-Anforderung enthalten, wenn Microsoft Graph die Änderungsbenachrichtigungen sendet. |
| notificationUrlAppId | Zeichenfolge | Optional. Die App-ID, die der Abonnementdienst zum Generieren des Überprüfungstokens verwenden kann. Anhand des Werts kann der Client die Echtheit der empfangenen Benachrichtigung überprüfen. |
| resource | Zeichenfolge | Erforderlich. Gibt die Ressource an, die auf Änderungen überwacht wird. Schließen Sie nicht die Basis-URL (https://graph.microsoft.com/beta/) ein. Hier finden Sie die möglichen Werte für den Ressourcenpfad für jede unterstützte Ressource. |
| vapidPublicKey | Zeichenfolge | Optional. Der öffentliche VAPID-Schlüssel des Anwendungsservers, base64url-codiert (nicht komprimierter P-256-Punkt, 65 Byte Vorcodierung). Abgerufen durch Aufrufen der getVapidPublicKey-Funktion für die Abonnementsammlung. Der Browser übergibt diesen Wert, PushManager.subscribe({ applicationServerKey }) um das Pushabonnement an diese Serveridentität zu binden. Erforderlich, *.push.apple.comwenn notificationUrl auf einen bekannten Webpushdienstursprung abzielt (z. B. , fcm.googleapis.com; updates.push.services.mozilla.com); rejected with if provided on 400 Bad Request a standard webhook subscription. Weitere Informationen finden Sie unter RFC 8292. |
| webPushEncryptionP256dhPublicKey | Zeichenfolge | Optional. Der öffentliche ECDH-Schlüssel des Teilnehmers, base64url-codiert (P-256 unkomprimierter Punkt, 65 Byte Vorcodierung). Abgerufen vom Browser über PushSubscription.getKey('p256dh'). Wird als öffentlicher Peerschlüssel während der ECDH-Schlüsselvereinbarung verwendet, um den Inhaltsverschlüsselungsschlüssel pro Nachricht für die RFC 8291-Nutzlastverschlüsselung abzuleiten. Erforderlich, wenn notificationUrl auf einen bekannten Webpushdienstursprung abzielt; Abgelehnt mit 400 Bad Request , wenn in einem Standard-Webhookabonnement angegeben. Weitere Informationen finden Sie unter RFC 8291 Abschnitt 3. |
| webPushEncryptionSecret | Zeichenfolge | Optional. Das Authentifizierungsgeheimnis des Abonnenten, Base64URL-codiert (16 Byte Vorcodierung). Abgerufen vom Browser über PushSubscription.getKey('auth'). Wird als HMAC-SHA-256-Salt für den HKDF-Kombinationsschritt verwendet, der Schlüsselmaterial für die RFC 8291-Nutzlastverschlüsselung ableitet. Schreibgeschützt: Dieser Wert wird in GET-Antworten nie zurückgegeben (zurückgegeben als null). Als Geheimnis behandeln. Erforderlich, wenn notificationUrl auf einen bekannten Webpushdienstursprung abzielt; Abgelehnt mit 400 Bad Request , wenn in einem Standard-Webhookabonnement angegeben. Weitere Informationen finden Sie unter RFC 8291 Abschnitt 3. |
Gültigkeitsdauer von Abonnements
Abonnements haben eine eingeschränkte Gültigkeit. Apps müssen ihre Abonnements vor dem Ablaufzeitpunkt erneuern. Andernfalls müssen sie ein neues Abonnement erstellen. Apps können auch jederzeit gekündigt werden, um keine weiteren Änderungsbenachrichtigungen zu erhalten.
Darüber hinaus wird jede Anforderung mit expirationDateTime, die auf weniger als 45 Minuten nach dem Zeitpunkt der Anforderung festgelegt ist, automatisch auf 45 Minuten nach dem Anforderungszeitpunkt festgelegt.
Die folgende Tabelle zeigt die maximalen Ablaufzeiten für Abonnements pro Ressource in Microsoft Graph.
| Ressource | Maximal zulässige Ablaufzeit |
|---|---|
| Copilot aiInteraction | 4.320 Minuten (drei Tage) |
| Sicherheitswarnung | 43.200 Minuten (unter 30 Tagen) |
| Microsoft Teams-Genehmigungen | 43.200 Minuten (unter 30 Tagen) |
| Teams callRecord | 4.230 Minuten (unter drei Tagen) |
| Teams-AnrufAufzeichnung | 4.320 Minuten (drei Tage) |
| Teams callTranscript | 4.320 Minuten (drei Tage) |
| Teams channel | 4.320 Minuten (drei Tage) |
| Teams Chat | 4.320 Minuten (drei Tage) |
| Teams chatMessage | 4.320 Minuten (drei Tage) |
| Teams conversationMember | 4.320 Minuten (drei Tage) |
| Teams onlineMeeting | 4.320 Minuten (drei Tage) |
| Teams team | 4.320 Minuten (drei Tage) |
| Teams teamsAppInstallation | 4.320 Minuten (3 Tage) |
| Teams Schichten AngebotShiftRequest | 360 Minuten (6 Stunden) |
| Teams Schichten openShiftChangeRequest | 360 Minuten (6 Stunden) |
| Microsoft Teams-Schichten schichtet | 360 Minuten (6 Stunden) |
| Teams Schichten swapShiftsChangeRequest | 360 Minuten (6 Stunden) |
| Teams Schichten timeOffRequest | 360 Minuten (6 Stunden) |
| Gruppen Unterhaltung | 4.230 Minuten (unter drei Tagen) |
| OneDrive driveItem | 42.300 Minuten (unter 30 Tagen) |
| SharePoint-Liste | 42.300 Minuten (unter 30 Tagen) |
| Outlook- Nachrichten-, -Ereignis, Kontakt | 10.080 Minuten (unter sieben Tagen) Bei Abonnements mit Ressourcendaten (Abonnements mit umfangreichen Benachrichtigungen) beträgt die Abonnementlebensdauer 1440 Minuten (unter einem Tag). |
| Benutzer, Gruppe, sonstige Verzeichnisressourcen | 41.760 Minuten (unter 29 Tagen) |
| onlineMeeting | 4.230 Minuten (unter drei Tagen) |
| presence | 60 Minuten (1 Stunde) |
| Drucken Drucker | 4.230 Minuten (unter drei Tagen) |
| Drucken von printTaskDefinition | 4.230 Minuten (unter drei Tagen) |
| todoTask | 4.230 Minuten (unter drei Tagen) Webhooks für diese Ressource sind nur im globalen Endpunkt und nicht in den nationalen Clouds verfügbar. |
| Microsoft Entra Health Monitoring-Warnung | 42.300 Minuten (unter 30 Tagen) |
| baseTask (veraltet) | 4.230 Minuten (unter drei Tagen) |
Hinweis: Vorhandene Anwendungen und neue Anwendungen sollten den unterstützten Wert nicht überschreiten. In Zukunft schlagen alle Anforderungen zur Erstellung oder Verlängerung eines Abonnements, die über den Maximalwert hinausgehen, fehl.
Wartezeit
Die folgende Tabelle enthält eine Liste der voraussichtlichen Wartezeiten zwischen dem Eintreten eines Ereignisses im Dienst und der Übermittlung der Änderungsbenachrichtigung.
| Ressource | Durchschnittliche Wartezeit | Maximale Wartezeit |
|---|---|---|
| aiInteraction | Weniger als 10 Sekunden | 60 Minuten |
| WARNUNG1 | Weniger als 3 Minuten | 5 Minuten |
| Genehmigungen | Weniger als 10 Sekunden | 40 Sekunden |
| Kalender | Weniger als 1 Minute | 3 Minuten |
| callRecord2 | Weniger als 30 Minuten | 150 Minuten |
| callRecording | Weniger als 10 Sekunden | 60 Minuten |
| callTranscript | Weniger als 10 Sekunden | 60 Minuten |
| channel | Weniger als 10 Sekunden | 60 Minuten |
| chat | Weniger als 10 Sekunden | 60 Minuten |
| chatMessage | Weniger als 10 Sekunden | 1 Minute |
| contact | Weniger als 1 Minute | 3 Minuten |
| conversation | Unbekannt | Unbekannt |
| conversationMember | Weniger als 10 Sekunden | 60 Minuten |
| driveItem | Weniger als 1 Minute | 6 Stunden |
| event | Unbekannt | Unbekannt |
| group | Unbekannt | Unbekannt |
| Warnung zur Systemüberwachung | Unbekannt | Unbekannt |
| list | Weniger als 1 Minute | 6 Stunden |
| Nachricht | Weniger als 1 Minute | 3 Minuten |
| offerShiftRequest | Weniger als 1 Minute | 60 Minuten |
| onlineMeeting | Weniger als 10 Sekunden | 1 Minute |
| openShiftChangeRequest | Weniger als 1 Minute | 60 Minuten |
| presence | Weniger als 10 Sekunden | 1 Minute |
| Drucker | Weniger als 1 Minute | 5 Minuten |
| printTaskDefinition | Weniger als 1 Minute | 5 Minuten |
| shift | Weniger als 1 Minute | 60 Minuten |
| swapShiftsChangeRequest | Weniger als 1 Minute | 60 Minuten |
| team | Weniger als 10 Sekunden | 60 Minuten |
| teamsAppInstallation | Weniger als 10 Sekunden | 60 Minuten |
| timeOffRequest | Weniger als 1 Minute | 60 Minuten |
| todoTask | Weniger als 2 Minuten | 15 Minuten |
| user | Unbekannt | Unbekannt |
1 Die für die Warnungsressource bereitgestellte Latenz gilt nur, nachdem die Warnung erstellt wurde. Die Zeit, die eine Regel benötigt, um eine Warnung aus den Daten zu erstellen, ist nicht enthalten. 2 Die für die callRecord-Ressource bereitgestellte Latenz gilt nur für die erste Version eines Anrufdatensatzes. Nachfolgende Versionen eines Anrufdatensatzes können über die angegebenen Wartezeiten hinaus aktualisiert werden.
Beziehungen
Keine.
JSON-Darstellung
Die folgende JSON-Darstellung veranschaulicht den Ressourcentyp.
{
"@odata.type": "#microsoft.graph.subscription",
"applicationId": "String",
"changeType": "String",
"clientState": "String",
"creatorId": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"expirationDateTime": "String (timestamp)",
"id": "String (identifier)",
"includeResourceData": "Boolean",
"latestSupportedTlsVersion": "String",
"lifecycleNotificationUrl": "String",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String",
"vapidPublicKey": "String",
"webPushEncryptionP256dhPublicKey": "String",
"webPushEncryptionSecret": "String"
}