Feedback Bearbeiten

subscription-Ressourcentyp

  • Artikel
  • 5 Minuten Lesedauer

Namespace: microsoft.graph

Mit einem Abonnement kann eine Client-App Änderungsbenachrichtigungen zu Datenänderungen in Microsoft Graph erhalten. Für die folgenden Ressourcen sind derzeit Abonnements aktiviert:

  • Eine [Warnung][] aus der Microsoft Graph-Sicherheits-API.
  • Eine [Anrufaufnahme][], die nach einem Anruf oder einer Besprechung in Microsoft Teams erstellt wurde.
  • Ein Kanal in Microsoft Teams.
  • Ein Chat in Microsoft Teams.
  • Eine [Chatnachricht][], die über Teams oder Kanäle in Microsoft Teams versendet wurde.
  • Eine [Unterhaltung][] in einer Microsoft 365-Gruppe.
  • Ein conversationMember in einem Team oder Kanal in Microsoft Teams.
  • Inhalte in der Hierarchie eines driveItem-Stammordners in OneDrive for Business bzw. eines driveItem-Stammordners oder -Unterordners im persönlichen OneDrive eines Benutzers.
  • Eine [Gruppe][] im Azure Active Directory.
  • Eine [Liste][] auf einer SharePoint-[Website][].
  • Eine [Nachrichte][], [ein Ereignis][] oder [ein Kontakt][] in Outlook.
  • Ein Drucker (sobald ein Druckauftrag für den Drucker den Status „JobFetchable“ anzeigt, was bedeutet, dass gedruckt werden kann) und eine [Druckauftragsdefinition][] in Universal Print. Weitere Informationen finden Sie unter Abonnieren von Änderungsbenachrichtigungen von Clouddruck-APIs.
  • Ein Team in Microsoft Teams.
  • Eine TodoTask eines Benutzers in Microsoft To-Do.*
  • Ein [Benutzer][] im Azure Active Directory.

Informationen zu den möglichen Ressourcenpfadwerten für jede unterstützte Ressource finden Sie unter Verwenden der Microsoft Graph-API, um Änderungsbenachrichtigungen zu erhalten. Informationen zur Verwendung von Lebenszyklusbenachrichtigungen finden Sie unter Abonnements und Änderungsbenachrichtigungen reduzieren.

Methoden

Methode Rückgabetyp Beschreibung
Create subscription Abonnement Abonniert eine Listener-Anwendung zum Empfangen von Änderungsbenachrichtigungen, wenn Microsoft Graph-Daten geändert werden.
Abonnement aktualisieren Abonnement Erneuert ein Abonnement durch Aktualisierung der Ablaufzeit.
Abonnements auflisten subscription Listet aktive Abonnements auf.
Abonnement abrufen Abonnement Dient zum Lesen der Eigenschaften und der Beziehungen des subscription-Objekts.
Delete subscription Keine Löscht ein subscription-Objekt.

Eigenschaften

Eigenschaft Typ Beschreibung Unterstützte Ressourcen
applicationId Zeichenfolge Optional. Bezeichner der Anwendung, die zum Erstellen des Abonnements verwendet wird. Schreibgeschützt. Alle
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. Mehrere Werte können mit einer durch Komma getrennten Liste kombiniert 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.
    		•  Alle
    clientState Zeichenfolge Erforderlich. 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. Alle
    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 den Aufruf ausgeführt hat. Wenn die App Anwendungsberechtigungen verwendet hat, enthält dieses Feld die ID des Dienstprinzipals, der der App entspricht. Schreibgeschützt. Alle
    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 gesetzt ist. Alle
    encryptionCertificateId Zeichenfolge Optional. Ein benutzerdefinierter, von einer App bereitgestellter Bezeichner zur Identifizierung des Zertifikats, das zum Entschlüsseln von Ressourcendaten erforderlich ist. Alle
    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 ab der Erstellung des Abonnements sein, die je nach abonnierter Ressource variiert. Die maximal unterstützte Abonnementdauer entnehmen Sie der Tabelle unten. Alle
    id Zeichenfolge Optional. Eindeutige ID für das Abonnement. Schreibgeschützt. Alle
    includeResourceData Boolescher Wert Optional. Wenn auf true festgelegt, schließen Änderungsbenachrichtigungen Ressourcendaten mit ein (z. B. den Inhalt einer Chatnachricht). Alle
    latestSupportedTlsVersion String Optional. Gibt die aktuelle Version von Transport Layer Security (TLS) an, die von dem durch notificationUrl angegebenen Benachrichtigungsendpunkt unterstützt wird. Zulässige Werte: v1_0, v1_1, v1_2, v1_3.

    Abonnenten, deren Benachrichtigungsendpunkt eine niedrigere als die aktuell empfohlene Version (TLS 1.2) unterstützt, können durch Festlegen dieser Eigenschaft anhand einer definierten Zeitachse vorübergehend ihre veraltete Version von TLS verwenden, bevor sie das Upgrade auf TLS 1.2 ausführen. 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.    		 Alle
    lifecycleNotificationUrl Zeichenfolge Optional. Die URL des Endpunkts, der Lebenszyklus-Benachrichtigungen empfängt, einschließlich subscriptionRemoved- und missed-Benachrichtigungen. Diese URL muss das HTTPS-Protokoll verwenden. Alle
    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 Eigenschaft notificationQueryOptions angegeben ist. Wenn beispielsweise der Druckauftrag abgeschlossen ist oder wenn der isFetchable-Eigenschaftswert eines Druckauftrags true wird usw. Universelles Drucken
    notificationUrl Zeichenfolge Erforderlich. Die URL des Endpunkts, der die Änderungsbenachrichtigungen erhält. Diese URL muss das HTTPS-Protokoll verwenden. Alle
    notificationUrlAppId Zeichenfolge Optional. Die App-ID, die der Abonnementdienst zum Generieren des Überprüfungstokens verwenden kann. Dadurch kann der Client die Echtheit der empfangenen Benachrichtigung überprüfen. Alle
    resource Zeichenfolge Erforderlich. Gibt die Ressource an, deren Änderungen überwacht werden. Fügen Sie nicht die Basis-URL hinzu (https://graph.microsoft.com/v1.0/). Hier finden Sie die möglichen Werte für den Ressourcenpfad für jede unterstützte Ressource. Alle

    Maximale Abonnementdauer pro Ressourcentyp

    Ressource Maximal zulässige Ablaufzeit
    Sicherheitswarnung 43200 Minuten (unter 30 Tage)
    Teams callRecord 4230 Minuten (unter 3 Tage)
    Teams channel 60 Minuten (1 Stunde)
    Teams Chat 60 Minuten (1 Stunde)
    Teams chatMessage 60 Minuten (1 Stunde)
    Teams conversationMember 60 Minuten (1 Stunde)
    Teams team 60 Minuten (1 Stunde)
    Gruppen Unterhaltung 4230 Minuten (unter 3 Tage)
    OneDrive driveItem 42300 Minuten (unter 30 Tage)
    SharePoint- Liste 42300 Minuten (unter 30 Tage)
    Outlook- Nachrichten-, -Ereignis, Kontakt 4230 Minuten (unter 3 Tage)
    Benutzer, Gruppe, sonstige Verzeichnisressourcen 41760 Minuten (weniger als 29 Tage)
    presence 60 Minuten (1 Stunde)
    Drucken Drucker 4230 Minuten (weniger als 3 Tage)
    Drucken von printTaskDefinition 4230 Minuten (unter 3 Tage)
    todoTask 4230 Minuten (unter 3 Tage)

    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.

    Beziehungen

    Keine

    JSON-Darstellung

    Es folgt eine JSON-Darstellung der Ressource.

    {
  "@odata.type": "#microsoft.graph.subscription",
  "id": "String (identifier)",
  "resource": "String",
  "changeType": "String",
  "clientState": "String",
  "notificationUrl": "String",
  "expirationDateTime": "String (timestamp)",
  "applicationId": "String",
  "creatorId": "String",
  "includeResourceData": "Boolean",
  "lifecycleNotificationUrl": "String",
  "encryptionCertificate": "String",
  "encryptionCertificateId": "String",
  "latestSupportedTlsVersion": "String",
  "notificationQueryOptions": "String",
  "notificationUrlAppId": "String"
}