Abonnement erstellen
Namespace: microsoft.graph
Abonniert eine Listeneranwendung zum Empfangen von Änderungsbenachrichtigungen, wenn die angeforderte Art von Änderungen an der angegebenen Ressource in Microsoft Graph erfolgt.
Im Abschnitt Berechtigungen der Tabelle finden Sie die Liste der Ressourcen, die das Abonnieren von Änderungsbenachrichtigungen unterstützen.
Einige Ressourcen unterstützen die Option, verschlüsselte Ressourcendaten in Änderungsbenachrichtigungen einzuschließen. Zu diesen Ressourcen gehören chatMessage, Kontakt, Ereignis, Nachricht und Anwesenheit. Weitere Informationen finden Sie unter Einrichten von Änderungsbenachrichtigungen, die Ressourcendaten einschließen und Änderungsbenachrichtigungen für Outlook-Ressourcen in Microsoft Graph.
Berechtigungen
Zur Abonnementerstellung ist Lesezugriff auf die Ressource erforderlich. Beispiel: Zum Erhalten von Änderungsbenachrichtigungen zu Nachrichten benötigt Ihre App die Mail.Read-Berechtigung.
Abhängig von der Ressource und dem angeforderten Berechtigungstyp (delegiert oder Anwendung) ist die in der folgenden Tabelle angegebene Berechtigung die niedrigste Berechtigung, die zum Aufrufen dieser API erforderlich ist. Um mehr zu erfahren und vor der Wahl der Berechtigungen Vorsicht walten zu lassen, suchen Sie unter Berechtigungen nach den folgenden Berechtigungen.
| Unterstützte Ressource | Delegiert (Geschäfts-, Schul- oder Unikonto) | Delegiert (persönliches Microsoft-Konto) | Anwendung |
|---|---|---|---|
| callRecord (/communications/callRecords) | Nicht unterstützt | Nicht unterstützt | CallRecords.Read.All |
| Kanal (/teams/getAllChannels – alle Kanäle in einer Organisation) | Nicht unterstützt | Nicht unterstützt | Channel.ReadBasic.All, ChannelSettings.Read.All |
| Kanal (/teams/{id}/channels) | Channel.ReadBasic.All, ChannelSettings.Read.All | Nicht unterstützt | Channel.ReadBasic.All, ChannelSettings.Read.All |
| chat (/Chats – alle Chats in einer Organisation) | Nicht unterstützt | Nicht unterstützt | Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| chat (/chats/{id}) | Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Nicht unterstützt | ChatSettings.Read.Chat , ChatSettings.ReadWrite.Chat, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| ChatMessage (/Teams/{ID}/Channels/{ID}/Messages) | ChannelMessage.Read.All | Nicht unterstützt | ChannelMessage.Read.Group*, ChannelMessage.Read.All |
| ChatMessage (/Teams/getAllMessages – alle Kanalnachrichten in der Organisation) | Nicht unterstützt | Nicht unterstützt | ChannelMessage.Read.All |
| ChatMessage (/Chats/{id}/Messages) | Nicht unterstützt | Nicht unterstützt | Chat.Read.All |
| ChatMessage (/Chats/getAllMessages – Alle Chatnachrichten in der Organisation) | Nicht unterstützt | Nicht unterstützt | Chat.Read.All |
| chatMessage (/users/{id}/chats/getAllMessages –- Chatnachrichten für alle Chats, an denen ein bestimmter Benutzer beteiligt ist) | Chat.Read, Chat.ReadWrite | Nicht unterstützt | Chat.Read.All, Chat.ReadWrite.All |
| contact | Contacts.Read | Contacts.Read | Contacts.Read |
| conversationMember (/chats/getAllMembers) | Nicht unterstützt | Nicht unterstützt | ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| conversationMember (/chats/{id}/members) | ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite | Nicht unterstützt | ChatMember.Read.Chat , Chat.Manage.Chat, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All |
| conversationMember (/teams/{id}/members) | TeamMember.Read.All | Nicht unterstützt | TeamMember.Read.All |
| conversationMember (/teams/{id}/channels/getAllMembers) | Nicht unterstützt | Nicht unterstützt | ChannelMember.Read.All |
| driveItem (persönliche OneDrive-Umgebung eines Benutzers) | Nicht unterstützt | Files.ReadWrite | Nicht unterstützt |
| driveItem (OneDrive for Business) | Files.ReadWrite.All | Nicht unterstützt | Files.ReadWrite.All |
| event | Calendars.Read | Calendars.Read | Calendars.Read |
| group | Group.Read.All | Nicht unterstützt | Group.Read.All |
| group conversation | Group.Read.All | Nicht unterstützt | Nicht unterstützt |
| list | Sites.ReadWrite.All | Nicht unterstützt | Sites.ReadWrite.All |
| message | Mail.ReadBasic, Mail.Read | Mail.ReadBasic, Mail.Read | Mail.Read |
| presence | Presence.Read.All | Nicht unterstützt | Nicht unterstützt |
| Drucker | Nicht unterstützt | Nicht unterstützt | Printer.Read.All, Printer.ReadWrite.All |
| printTaskDefinition | Nicht unterstützt | Nicht unterstützt | PrintTaskDefinition.ReadWrite.All |
| security alert | SecurityEvents.ReadWrite.All | Nicht unterstützt | SecurityEvents.ReadWrite.All |
| Team (/teams – alle Teams in einer Organisation) | Nicht unterstützt | Nicht unterstützt | Team.ReadBasic.All, TeamSettings.Read.All |
| Team (/teams/{id}) | Team.ReadBasic.All, TeamSettings.Read.All | Nicht unterstützt | Team.ReadBasic.All, TeamSettings.Read.All |
| todoTask | Tasks.ReadWrite | Tasks.ReadWrite | Nicht unterstützt |
| user | User.Read.All | User.Read.All | User.Read.All |
Wir empfehlen, die in der vorherigen Tabelle dokumentierten Berechtigungen zu verwenden. Aufgrund von Sicherheitseinschränkungen werden Microsoft Graph-Abonnements keine Schreibzugriffsberechtigungen unterstützen, wenn nur Lesezugriffsberechtigungen benötigt werden.
Hinweis: Mit * markierte Berechtigungen verwenden ressourcenspezifische Zustimmung.
ChatMessage
chatMessage-Abonnements können angegeben werden, um Ressourcendaten einzuschließen. Wenn angegeben wird, dass Ressourcendaten eingeschlossen werden sollen (includeResourceData festgelegt auf true), ist eine Verschlüsselung erforderlich. Die Abonnementerstellung schlägt fehl, wenn für solche Abonnements kein encryptionCertificate angegeben ist. Bevor Sie ein chatMessage-Abonnement mit Anwendungsberechtigungen erstellen können, müssen Sie möglicherweise Zugriff anfordern. Detaillierte Informationen finden Sie unter Geschützte APIs in Microsoft Teams.
Sie müssen den Prefer: include-unknown-enum-members Anforderungsheader verwenden, um die folgenden Werte in chatMessage****messageTypeevolvable enumabzurufen: systemEventMessage für /teams/{id}/channels/{id}/messages und /chats/{id}/messages Ressource.
Hinweis
/teams/getAllMessages, /chats/getAllMessages, /me/chats/getAllMessages und /users/{id}/chats/getAllMessages haben Lizenz- und Zahlungsanforderungen.
/teams/getAllMessages und /chats/getAllMessages unterstützen sowohl model=A- als auch model=B-Abfrageparameter, /me/chats/getAllMessages und /users/{id}/chats/getAllMessages unterstützen nur model=B.
Wenn kein Modell angegeben ist, wird der Auswertungsmodus verwendet.
conversationMember
conversationMember-Abonnements können angegeben werden, um Ressourcendaten einzuschließen. Wenn angegeben wird, dass Ressourcendaten eingeschlossen werden sollen (includeResourceData festgelegt auf true), ist eine Verschlüsselung erforderlich. Die Abonnementerstellung schlägt fehl, wenn kein encryptionCertificate angegeben ist.
Hinweis
/teams/getAllMembers und /chats/getAllMembers haben Lizenz- und Zahlungsanforderungen.
/teams/getAllMembers und /chats/getAllMembers unterstützen sowohl model=A als auch model=B Abfrageparameter.
Wenn kein Modell angegeben ist, wird der Auswertungsmodus verwendet.
Team, Kanal und Chat
Team-, Kanal- und Chatabonnements können angegeben werden, um Ressourcendaten einzuschließen. Wenn angegeben wird, dass Ressourcendaten eingeschlossen werden sollen (includeResourceData festgelegt auf true), ist eine Verschlüsselung erforderlich. Die Abonnementerstellung schlägt fehl, wenn kein encryptionCertificate angegeben ist.
Anforderungsbeispiel
Geben Sie den model Abfrageparameter in der Ressourcen- Eigenschaft im Anforderungstext an.
POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "chats/getAllMessages?model=A",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
driveItem
Weitere Einschränkungen gelten für Abonnements von OneDrive-Elementen. Die Einschränkungen gelten für das Erstellen und Verwalten von Abonnements (das Erstellen, aktualisieren und löschen).
Auf einem persönlichen OneDrive können Sie den Stammordner oder einen beliebigen Unterordner in diesem Laufwerk abonnieren. Bei OneDrive for Business können Sie nur den Stammordner abonnieren. Änderungsbenachrichtigungen werden für die angeforderten Arten von Änderungen am abonnierten Ordner bzw. an einer Datei, einem Ordner oder anderen driveItem-Instanzen in seiner Hierarchie gesendet. Sie können keine drive- oder driveItem-Instanzen abonnieren, die keine Ordner sind, wie beispielsweise einzelne Dateien.
OneDrive for Business und SharePoint unterstützen das Senden von Anwendungsbenachrichtigungen zu Sicherheitsereignissen, die auf einem DriveItem-Konto auftreten. Wenn Sie diese Ereignisse abonnieren möchten, fügen Sie Ihrer Anforderung prefer:includesecuritywebhooks Kopfzeile hinzu, um ein Abonnement zu erstellen. Nachdem das Abonnement erstellt wurde, erhalten Sie Benachrichtigungen, wenn sich die Berechtigungen für ein Element ändern. Diese Kopfzeile gilt für SharePoint und OneDrive for Business, aber nicht für OneDrive-Konten von Verbrauchern.
Kontakt, Ereignis und Nachricht
Sie können Änderungen an der Outlook-Ressource Kontakt, Ereignis oder Nachricht abonnieren.
Das Erstellen und Verwalten (Abrufen, Aktualisieren und Löschen) eines Abonnements erfordert einen Lesebereich für die Ressource. Beispiel: Zum Erhalten von Änderungsbenachrichtigungen zu Nachrichten benötigt Ihre App die Mail.Read-Berechtigung. Outlook-Änderungsbenachrichtigungen unterstützen delegierte und Anwendungsberechtigungsbereiche. Beachten Sie die folgenden Einschränkungen:
Die delegierte Berechtigung unterstützt das Abonnieren von Objekten in Ordnern, die sich nur im Postfach des angemeldeten Benutzers befinden. Beispielsweise können Sie nicht die delegierte Berechtigung "Calendars.Read" verwenden, um Ereignisse im Postfach eines anderen Benutzers zu abonnieren.
So abonnieren Sie Änderungsbenachrichtigungen über Outlook-Kontakte, -Ereignisse oder -Nachrichten in freigegebenen oder delegierten Ordnern:
- Verwenden Sie die entsprechende Anwendungsberechtigung, um Änderungen von Elementen in einem Ordner oder Postfach eines beliebigen Benutzers im Mandanten zu abonnieren.
- Verwenden Sie nicht die Outlook-Freigabeberechtigungen (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared und ihre read/write-Entsprechungen), da sie das Abonnieren von Änderungsbenachrichtigungen für Elemente in freigegebenen oder delegierten Ordnern nicht unterstützen.
Anwesenheit
Bei Abonnements auf Präsenz müssen alle Ressourcendaten, die in einer Änderungsmeldung enthalten sind, verschlüsselt werden. Geben Sie immer den Parameter encryptionCertificate an, wenn Sie ein Abonnement erstellen, um Fehler zu vermeiden. Weitere Informationen zum Einrichten von Änderungsbenachrichtigungen, die Ressourcendaten enthalten, finden Sie hier.
HTTP-Anforderung
POST /subscriptions
Anforderungsheader
| Name | Typ | Beschreibung |
|---|---|---|
| Authorization | string | Bearer {token}. Erforderlich. |
Anforderungstext
Geben Sie im Anforderungstext eine JSON-Darstellung des Abonnement-Objekts an.
Antwort
Wenn die Methode erfolgreich verläuft, werden der Antwortcode 201 Created und ein subscription-Objekt im Antworttext zurückgegeben.
Weitere Informationen dazu, wie Fehler zurückgegeben werden, finden Sie unter Fehlerantworten.
Beispiel
Anforderung
Hier sehen Sie ein Beispiel für die Anforderung zum Senden einer Änderungsbenachrichtigung, wenn der Benutzer eine neue E-Mail empfängt.
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "me/mailFolders('Inbox')/messages",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
Geben Sie im Anforderungstext eine JSON-Darstellung des Abonnement-Objekts an. Die Felder clientState und latestSupportedTlsVersion sind optional.
Beispiele für Ressourcen
Im Folgenden sind gültige Werte für die Ressourceneigenschaft des Abonnements aufgeführt:
| Ressourcentyp | Beispiele |
|---|---|
| Anrufdatensätze | communications/callRecords |
| Chatnachricht | chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages |
| Kontakte | me/contacts |
| Unterhaltungen | groups('{id}')/conversations |
| Laufwerke | me/drive/root |
| Ereignisse | me/events |
| Gruppen | groups |
| Liste | sites/{site-id}/lists/{list-id} |
me/mailfolders('inbox')/messages, me/messages |
|
| Anwesenheit | /communications/presences/{id} (einzelner Benutzer), /communications/presences?$filter=id in ('{id}','{id}',…) (mehrere Benutzer) |
| Drucker | print/printers/{id}/jobs |
| PrintTaskDefinition | print/taskDefinitions/{id}/tasks |
| Sicherheitswarnung | security/alerts?$filter=status eq 'New' |
| todoTask | /me/todo/lists/{todoTaskListId}/tasks |
| Benutzer | users |
Hinweis: alle Pfade, beginnend mit
me, können auch fürusers/{id}anstelle vonmeverwendet werden, um einen bestimmten Benutzer anstelle des aktuellen Benutzers zu verwenden.
Antwort
Nachfolgend sehen Sie ein Beispiel der Antwort.
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
"id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
"resource": "me/mailFolders('Inbox')/messages",
"applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
"changeType": "created",
"clientState": "secretClientValue",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"expirationDateTime": "2016-11-20T18:23:45.9356913Z",
"creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
"latestSupportedTlsVersion": "v1_2",
"notificationContentType": "application/json"
}
Endpunktprüfung für Benachrichtigungen
Der Endpunkt der Abonnementbenachrichtigung (angegeben in der Eigenschaft notificationUrl) muss in der Lage sein, auf eine Validierungsanforderung zu reagieren, wie unter Einrichten von Benachrichtigungen für Änderungen an Benutzerdaten beschrieben. Wenn die Validierung fehlschlägt, gibt die Anforderung zur Erstellung des Abonnements einen "400 Bad Request"-Fehler zurück.
Feedback
Feedback senden und anzeigen für