Abonnement erstellenCreate subscription

• 07.05.2019
• 3 Minuten Lesedauer
• Beitragende
  • 
  • 

Abonniert eine Listener-Anwendung, um Benachrichtigungen zu erhalten, wenn die angeforderte Art von Änderungen an der angegebenen Ressource in Microsoft Graph auftritt.Subscribes a listener application to receive 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: um Benachrichtigungen zu Nachrichten zu erhalten, benötigt Ihre App die Mail.Read-Berechtigung.For example, to get 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.

Hinweis: Es gibt zusätzliche Einschränkungen für Abonnements für OneDrive- und Outlook-Elemente.Note: There are additional limitations for subscriptions on OneDrive and Outlook items. Die Einschränkungen gelten sowohl für die Erstellung als auch für die Verwaltung von Abonnements (Abrufen, Aktualisieren und Löschen von Abonnements).The limitations apply to creating as well as managing subscriptions (getting, updating, and deleting subscriptions).

• Auf dem persönlichen OneDrive können Sie den Stammordner oder einen beliebigen Unterordner auf diesem Laufwerk abonnieren.On 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. Benachrichtigungen 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.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.

• In Outlook unterstützt die delegierte Berechtigung das Abonnieren von Elementen ausschließlich in Ordnern, die sich im Postfach des angemeldeten Benutzers befinden.In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. Das bedeutet, dass Sie beispielsweise nicht die delegierte Berechtigung "Calendars.Read" verwenden können, um Ereignisse im Postfach eines anderen Benutzers zu abonnieren.That means, 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

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.

BeispielExample

AnforderungRequest

Hier sehen Sie ein Beispiel für die Anforderung zum Senden einer Benachrichtigung, wenn der Benutzer eine neue E-Mail empfängt.Here is an example of the request to send a notification when the user receives a new mail.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "created,updated",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue"
}

Geben Sie im Anforderungstext eine JSON-Darstellung des subscription-Objekts an.In the request body, supply a JSON representation of the subscription object. Das clientState-Feld ist optional.The clientState field is 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:

ReaktionResponse

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/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created,updated",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437"
}

SDK-BeispielcodeSDK sample code

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var subscription = new Subscription
{
    ChangeType = "created,updated",
    NotificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    Resource = "me/mailFolders('Inbox')/messages",
    ExpirationDateTime = "2016-11-20T18:23:45.9356913Z",
    ClientState = "secretClientValue"
};

await graphClient.Subscriptions
    .Request()
    .AddAsync(subscription);

const options = {
    authProvider,
};

const client = Client.init(options);

const subscription = {
   changeType: "created,updated",
   notificationUrl: "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   resource: "me/mailFolders('Inbox')/messages",
   expirationDateTime:"2016-11-20T18:23:45.9356913Z",
   clientState: "secretClientValue"
};

let res = await client.api('/subscriptions')
    .post({subscription : subscription});

In der SDK-Dokumentation finden Sie Informationen zum Hinzufügen des SDK zu Ihrem Projekt und zum Erstellen einer authProvider -Instanz.Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

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.