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 ressources : 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 de cloud national suivants.

Autorisations

La création d’un abonnement nécessite un accès en lecture à la ressource. Par exemple, pour recevoir des notifications de modification sur les messages, votre application a besoin de l’autorisation 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.

Nous vous recommandons d’utiliser les autorisations décrites dans le tableau précédent. En raison de restrictions de sécurité, les abonnements Microsoft Graph ne prennent pas en charge les autorisations d’accès en écriture lorsque seules des autorisations d’accès en lecture sont nécessaires.

Remarque : les autorisations marquées d’un astérisque (*) utilisent une autorisation propre aux ressources.

chatMessage

Les abonnements chatMessage peuvent être spécifiés pour inclure des données de ressource. S’il est spécifié pour inclure des données de ressource (ncludeResourceData défini sur true), le chiffrement est nécessaire. La création de l’abonnement échoue si un encryptionCertificate n’est pas spécifié pour ces abonnements.

Vous devez utiliser l’en-tête Prefer: include-unknown-enum-members de requête pour obtenir les valeurs suivantes dans chatMessagemessageTypeevolvable enum : systemEventMessage for /teams/{id}/channels/{id}/messages et /chats/{id}/messages resource.

conversationMember

Les abonnements conversationMember peuvent être spécifiés pour inclure des données de ressources. S’il est spécifié pour inclure des données de ressource (ncludeResourceData défini sur true), le chiffrement est nécessaire. La création de l’abonnement échoue si un encryptionCertificate n’est pas spécifié.

équipe, canal et conversation

Les abonnements d’équipe, de canal et de conversation peuvent être spécifiés pour inclure des données de ressources. S’il est spécifié pour inclure des données de ressource (ncludeResourceData défini sur true), le chiffrement est nécessaire. La création de l’abonnement échoue si un encryptionCertificate n’est pas spécifié.

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

Exemple de requête

Spécifiez model le paramètre de requête dans la propriété de ressource dans le corps de la requête.

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

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "chats/getAllMessages?model=A",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

driveItem

Des limitations supplémentaires s’appliquent aux abonnements sur les é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 pour les entreprises, vous pouvez vous abonner uniquement au dossier racine. 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. Vous ne pouvez pas vous abonner à des instances drive ou driveItem qui ne sont pas des dossiers, tels que des fichiers individuels.

OneDrive Entreprise et SharePoint prennent en charge l’envoi de notifications d’événements de sécurité 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. Cette fonctionnalité est applicable à SharePoint et OneDrive Entreprise, mais pas aux comptes OneDrive consommateurs.

contact, événement et message

Vous pouvez vous abonner aux modifications apportées aux ressources decontact, d’événements, ou de messages d’Outlook.

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 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 sur les éléments des dossiers partagés ou délégués.

présence

Les abonnements à la présence nécessitent le chiffrement des données de ressources incluses dans une notification de modification. Spécifiez toujours le paramètre encryptionCertificate lors de la création d’un abonnement pour éviter toute défaillance. Afficher plus d’informations sur la configuration des notifications de modification pour inclure des données de ressources

virtualEventWebinar

Les abonnements aux événements virtuels prennent uniquement en charge les notifications de base et sont limités à quelques entités d’un événement virtuel. Pour plus d’informations sur les types d’abonnements 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 le code de réponse 201 Created et un objet abonnement dans le corps de la réponse. Pour plus d’informations sur le retour des erreurs, voir Réponses aux erreurs.

Exemple

Demande

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

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

// Dependencies
using Microsoft.Graph.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://video2.skills-academy.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions.PostAsync(requestBody);

mgc subscriptions create --body '{\
   "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 major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-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://video2.skills-academy.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')
	.post(subscription);

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\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.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-MgSubscription -BodyParameter $params

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription
# To initialize your graph_client, see https://video2.skills-academy.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 requête é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 valides pour la propriété de ressource de l’abonnement sont les suivantes :

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.

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

Validation du point de terminaison de notification

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. Si la validation échoue, la demande pour créer l’abonnement renvoie une erreur 400 de Requête incorrecte.