Abonnement erstellenCreate subscription

• 14.01.2021
• 4 Minuten Lesedauer
• • d
  • o

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.

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

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"
}

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

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

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

const options = {
    authProvider,
};

const client = Client.init(options);

const subscription = {
   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"
};

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

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/subscriptions"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

MSGraphSubscription *subscription = [[MSGraphSubscription alloc] init];
[subscription setChangeType:@"created"];
[subscription setNotificationUrl:@"https://webhook.azurewebsites.net/api/send/myNotifyClient"];
[subscription setResource:@"me/mailFolders('Inbox')/messages"];
[subscription setExpirationDateTime: "2016-11-20T18:23:45.9356913Z"];
[subscription setClientState:@"secretClientValue"];
[subscription setLatestSupportedTlsVersion:@"v1_2"];

NSError *error;
NSData *subscriptionData = [subscription getSerializedDataWithError:&error];
[urlRequest setHTTPBody:subscriptionData];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

IGraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "created";
subscription.notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient";
subscription.resource = "me/mailFolders('Inbox')/messages";
subscription.expirationDateTime = CalendarSerializer.deserialize("2016-11-20T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";
subscription.latestSupportedTlsVersion = "v1_2";

graphClient.subscriptions()
    .buildRequest()
    .post(subscription);

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:

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.Note: Any path starting with me can also be used with users/{id} instead of me 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.