Créer un abonnementCreate subscription

S’abonne à une application auditeur pour recevoir des notifications lorsque le type de modifications demandé se produit à la ressource spécifiée dans Microsoft Graph.Subscribes a listener application to receive notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

AutorisationsPermissions

La création d’un abonnement nécessite un accès en lecture à la ressource.Creating a subscription requires read scope to the resource. Par exemple, pour recevoir des messages de notification, votre application a besoin de l’autorisation Mail.Read.For example, to get notifications on messages, your app needs the Mail.Read permission.

En fonction du type de ressource et d’autorisation(délégué ou application) demandé, l’autorisation spécifiée dans le tableau suivant est la moins requise privilégiée pour appeler cette API.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. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.To learn more, including how to choose permissions, see Permissions.

Ressource prise en chargeSupported resource Déléguée (compte professionnel ou scolaire)Delegated (work or school account) Déléguée (compte Microsoft personnel)Delegated (personal Microsoft account) ApplicationApplication
contactcontact Contacts.ReadContacts.Read Contacts.ReadContacts.Read Contacts.ReadContacts.Read
driveItem(OneDrive personnel de l’utilisateur)driveItem (user's personal OneDrive) Non pris en chargeNot supported Files.ReadWriteFiles.ReadWrite Non pris en chargeNot supported
driveItem(Microsoft OneDrive Entreprise)driveItem (OneDrive for Business) Files.ReadWrite.AllFiles.ReadWrite.All Non pris en chargeNot supported Files.ReadWrite.AllFiles.ReadWrite.All
eventevent Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read
groupegroup Group.Read.AllGroup.Read.All Non pris en chargeNot supported Group.Read.AllGroup.Read.All
Conversation de groupegroup conversation Group.Read.AllGroup.Read.All Non pris en chargeNot supported Non pris en chargeNot supported
messagemessage Mail.ReadMail.Read Mail.ReadMail.Read Mail.ReadMail.Read
alerte de sécuritésecurity alert SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All Non pris en chargeNot supported SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All
utilisateuruser User.Read.AllUser.Read.All User.Read.AllUser.Read.All User.Read.AllUser.Read.All

Remarque : il existe des restrictions supplémentaires pour les abonnements sur les éléments Outlook et OneDrive.Note: There are additional limitations for subscriptions on OneDrive and Outlook items. Les limitations s’appliquent à la création, ainsi que de la gestion des abonnements (prise, la mise à jour et suppression d’abonnements).The limitations apply to creating as well as managing subscriptions (getting, updating, and deleting subscriptions).

  • Dans OneDrive personnel, vous pouvez vous abonner au dossier racine ou à n’importe quel sous-dossier dans ce lecteur.On personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. Sur OneDrive pour les entreprises, vous pouvez vous abonner uniquement au dossier racine.On OneDrive for Business, you can subscribe to only the root folder. Les notifications sont envoyées pour les types de modifications sur le dossier concerné, ou n’importe quel fichier, dossier ou autres instances demandéesdriveItemdans sa hiérarchie.Notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. Vous ne pouvez pas vous abonner au lecteur ou aux instancesdriveItemqui ne sont pas des dossiers, tels que les fichiers individuels.You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

  • Dans Outlook, l’autorisation de délégué prend en charge le fait de s’abonner à des éléments dans vos dossiers dans une seule boîte aux lettres de l’utilisateur de connectés.In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. Cela signifie que, par exemple, vous ne pouvez pas utiliser l’autorisation de délégué Calendars.Read pour s’abonner à des événements de boîte aux lettres d’un autre utilisateur.That means, for example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

  • Pour vous abonner afin de modifier les notifications de contacts, d’événements ou de messages dans Outlook dans dossiers_partagés ou délégués_:To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

    • Permet de s’abonner aux modifications d’éléments dans un dossier ou une boîte aux lettres de l’autorisation d’application correspondante n’importe quel utilisateur dans le client.Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
    • N’utilisez pas les autorisations Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared et leurs équivalents en lecture/écriture), de partage à ceux inscrits non partagés de prise en charge de l’abonnement pour modifier les notifications sur les éléments dans ou dossiers délégués.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.

Requête HTTPHTTP request

POST /subscriptions

En-têtes de demandeRequest headers

NomName TypeType DescriptionDescription
AutorisationAuthorization stringstring Porteur {token}. Obligatoire.Bearer {token}. Required.

RéponseResponse

En cas de réussite, cette méthode renvoie le code de réponse 201 Created et un objet abonnement dans le corps de la réponse.If successful, this method returns 201 Created response code and a subscription object in the response body.

ExempleExample

DemandeRequest

Voici un exemple de demande pour envoyer une notification lorsque l’utilisateur reçoit un nouveau message.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"
}

Dans le corps de la demande, fournissez une représentation JSON de l’objet abonnement.In the request body, supply a JSON representation of the subscription object. Ce champclientStateest facultatif.The clientState field is optional.

Exemples de ressourcesResources examples

Les valeurs valides pour la propriété de ressource de l’abonnement sont les suivantes :The following are valid values for the resource property of the subscription:

Type de ressourceResource type 範例Examples
Application de messagerieMail me/mailfolders('inbox')/messagesme/mailfolders('inbox')/messages
me/messagesme/messages
ContactsContacts me/contactsme/contacts
CalendriersCalendars me/eventsme/events
UtilisateursUsers utilisateursusers
GroupesGroups groupesgroups
ConversationsConversations groups('{id}')/conversationsgroups('{id}')/conversations
LecteursDrives me/drive/rootme/drive/root
Alerte de sécuritéSecurity alert security/alerts?$filter=status eq ‘New’security/alerts?$filter=status eq ‘New’
RéponseResponse

Voici un exemple de la réponse. Remarque : L’objet de réponse illustré ici peut être tronqué à des fins de concision. Toutes les propriétés sont renvoyées à partir d’un appel réel.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"
}

Validation du point de terminaison de notificationNotification endpoint validation

L’abonnement de point de terminaison de notification (spécifié dans la propriéténotificationUrl) doit être capable de répondre à une demande de validation comme décrit dans Configurer les notifications pour les modifications dans les données utilisateur.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. Si la validation échoue, la demande pour créer l’abonnement renvoie une erreur 400 de Requête incorrecte.If validation fails, the request to create the subscription returns a 400 Bad Request error.