Créer un abonnement

Espace de noms: 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.

Pour identifier les ressources pour lesquelles vous pouvez créer des abonnements et les limitations des abonnements, consultez Configurer des notifications pour les modifications apportées aux données de ressource : Ressources prises en charge.

Certaines ressources prennent en charge les notifications enrichies, c’est-à-dire les notifications qui incluent des données de ressources. Pour plus d’informations sur ces ressources, consultez Configurer des notifications de modification qui incluent des données de ressource : Ressources prises en charge.

Cette API est disponible dans les déploiements cloud nationaux suivants.

Autorisations

La création d’un abonnement nécessite une autorisation de lecture sur la ressource. Par exemple, pour obtenir des notifications de modification sur les messages, votre application doit disposer des autorisations Mail.Read.

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. Pour en savoir plus, notamment sur les mesures de prudence avant de choisir des autorisations, recherchez les autorisations dans Autorisations.

chatMessage

chatMessage peuvent être spécifiés pour inclure les données de ressource (includeResourceData défini sur true). Dans ce cas, le chiffrement est requis et la création de l’abonnement échoue si un encryptionCertificate n’est pas spécifié pour ces abonnements.

Utilisez l’en-tête de Prefer: include-unknown-enum-members requête pour obtenir les valeurs suivantes dans chatMessagemessageTypeénumération évolutive : systemEventMessage pour /teams/{id}/channels/{id}/messages et /chats/{id}/messages ressource.

conversationMember

Les abonnements conversationMember peuvent être spécifiés pour inclure les données de ressources (includeResourceData défini sur true). Dans ce cas, le chiffrement est requis et la création de l’abonnement échoue si un encryptionCertificate n’est pas spécifié pour ces abonnements.

Équipe, canal et conversation

Les abonnements d’équipe, de canal et de conversation peuvent être spécifiés pour inclure les données de ressources (includeResourceData défini sur true). Dans ce cas, le chiffrement est requis et la création de l’abonnement échoue si un encryptionCertificate n’est pas spécifié pour ces abonnements.

Vous pouvez utiliser le paramètre de chaîne de requête notifyOnUserSpecificProperties lorsque vous vous abonnez aux modifications apportées à une conversation particulière ou au niveau de l’utilisateur. Lorsque vous définissez le paramètre de chaîne de requête notifyOnUserSpecificProperties sur true lors de la création de l’abonnement, deux types de charges utiles sont envoyés à l’abonné. L’un contient des propriétés spécifiques à l’utilisateur, tandis que l’autre est envoyé sans celles-ci. Pour plus d’informations, consultez Obtenir des notifications de modification pour les conversations à l’aide de Microsoft Graph.

aiInsights

Les abonnements à Copilot AI Insights nécessitent une licence Copilot valide qui inclut le plan de service Copilot suivant :

• Microsoft 365 Copilot Chat : 3f30311c-6b1e-48a4-ab79-725b469da960

aiInteraction

Les abonnements aux interactions Copilot AI nécessitent une licence Copilot valide qui inclut le plan de service Copilot suivant :

• Microsoft 365 Copilot Chat : 3f30311c-6b1e-48a4-ab79-725b469da960

Pour les abonnements qui ciblent les interactions Copilot AI dont un utilisateur particulier fait partie, l’utilisateur dans le chemin de ressource doit avoir les plans de service précédents qui lui sont attribués dans un état valide.

Pour les abonnements qui ciblent les interactions Copilot AI pour l’ensemble du client, le locataire doit disposer de licences valides approvisionnées qui incluent tous les plans de service Copilot précédents.

driveItem

D’autres limitations s’appliquent aux abonnements sur des éléments OneDrive. Les limitations s’appliquent à la création, ainsi que de la gestion des abonnements (prise, la mise à jour et suppression d’abonnements).

Sur un OneDrive personnel, vous pouvez vous abonner au dossier racine ou à tout sous-dossier de ce lecteur. Sur OneDrive professionnel ou scolaire, vous pouvez vous abonner uniquement au dossier racine. Des notifications de modification sont envoyées pour les modifications demandées sur le dossier abonné ou sur tout fichier, dossier ou autre instance de driveItem dans sa hiérarchie. Vous ne pouvez pas vous abonner à des instances de lecteur ou de driveItem qui ne sont pas des dossiers, comme des fichiers individuels.

OneDrive professionnel ou scolaire et support SharePoint envoyant à votre application des notifications d’événements de sécurité qui se produisent sur un driveItem. Pour vous abonner à ces événements, ajoutez l’en-tête prefer:includesecuritywebhooks à votre demande de création d’abonnement. Une fois l’abonnement créé, vous recevez des notifications lorsque les autorisations sur un élément changent. Cet en-tête s’applique à SharePoint et OneDrive professionnel ou scolaire, mais pas aux comptes OneDrive de consommateur.

contact, événement et message

Vous pouvez vous abonner aux modifications apportées aux ressources de contact, d’événement ou de message Outlook et éventuellement spécifier dans la charge utile de la requête POST s’il faut inclure des données de ressource chiffrées dans les notifications.

La création et la gestion (obtention, mise à jour et suppression) d’un abonnement nécessitent une étendue de lecture de la ressource. Par exemple, pour recevoir des notifications de modification sur les messages, votre application a besoin de l’autorisation Mail Read. Les notifications de modification Outlook prennent en charge les étendues d’autorisation déléguées et d’application. Notez les limitations suivantes :

• 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é. 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.

• Pour vous abonner afin de modifier les notifications de contacts, d’événements ou de messages dans Outlook dans dossierspartagés ou délégués:

  • 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.
  • N’utilisez pas les autorisations de partage d’Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared et leurs équivalents en lecture/écriture), car elles ne prennent pas en charge l’abonnement aux notifications de modification des éléments dans les dossiers partagés ou délégués.

onlineMeetings, présence

Les abonnements sur onlineMeetings et la présence nécessitent les propriétés encryptionCertificate et encryptionCertificateId lors de la création d’un abonnement pour les notifications avec des données de ressource chiffrées. Pour plus d’informations, consultez Configuration des notifications de modification pour inclure les données de ressource. Pour plus d’informations sur les abonnements à des réunions en ligne, consultez Obtenir des notifications de modification pour les réunions en ligne.

virtualEventWebinar et virtualEventTownhall

Les abonnements aux événements virtuels ne prennent en charge que les notifications de base et sont limités à quelques entités d’un événement virtuel. Pour plus d’informations sur les types d’abonnement pris en charge, consultez Obtenir des notifications de modification pour les mises à jour d’événements virtuels Microsoft Teams.

Requête HTTP

POST /subscriptions

En-têtes de demande

Corps de la demande

Dans le corps de la demande, fournissons une représentation JSON de l’objet d’abonnement.

Réponse

En cas de réussite, cette méthode renvoie un code de réponse et un 201 Created objet Subscription dans le corps de la réponse.

Pour plus d’informations sur le retour des erreurs, voir Réponses aux erreurs.

Exemple

Demande

Dans le corps de la demande, fournissez une représentation JSON de l’objet abonnement. Les champs clientState et latestSupportedTlsVersion sont facultatifs.

Cette demande crée un abonnement pour les notifications de modification relatives aux nouveaux messages reçus par l’utilisateur actuellement connecté.

POST https://graph.microsoft.com/beta/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"
}

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = 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",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewSubscription()
changeType := "created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/api/send/myNotifyClient"
requestBody.SetNotificationUrl(&notificationUrl) 
resource := "me/mailFolders('Inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-11-20T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 
latestSupportedTlsVersion := "v1_2"
requestBody.SetLatestSupportedTlsVersion(&latestSupportedTlsVersion) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/send/myNotifyClient");
subscription.setResource("me/mailFolders('Inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-11-20T18:23:45.9356913Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("secretClientValue");
subscription.setLatestSupportedTlsVersion("v1_2");
Subscription result = graphClient.subscriptions().post(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'
};

await client.api('/subscriptions')
	.version('beta')
	.post(subscription);

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('created');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/send/myNotifyClient');
$requestBody->setResource('me/mailFolders(\'Inbox\')/messages');
$requestBody->setExpirationDateTime(new \DateTime('2016-11-20T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');
$requestBody->setLatestSupportedTlsVersion('v1_2');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

Import-Module Microsoft.Graph.Beta.ChangeNotifications

$params = @{
	changeType = "created"
	notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient"
	resource = "me/mailFolders('Inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-11-20T18:23:45.9356913Z")
	clientState = "secretClientValue"
	latestSupportedTlsVersion = "v1_2"
}

New-MgBetaSubscription -BodyParameter $params

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.subscription import Subscription
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	change_type = "created",
	notification_url = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	resource = "me/mailFolders('Inbox')/messages",
	expiration_date_time = "2016-11-20T18:23:45.9356913Z",
	client_state = "secretClientValue",
	latest_supported_tls_version = "v1_2",
)

result = await graph_client.subscriptions.post(request_body)

Dans le corps de la demande, fournissez une représentation JSON de l’objet abonnement. Les champs clientState et latestSupportedTlsVersion sont facultatifs.

Comportement de l’abonnement en double

Les abonnements en double ne sont pas autorisés. Lorsqu’une demande d’abonnement contient les mêmes valeurs pour changeType et Resource qu’un abonnement existant, la demande échoue avec un code 409 Conflictd’erreur HTTP et le message Subscription Id <> already exists for the requested combinationd’erreur .

Exemples de ressources

Les valeurs suivantes sont valides pour la propriété de ressource.

Réponse

L’exemple suivant illustre la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@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",
  "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",
  "notificationContentType": "application/json"
}

Exemple 2 : créer un abonnement ciblant un point de terminaison web Push

L’exemple suivant crée un abonnement qui fournit des notifications de modification chiffrées à un point de terminaison Web Push natif du navigateur (tel que web.push.apple.com, fcm.googleapis.comou updates.push.services.mozilla.com).

Avant de créer cet abonnement, l’application basée sur un navigateur doit :

1. Appelez la fonction getVapidPublicKey sur la collection d’abonnement pour obtenir la clé publique VAPID de Microsoft Graph (RFC 8292).
2. Appelez PushManager.subscribe({ applicationServerKey: <vapidPublicKey> }) pour vous inscrire au service push du navigateur. Le navigateur renvoie des PushSubscription valeurs , p256dh, et auth qui contiennentendpoint.

L’application crée ensuite l’abonnement avec notificationUrl définie sur l’URL de point de terminaison du service push nu et les propriétés vapidPublicKey, webPushEncryptionP256dhPublicKey et webPushEncryptionSecret définies sur les valeurs renvoyées par le navigateur. Après la création, Microsoft Graph chiffre chaque notification selon RFC 8291 à l’aide des clés stockées et signe la demande avec VAPID avant de la publier dans le service push.

Demande

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://web.push.apple.com/QKmFUwSBFK8g7iY4t1...",
  "resource": "me/mailFolders('Inbox')/messages",
  "expirationDateTime": "2026-12-31T11:00:00.0000000Z",
  "clientState": "secretClientValue",
  "vapidPublicKey": "BNKm...base64url-encoded-server-vapid-public-key...",
  "webPushEncryptionP256dhPublicKey": "BNcR...base64url-encoded-client-public-key...",
  "webPushEncryptionSecret": "tBHI...base64url-encoded-auth-secret..."
}

Remarque : La propriété webPushEncryptionSecret est en écriture seule. Il n’est jamais renvoyé dans GET les réponses (renvoyé en tant que null). Traitez la valeur comme un secret.

Validation du point de terminaison de notification

Le point de terminaison de notification d’abonnement (spécifié dans la propriété notificationUrl ) doit être capable de répondre à une demande de validation, comme décrit dans Configurer des notifications pour les modifications apportées aux données utilisateur. Si la validation échoue, la demande pour créer l’abonnement renvoie une erreur 400 de Requête incorrecte.