subscription-Ressourcentyp
Namespace: microsoft.graph
Stellt ein Abonnement dar, mit dem eine Client-App Änderungsbenachrichtigungen zu Änderungen an Daten in Microsoft Graph empfangen kann.
Weitere Informationen zu Abonnements und Änderungsbenachrichtigungen, einschließlich Ressourcen, die Änderungsbenachrichtigungen unterstützen, finden Sie unter Einrichten von Benachrichtigungen für Änderungen an Ressourcendaten.
Methoden
| Methode | Rückgabetyp | Beschreibung |
|---|---|---|
| List | subscription | Listet aktive Abonnements auf. |
| Create | Abonnement | Abonniert eine Listener-Anwendung zum Empfangen von Änderungsbenachrichtigungen, wenn Microsoft Graph-Daten geändert werden. |
| Get | Abonnement | Dient zum Lesen der Eigenschaften und der Beziehungen des subscription-Objekts. |
| Update | Abonnement | Updates eine Abonnementablaufzeit für die Verlängerung und/oder aktualisiert die notificationUrl für die Übermittlung. |
| Löschen | Keine | Löscht ein subscription-Objekt. |
| Neu bevollmächtigen | Keine | Erneutes Authentifizieren eines Abonnements, wenn Sie eine Anforderung zur erneuten Autorisierung erhalten . |
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: updated-changeType. updated- und den deleted-changeType. Verwenden Sie updated , um Benachrichtigungen zu erhalten, wenn Benutzer oder Gruppen erstellt, aktualisiert oder vorläufig gelöscht werden. Verwenden Sie deleted , um Benachrichtigungen zu erhalten, wenn ein Benutzer oder eine Gruppe endgültig gelöscht wird. |
| clientState | Zeichenfolge | Optional. Gibt den Wert der clientState-Eigenschaft an, die in jeder Änderungsbenachrichtigung vom Dienst gesendet wird. Die Höchstlänge beträgt 128 Zeichen. Der Client kann prüfen, ob die Änderungsbenachrichtigung vom Dienst stammt, indem er den Wert der mit dem Abonnement gesendeten clientState-Eigenschaft mit dem Wert der mit jeder Änderungsbenachrichtigung empfangenen clientState-Eigenschaft vergleicht. |
| 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 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. |
| 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. Informationen zur maximal unterstützten 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 niedrigere Version als die derzeit empfohlene Version (TLS 1.2) unterstützt, ermöglicht die Angabe dieser Eigenschaft durch einen Satz Zeitleiste ihnen die vorübergehende Verwendung ihrer veralteten Tls-Version, bevor das Upgrade auf TLS 1.2 abgeschlossen wird. Bei diesen Abonnenten würden Abonnementvorgänge fehlschlagen, wenn diese Eigenschaft nicht durch eine Zeitachse festgelegt würde. Für Abonnenten, deren Benachrichtigungsendpunkt bereits TLS 1.2 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 | Erforderlich für Teams-Ressourcen, wenn der expirationDateTime Wert in 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. |
| notificationQueryOptions | Zeichenfolge | Optional. OData-Abfrageoptionen zum Angeben eines Werts für die Zielressource. Clients erhalten Benachrichtigungen, wenn die Ressource den Zustand erreicht, der mit den hier angegebenen Abfrageoptionen übereinstimmen soll. Mit dieser neuen Eigenschaft in der Nutzlast für die Abonnementerstellung zusammen mit allen vorhandenen Eigenschaften senden 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. Wird nur für den universellen Druckdienst unterstützt. Weitere Informationen finden Sie unter Abonnieren von Änderungsbenachrichtigungen von Clouddruck-APIs mithilfe von Microsoft Graph. |
| notificationUrl | Zeichenfolge | Erforderlich. Die URL des Endpunkts, der die Änderungsbenachrichtigungen empfängt. Diese URL muss das HTTPS-Protokoll verwenden. Alle Abfragezeichenfolgenparameter, die in der notificationUrl-Eigenschaft enthalten sind, sind 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. Der Wert ermöglicht es dem Client, die Authentizität der empfangenen Benachrichtigung zu überprüfen. |
| resource | Zeichenfolge | Erforderlich. Gibt die Ressource an, die auf Änderungen überwacht wird. Schließen Sie die Basis-URL (https://graph.microsoft.com/v1.0/) nicht ein. Hier finden Sie die möglichen Werte für den Ressourcenpfad für jede unterstützte Ressource. |
Gültigkeitsdauer von Abonnements
Abonnements haben eine eingeschränkte Gültigkeit. Apps müssen ihre Abonnements vor der Ablaufzeit verlängern. Andernfalls muss ein neues Abonnement erstellt werden. Apps können auch jederzeit gekündigt werden, um keine weiteren Änderungsbenachrichtigungen zu erhalten.
In der folgenden Tabelle sind die maximalen Ablaufzeiten für Abonnements pro Ressource in Microsoft Graph aufgeführt.
| Ressource | Maximal zulässige Ablaufzeit |
|---|---|
| Sicherheitswarnung | 43.200 Minuten (unter 30 Tagen) |
| 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) |
| Angebot "Teams-Schichten" ShiftRequest | 360 Minuten (6 Stunden) |
| Teams Schichten openShiftChangeRequest | 360 Minuten (6 Stunden) |
| Schichten in Teams | 360 Minuten (6 Stunden) |
| Teams Schichten swapShiftsChangeRequest | 360 Minuten (6 Stunden) |
| Teams verschiebt 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) |
| 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. |
| 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 |
|---|---|---|
| Warnung1 | Weniger als 3 Minuten | 5 Minuten |
| Zustimmungen | Weniger als 10 Sekunden | 40 Sekunden |
| Kalender | Weniger als 1 Minute | 3 Minuten |
| callRecord | Weniger als 15 Minuten | 60 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 | 5 Minuten |
| event | Unbekannt | Unbekannt |
| group | Unbekannt | Unbekannt |
| list | Weniger als 1 Minute | 5 Minuten |
| message | 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 erst, nachdem die Warnung erstellt wurde. Sie enthält nicht die Zeit, die eine Regel benötigt, um eine Warnung aus den Daten zu erstellen.
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",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String"
}