Freigeben über


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 subscription Updates eine Abonnementablaufzeit für die Verlängerung und/oder aktualisiert die notificationUrl für die Übermittlung.
Delete 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:
  • Änderungsbenachrichtigungen für Laufwerkstammelemente und Listen unterstützen nur den updated-changeType.
  • Änderungsbenachrichtigungen für Benutzer und Gruppen unterstützen den 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 4.230 Minuten (unter drei 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"
    }