Abonnement erstellenCreate subscription
Namespace: microsoft.graphNamespace: microsoft.graph
Abonniert eine Listeneranwendung zum Empfangen von Änderungsbenachrichtigungen, wenn die angeforderte Art von Änderungen an der angegebenen Ressource in Microsoft Graph erfolgt.Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.
BerechtigungenPermissions
Zur Abonnementerstellung ist Lesezugriff auf die Ressource erforderlich.Creating a subscription requires read scope to the resource. Beispiel: Zum Erhalten von Änderungsbenachrichtigungen zu Nachrichten benötigt Ihre App die Mail.Read
-Berechtigung.For example, to get change notifications on messages, your app needs the Mail.Read
permission.
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.Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie unter Berechtigungen.To learn more, including how to choose permissions, see Permissions.
Unterstützte RessourceSupported resource | Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) | Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) | AnwendungApplication |
---|---|---|---|
callRecord (/communications/callRecords)callRecord (/communications/callRecords) | Nicht unterstütztNot supported | Nicht unterstütztNot supported | CallRecords.Read.AllCallRecords.Read.All |
ChatMessage (/Teams/{ID}/Channels/{ID}/Messages)chatMessage (/teams/{id}/channels/{id}/messages) | Nicht unterstütztNot supported | Nicht unterstütztNot supported | ChannelMessage.Read.Group*, ChannelMessage.Read.AllChannelMessage.Read.Group*, ChannelMessage.Read.All |
ChatMessage (/Teams/getAllMessages – alle Kanalnachrichten in der Organisation)chatMessage (/teams/getAllMessages -- all channel messages in organization) | Nicht unterstütztNot supported | Nicht unterstütztNot supported | ChannelMessage.Read.AllChannelMessage.Read.All |
ChatMessage (/Chats/{ID}/Messages)chatMessage (/chats/{id}/messages) | Nicht unterstütztNot supported | Nicht unterstütztNot supported | Chat.Read.AllChat.Read.All |
ChatMessage (/Chats/getAllMessages – Alle Chatnachrichten in der Organisation)chatMessage (/chats/getAllMessages -- all chat messages in organization) | Nicht unterstütztNot supported | Nicht unterstütztNot supported | Chat.Read.AllChat.Read.All |
Kontaktcontact | Contacts.ReadContacts.Read | Contacts.ReadContacts.Read | Contacts.ReadContacts.Read |
driveItem (persönliche OneDrive-Umgebung eines Benutzers)driveItem (user's personal OneDrive) | Nicht unterstütztNot supported | Files.ReadWriteFiles.ReadWrite | Nicht unterstütztNot supported |
driveItem (OneDrive for Business)driveItem (OneDrive for Business) | Files.ReadWrite.AllFiles.ReadWrite.All | Nicht unterstütztNot supported | Files.ReadWrite.AllFiles.ReadWrite.All |
eventevent | Calendars.ReadCalendars.Read | Calendars.ReadCalendars.Read | Calendars.ReadCalendars.Read |
groupgroup | Group.Read.AllGroup.Read.All | Nicht unterstütztNot supported | Group.Read.AllGroup.Read.All |
group conversationgroup conversation | Group.Read.AllGroup.Read.All | Nicht unterstütztNot supported | Nicht unterstütztNot supported |
listlist | Sites.ReadWrite.AllSites.ReadWrite.All | Nicht unterstütztNot supported | Sites.ReadWrite.AllSites.ReadWrite.All |
messagemessage | Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read | Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read | Mail.ReadBasic, Mail.ReadMail.ReadBasic, Mail.Read |
security alertsecurity alert | SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All | Nicht unterstütztNot supported | SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All |
useruser | User.Read.AllUser.Read.All | User.Read.AllUser.Read.All | User.Read.AllUser.Read.All |
Hinweis: Mit * markierte Berechtigungen verwenden ressourcenspezifische Zustimmung.Note: Permissions marked with * use resource-specific consent.
ChatMessagechatMessage
ChatMessage Abonnements mit Anwendungsberechtigungen enthalten Ressourcendaten und erfordern Verschlüsselung.chatMessage subscriptions with application permissions include resource data, and require encryption. Die Abonnementerstellung schlägt fehl, wenn encryptionCertificate- nicht angegeben wurde.Subscription creation will fail if encryptionCertificate is not specified. Bevor Sie ein ChatMessage -Abonnement erstellen, müssen Sie den Zugriff anfordern.Before creating a chatMessage subscription, you must request access. Ausführliche Informationen finden Sie unter Geschützte APIs in Microsoft Teams.For details, see Protected APIs in Microsoft Teams.
Hinweis:
/teams/getAllMessages
und/chats/getAllMessages
sind für Benutzer verfügbar, die über die erforderliche Lizenzen verfügen.Note:/teams/getAllMessages
and/chats/getAllMessages
are available to users that have the required licenses.
Hinweis:
/chats/getAllMessages
gibt nur Nachrichten aus Chats zurück, die sich im Besitz des Mandanten befinden.Note:/chats/getAllMessages
only returns messages from chats owned by the tenant. Wenn ein Chat-Thread von einem Benutzer außerhalb des Mandanten initiiert wird, befindet sich dieser Chat-Thread nicht im Besitz des Mandanten und erstellt keine Änderungsbenachrichtigungen.If a chat thread is initiated by a user outside the tenant, that chat thread is not owned by the tenant, and does not create change notifications.
driveItemdriveItem
Weitere Einschränkungen gelten für Abonnements von OneDrive-Elementen.Additional limitations apply for subscriptions on OneDrive items. Die Einschränkungen gelten für das Erstellen und Verwalten von Abonnements (das Erstellen, aktualisieren und löschen).The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.
Auf einem persönlichen OneDrive können Sie den Stammordner oder einen beliebigen Unterordner in diesem Laufwerk abonnieren.On a personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. Bei OneDrive for Business können Sie nur den Stammordner abonnieren.On OneDrive for Business, you can subscribe to only the root folder. Ä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.Change notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. Sie können keine drive- oder driveItem-Instanzen abonnieren, die keine Ordner sind, wie beispielsweise einzelne Dateien.You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.
Kontakt, Ereignis und Nachrichtcontact, event, and message
Für Abonnements von Outlook-Elementen gelten weitere Einschränkungen.Additional limitations apply for subscriptions on Outlook items. Die Einschränkungen gelten für das Erstellen und Verwalten von Abonnements (das Erstellen, aktualisieren und löschen).The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.
Die delegierte Berechtigung unterstützt das Abonnieren von Objekten in Ordnern, die sich nur im Postfach des angemeldeten Benutzers befinden.Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. Beispielsweise können Sie nicht die delegierte Berechtigung "Calendars.Read" verwenden, um Ereignisse im Postfach eines anderen Benutzers zu abonnieren.For example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.
So abonnieren Sie Änderungsbenachrichtigungen über Outlook-Kontakte, -Ereignisse oder -Nachrichten in freigegebenen oder delegierten Ordnern:To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:
- Verwenden Sie die entsprechende Anwendungsberechtigung, um Änderungen von Elementen in einem Ordner oder Postfach eines beliebigen Benutzers im Mandanten zu abonnieren.Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
- 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.Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.
HTTP-AnforderungHTTP request
POST /subscriptions
AnforderungsheaderRequest headers
NameName | TypType | BeschreibungDescription |
---|---|---|
AuthorizationAuthorization | stringstring | Bearer {token}. Erforderlich.Bearer {token}. Required. |
AntwortResponse
Wenn die Methode erfolgreich verläuft, werden der Antwortcode 201 Created
und ein subscription-Objekt im Antworttext zurückgegeben.If successful, this method returns 201 Created
response code and a subscription object in the response body.
Weitere Informationen dazu, wie Fehler zurückgegeben werden, finden Sie unter Fehlerantworten.For details about how errors are returned, see Error responses.
BeispielExample
AnforderungRequest
Hier sehen Sie ein Beispiel für die Anforderung zum Senden einer Änderungsbenachrichtigung, wenn der Benutzer eine neue E-Mail empfängt.Here is an example of the request to send a change notification when the user receives a new mail.
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.In the request body, supply a JSON representation of the subscription object.
Die Felder clientState
und latestSupportedTlsVersion
sind optional.The clientState
and latestSupportedTlsVersion
fields are optional.
Beispiele für RessourcenResources examples
Im Folgenden sind gültige Werte für die Ressourceneigenschaft des Abonnements aufgeführt:The following are valid values for the resource property of the subscription:
RessourcentypResource type | BeispieleExamples |
---|---|
AnrufdatensätzeCall records | communications/callRecords |
ChatnachrichtChat message | chats/{id}/messages , chats/getAllMessages , teams/{id}/channels/{id}/messages , teams/getAllMessages chats/{id}/messages , chats/getAllMessages , teams/{id}/channels/{id}/messages , teams/getAllMessages |
KontakteContacts | me/contacts |
UnterhaltungenConversations | groups('{id}')/conversations |
LaufwerkeDrives | me/drive/root |
EreignisseEvents | me/events |
GruppenGroups | groups |
ListeList | sites/{site-id}/lists/{list-id} |
E-MailMail | me/mailfolders('inbox')/messages , me/messages me/mailfolders('inbox')/messages , me/messages |
BenutzerUsers | users |
SicherheitswarnungSecurity alert | security/alerts?$filter=status eq 'New' |
Hinweis: alle Pfade, beginnend mit
me
, können auch fürusers/{id}
anstelle vonme
verwendet werden, um einen bestimmten Benutzer anstelle des aktuellen Benutzers zu verwenden.Note: Any path starting withme
can also be used withusers/{id}
instead ofme
to target a specific user instead of the current user.
AntwortResponse
Nachfolgend sehen Sie ein Beispiel der Antwort. Hinweis: Das hier gezeigte Antwortobjekt ist möglicherweise aus Platzgründen abgeschnitten. Von einem tatsächlichen Aufruf werden alle Eigenschaften zurückgegeben.Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.
HTTP/1.1 201 Created
Content-type: application/json
Content-length: 252
{
"@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"
}
Endpunktprüfung für BenachrichtigungenNotification endpoint validation
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.The subscription notification endpoint (specified in the notificationUrl
property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. Wenn die Validierung fehlschlägt, gibt die Anforderung zur Erstellung des Abonnements einen "400 Bad Request"-Fehler zurück.If validation fails, the request to create the subscription returns a 400 Bad Request error.