Créer un abonnementCreate subscription

Espace de noms: microsoft.graphNamespace: microsoft.graph

S’abonne à une application d’écouteur afin de recevoir des notifications de modification lorsque le type demandé de modifications se produit au niveau de la ressource spécifiée dans Microsoft Graph.Subscribes a listener application to receive change 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 notifications de modification sur les messages, votre application a besoin de l’autorisation Mail.Read.For example, to get change 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
callRecord (/communications/callRecords)callRecord (/communications/callRecords) Non pris en chargeNot supported Non pris en chargeNot supported CallRecords.Read.AllCallRecords.Read.All
chatMessage (/teams/{id}/channels/{id}/messages)chatMessage (/teams/{id}/channels/{id}/messages) Non pris en chargeNot supported Non pris en chargeNot supported ChannelMessage.Read.AllChannelMessage.Read.All
chatMessage (/teams/getAllMessages -- tous les messages de canal dans l’organisation)chatMessage (/teams/getAllMessages -- all channel messages in organization) Non pris en chargeNot supported Non pris en chargeNot supported ChannelMessage.Read.AllChannelMessage.Read.All
chatMessage (/chats/{ID}/messages)chatMessage (/chats/{id}/messages) Non pris en chargeNot supported Non pris en chargeNot supported Chat.Read.AllChat.Read.All
chatMessage (/teams/getAllMessages -- tous les messages de canal dans l’organisation)chatMessage (/chats/getAllMessages -- all chat messages in organization) Non pris en chargeNot supported Non pris en chargeNot supported Chat.Read.AllChat.Read.All
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
listelist Sites.ReadWrite.AllSites.ReadWrite.All Non pris en chargeNot 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
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

chatMessagechatMessage

chatMessage les abonnements avec les autorisations d’application incluent les données de ressource et nécessitent un chiffrement.chatMessage subscriptions with application permissions include resource data, and require encryption. La création d’un abonnement échouera si encryptionCertificate n’est pas spécifié.Subscription creation will fail if encryptionCertificate is not specified. Avant de créer un abonnement chatMessage, vous devez demander l’accès.Before creating a chatMessage subscription, you must request access. Pour plus d’informations, consultez API protégées dans Microsoft Teams.For details, see Protected APIs in Microsoft Teams.

Remarque : les /teams/getAllMessages et /chats/getAllMessages sont disponibles pour les utilisateurs disposant deslicences requises.Note: /teams/getAllMessages and /chats/getAllMessages are available to users that have the required licenses.

driveItemdriveItem

Des limitations supplémentaires s’appliquent aux abonnements sur les éléments OneDrive.Additional limitations apply for subscriptions on OneDrive 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 (getting, updating, and deleting) subscriptions.

Sur un OneDrive personnel, vous pouvez vous abonner au dossier racine ou à tout sous-dossier de ce lecteur.On a 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 de modification sont envoyées pour les types demandés de modifications sur le dossier concerné, ou n’importe quel fichier ou dossier, ou d’autres instances driveItem dans leur hiérarchie.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. 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.

contact, événement et messagecontact, event, and message

Des limitations supplémentaires s’appliquent aux abonnements sur les éléments Outlook.Additional limitations apply for subscriptions on 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 (getting, updating, and deleting) subscriptions.

  • L’autorisation déléguée permet de s'abonner à des articles dans des dossiers qui se trouvent uniquement dans la boîte aux lettres de l'utilisateur connecté.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 déléguée Calendars.Read pour vous abonner à des événements dans la boîte aux lettres d’un autre utilisateur.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. Pour plus d’informations sur le retour des erreurs, voir Réponses aux erreurs.For details about how errors are returned, see Error responses.

ExempleExample

DemandeRequest

L’exemple suivant demande l’envoi d’une notification de modification lorsque l’utilisateur reçoit un nouveau message.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"
}

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. Les champs clientState et latestSupportedTlsVersion sont facultatifs.The clientState and latestSupportedTlsVersion fields are 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 ExemplesExamples
Enregistrements d’appelsCall records communications/callRecords
Message de conversationChat message chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessageschats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
ContactsContacts me/contacts
ConversationsConversations groups('{id}')/conversations
DrivesDrives me/drive/root
ÉvénementsEvents me/events
GroupesGroups groups
ListeList sites/{site-id}/lists/{list-id}
MessagerieMail me/mailfolders('inbox')/messages, me/messagesme/mailfolders('inbox')/messages, me/messages
UtilisateursUsers users
Alerte de sécuritéSecurity alert security/alerts?$filter=status eq 'New'

Remarque : les chemins d’accès commençant par me peuvent également être utilisés avec users/{id} au lieu de me pour cibler un utilisateur spécifique au lieu de l’utilisateur actuel.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.

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

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.