Freigeben über


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.

Informationen zu den Ressourcen, für die Sie Abonnements erstellen können, und die Einschränkungen für Abonnements finden Sie unter Einrichten von Benachrichtigungen für Änderungen an Ressourcendaten: Unterstützte Ressourcen.

Einige Ressourcen unterstützen umfangreiche Benachrichtigungen, d. h. Benachrichtigungen, die Ressourcendaten enthalten. Weitere Informationen zu diesen Ressourcen finden Sie unter Einrichten von Änderungsbenachrichtigungen, die Ressourcendaten enthalten: Unterstützte Ressourcen.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

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
callRecording
communications/onlineMeetings/getAllRecordings
Alle Aufzeichnungen in einer Organisation.
Nicht unterstützt Nicht unterstützt OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
Alle Aufzeichnungen für eine bestimmte Besprechung.
OnlineMeetingRecording.Read.All Nicht unterstützt OnlineMeetingRecording.Read.All
callRecording
users/{userId}/onlineMeetings/getAllRecordings
Eine Anrufaufzeichnung, die in einer Besprechung verfügbar wird, die von einem bestimmten Benutzer organisiert wird.
OnlineMeetingRecording.Read.All Nicht unterstützt OnlineMeetingRecording.Read.All
callTranscript
communications/onlineMeetings/getAllTranscripts
Alle Transkripte in einer Organisation.
Nicht unterstützt Nicht unterstützt OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
Alle Transkripte für eine bestimmte Besprechung.
OnlineMeetingTranscript.Read.All Nicht unterstützt OnlineMeetingTranscript.Read.All
callTranscript
users/{userId}/onlineMeetings/getAllTranscripts
Ein Anruftranskript, das in einer Besprechung verfügbar wird, die von einem bestimmten Benutzer organisiert wird.
OnlineMeetingTranscript.Read.All Nicht unterstützt OnlineMeetingTranscript.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
chat
/appCatalogs/teamsApps/{id}/installedToChats
Alle Chats in einer Organisation, in der eine bestimmte Teams-App installiert ist.
Nicht unterstützt Nicht unterstützt Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
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) Chat.Read, Chat.ReadWrite 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
chatMessage
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
Chatnachrichten für alle Chats in einer Organisation, in der eine bestimmte Teams-App installiert ist.
Nicht unterstützt Nicht unterstützt Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
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
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
Chatmitglieder für alle Chats in einer Organisation, in der eine bestimmte Teams-App installiert ist.
Nicht unterstützt Nicht unterstützt ChatMember.Read.WhereInstalled, ChatMember.ReadWrite.WhereInstalled, Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled
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
offerShiftRequest
(/teams/{id}/schedule/offerShiftRequests)
Änderungen an einer Angebotsverschiebungsanforderung in einem Team.
Schedule.Read.All, Schedule.ReadWrite.All Nicht unterstützt Schedule.Read.All, Schedule.ReadWrite.All
openShiftChangeRequest
(/teams/{id}/schedule/openShiftChangeRequests)
Änderungen an allen offenen Schichtanforderungen in einem Team.
Schedule.Read.All, Schedule.ReadWrite.All Nicht unterstützt Schedule.Read.All, Schedule.ReadWrite.All
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
shift
(/teams/{id}/schedule/shifts)
Änderungen an jeder Verschiebung in einem Team.
Schedule.Read.All, Schedule.ReadWrite.All Nicht unterstützt Schedule.Read.All, Schedule.ReadWrite.All
swapShiftsChangeRequest
(/teams/{id}/schedule/swapShiftsChangeRequests)
Änderungen an allen Verschiebungsanforderungen in einem Team.
Schedule.Read.All, Schedule.ReadWrite.All Nicht unterstützt Schedule.Read.All, Schedule.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
timeOffRequest
(/teams/{id}/schedule/timeOffRequests)
Änderungen an einer Anforderung für eine ausserplanende Zeit in einem Team.
Schedule.Read.All, Schedule.ReadWrite.All Nicht unterstützt Schedule.Read.All, Schedule.ReadWrite.All
todoTask Tasks.ReadWrite Tasks.ReadWrite Nicht unterstützt
user User.Read.All User.Read.All User.Read.All
virtualEventWebinar VirtualEvent.Read Nicht unterstützt VirtualEvent.Read.All

Wir empfehlen, die in der vorherigen Tabelle dokumentierten Berechtigungen zu verwenden. Aufgrund von Sicherheitseinschränkungen unterstützen Microsoft Graph-Abonnements keine Schreibzugriffsberechtigungen, wenn nur Lesezugriffsberechtigungen erforderlich sind.

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.

Sie müssen den Anforderungsheader Prefer: include-unknown-enum-members verwenden, um die folgenden Werte in chatMessagemessageTypeevolvable enum abzurufen: systemEventMessage for /teams/{id}/channels/{id}/messages und /chats/{id}/messages resource.

Hinweis

/teams/getAllMessages, /chats/getAllMessages, /me/chats/getAllMessages, /users/{id}/chats/getAllMessagesund /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages sind getaktete APIs. Zahlungsmodelle und Lizenzierungsanforderungen können gelten. /teams/getAllMessagesund /chats/getAllMessages unterstützen sowohl als auch model=A die model=B Zahlungsmodelle , /me/chats/getAllMessages/users/{id}/chats/getAllMessagesund /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages unterstützen nur model=B. Wenn Sie in Ihrer Abfrage kein Zahlungsmodell angeben, wird der Standardauswertungsmodus verwendet.

Hinweis

Um ein Zahlungsmodell für eine abonnierte Ressource einer Änderungsbenachrichtigung hinzuzufügen oder zu ändern, müssen Sie ein neues Abonnement für Änderungsbenachrichtigungen mit dem neuen Zahlungsmodell erstellen. Das Aktualisieren einer vorhandenen Änderungsbenachrichtigung funktioniert nicht.

conversationMember

conversationMember-Abonnements können so angegeben werden, dass sie Ressourcendaten enthalten. 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, /chats/getAllMembersund /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers sind getaktete APIs. Zahlungsmodelle und Lizenzierungsanforderungen können gelten. /teams/getAllMembersund /chats/getAllMembers unterstützen sowohl als model=B auch model=A zahlungsmodelle. /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers unterstützt nur model=B. Wenn Sie in Ihrer Abfrage kein Zahlungsmodell angeben, wird der Standardauswertungsmodus verwendet.

Hinweis

Um ein Zahlungsmodell für eine abonnierte Ressource einer Änderungsbenachrichtigung hinzuzufügen oder zu ändern, müssen Sie ein neues Abonnement für Änderungsbenachrichtigungen mit dem neuen Zahlungsmodell erstellen. Das Aktualisieren einer vorhandenen Änderungsbenachrichtigung funktioniert nicht.

Team, Kanal und Chat

Team-, Kanal- und Chatabonnements können so angegeben werden, dass sie Ressourcendaten enthalten. 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.

Sie können den Abfragezeichenfolgenparameter notifyOnUserSpecificProperties verwenden, wenn Sie Änderungen in einem bestimmten Chat oder auf Benutzerebene abonnieren. Wenn Sie den Abfragezeichenfolgenparameter notifyOnUserSpecificProperties während der Abonnementerstellung auf true festlegen, werden zwei Arten von Nutzlasten an den Abonnenten gesendet. Ein Typ enthält benutzerspezifische Eigenschaften, der andere wird ohne sie gesendet. Weitere Informationen finden Sie unter Abrufen von Änderungsbenachrichtigungen für Chats mit Microsoft Graph.

Hinweis

/appCatalogs/teamsApps/{id}/installedToChats verfügt über Lizenzierungs- und Zahlungsanforderungen, die speziell nur model=Bunterstützt werden. Wenn kein Modell angegeben ist, wird der Auswertungsmodus verwendet.

Hinweis

Um ein Zahlungsmodell für eine abonnierte Ressource einer Änderungsbenachrichtigung hinzuzufügen oder zu ändern, müssen Sie ein neues Abonnement für Änderungsbenachrichtigungen mit dem neuen Zahlungsmodell erstellen. Das Aktualisieren einer vorhandenen Änderungsbenachrichtigung funktioniert nicht.

Anforderungsbeispiel

Geben Sie den model Abfrageparameter in der Ressourcen- Eigenschaft im Anforderungstext an.

POST https://graph.microsoft.com/v1.0/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, z. B. einzelne Dateien.

OneDrive for Business und SharePoint unterstützen das Senden von Anwendungsbenachrichtigungen zu Sicherheitsereignissen, die auf einem DriveItem-Kontoauftreten. 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 die delegierte Berechtigung Calendars.Read nicht 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 deren Entsprechungen mit Lese-/Schreibzugriff), da sie das Abonnieren von Änderungsbenachrichtigungen für Elemente in freigegebenen oder delegierten Ordnern nicht unterstützen.

Anwesenheit

Bei Abonnements aufPrä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.

virtualEventWebinar

Abonnements für virtuelle Ereignisse unterstützen nur grundlegende Benachrichtigungen und sind auf einige Entitäten eines virtuellen Ereignisses beschränkt. Weitere Informationen zu den unterstützten Abonnementtypen finden Sie unter Abrufen von Änderungsbenachrichtigungen für Updates virtueller Microsoft Teams-Ereignisse.

HTTP-Anforderung

POST /subscriptions

Anforderungsheader

Name Typ Beschreibung
Authorization string Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.

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

Das folgende Beispiel zeigt eine Anforderung zum Senden einer Änderungsbenachrichtigung, wenn der Benutzer eine neue E-Mail erhält.

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 subscription-Objekts an. Die Felder clientState und latestSupportedTlsVersion sind optional.

Verhalten von doppelten Abonnements

Doppelte Abonnements sind nicht zulässig. Wenn eine Abonnementanforderung die gleichen Werte für changeType und die Ressource enthält, die ein vorhandenes Abonnement enthält, schlägt die Anforderung mit einem HTTP-Fehlercode 409 Conflictund der Fehlermeldung Subscription Id <> already exists for the requested combinationfehl.

Beispiele für Ressourcen

Im Folgenden sind gültige Werte für die Ressourceneigenschaft des Abonnements aufgeführt:

Ressourcentyp Beispiele
Anrufdatensätze communications/callRecords
callRecording communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings
callTranscript communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts
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}
E-Mail 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ür users/{id} anstelle von me verwendet werden, um einen bestimmten Benutzer anstelle des aktuellen Benutzers zu verwenden.

Antwort

Das folgende Beispiel zeigt die 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.