Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Espace de noms: microsoft.graph
Importante
Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .
Attention
Les applications existantes qui utilisent cette fonctionnalité avec baseTask ou baseTaskList doivent être mises à jour, car l’ensemble d’API To-Do basé sur ces ressources est déconseillé depuis le 31 mai 2022. Cet ensemble d'API cessera de renvoyer des données le 31 août 2022. Veuillez utiliser l’ensemble d’API basé sur todoTask.
Représente un abonnement qui permet à une application cliente de recevoir des notifications de modification des modifications apportées aux données dans Microsoft Graph.
Pour plus d’informations sur les abonnements et les notifications de modification, y compris les ressources qui prennent en charge les notifications de modification, consultez Configurer des notifications pour les modifications apportées aux données de ressource.
Méthodes
| Méthode | Type renvoyé | Description |
|---|---|---|
| List | abonnement | Répertorier les abonnements actifs. |
| Create | abonnement | Abonnez une application d’écoute pour recevoir des notifications de modification lorsque les données Microsoft Graph changent. Lorsqu’une inscription est créée et valdée avec succès, Microsoft Graph envoie à l’application au moins un objet changeNotificationCollection chaque fois qu’il y a une modification dans la ressource abonnée. |
| Obtenir | abonnement | Lire les propriétés et les relations de l’objet d’abonnement. |
| Mettre à jour | abonnement | Renouveler un abonnement en mettant à jour son heure d’expiration. |
| Supprimer | Aucun | Supprimer un objet d’abonnement. |
| Autorisez à nouveau | Aucun | Autorisez à nouveau un abonnement lorsque vous recevez une demande d’autorisation ReauthorizationRequired . |
| Obtenir VAPID | String | Récupérez la clé publique VAPID (Voluntary Application Server Identification) à utiliser pour créer un abonnement après RFC8292. |
Propriétés
| Propriété | Type | Description |
|---|---|---|
| applicationId | Chaîne | Facultatif. Identificateur de l’application utilisée pour créer l’abonnement. En lecture seule. |
| changeType | Chaîne | Obligatoire. Indique le type de modification de la ressource abonnée qui génère une notification de modification. Les valeurs prises en charge sont : created, updated, deleted. Plusieurs valeurs peuvent être combinées à l’aide d’une liste délimitée par des virgules. Remarque :
|
| clientState | String | Facultatif. Spécifie la valeur de la propriété clientState envoyée par le service dans chaque notification de modification. La longueur maximale est de 255 caractères. Le client peut vérifier la case activée que la notification de modification provient du service en comparant la valeur de la propriété clientState envoyée avec l’abonnement avec la valeur de la propriété clientState reçue avec chaque notification de modification. |
| creatorId | String | Facultatif. Identificateur de l’utilisateur ou le principal de service qui a créé l’abonnement. Si l’application a utilisé des autorisations déléguées pour créer l’abonnement, ce champ contient l’ID de l’utilisateur connecté que l’application a appelé pour le compte. Si l’application a utilisé des autorisations d’application, ce champ contient l’ID du principal de service correspondant à l’application. En lecture seule. |
| encryptionCertificate | String | Facultatif. Représentation base64 d’un certificat avec une clé publique utilisée pour chiffrer des données de ressources dans les notifications de modifications. Facultatif, mais requis lorsque includeResourceData esttrue . |
| encryptionCertificateId | String | Facultatif. Identificateur fourni par une application personnalisée pour vous aider à identifier le certificat nécessaire au déchiffrement des données de ressource. Obligatoire lorsque includeResourceData est true. |
| expirationDateTime | DateTimeOffset | Obligatoire. Spécifie la date et l’heure d’expiration de l’abonnement webhook. L’heure est au format UTC et peut être une durée depuis la création d’un abonnement, qui varie pour la ressource à laquelle l’utilisateur est abonné. Toute valeur inférieure à 45 minutes après l’heure de la demande est automatiquement définie sur 45 minutes après l’heure de la demande. Pour connaître la durée maximale prise en charge de l’abonnement, consultez Durée de vie de l’abonnement. |
| id | String | Facultatif. Identificateur unique pour l’abonnement. En lecture seule. |
| includeResourceData | Boolean | Facultatif. Lorsque la valeur est true, les notifications de modification incluent les données de ressources (telles que le contenu d’un message de conversation). |
| latestSupportedTlsVersion | String | Facultatif. Indique la dernière version de TLS (Transport Layer Security) que le point de terminaison de notification, spécifié par notificationUrl, prend en charge. Les valeurs possibles sont v1_0, v1_1, v1_2, v1_3.
Pour les abonnés dont le point de terminaison de notification prend en charge une version inférieure à la version actuellement recommandée (TLS 1.2), la spécification de cette propriété par une chronologie définie leur permet d’utiliser temporairement leur version déconseillée de TLS avant de terminer leur mise à niveau vers TLS 1.2. Pour ces abonnés, le fait de ne pas définir cette propriété en raison de la chronologie entraîne l’échec des opérations d’abonnement. Pour les abonnés dont le point de terminaison de notification prend déjà en charge TLS 1.2, la définition de cette propriété est facultative. Dans ce cas, Microsoft Graph par défaut, la propriété est v1_2. |
| lifecycleNotificationUrl | String | Obligatoire pour les ressources Teams si la valeur est antérieure à expirationDateTime une heure ; facultatif dans le cas contraire. URL du point de terminaison qui reçoit les notifications de cycle de vie, y compris subscriptionRemoved, reauthorizationRequiredet les missed notifications. Cette URL doit utiliser le protocole HTTPS. Pour plus d’informations, consultez Réduire les abonnements manquants et modifier les notifications. |
| notificationContentType | String | Facultatif. Type de contenu souhaité pour Microsoft Graph notifications de modification pour les types de ressources pris en charge. Le type de contenu par défaut est application/json . |
| notificationQueryOptions | String | Facultatif. Options de requête OData pour spécifier la valeur de la ressource de ciblage. Les clients reçoivent des notifications lorsque la ressource atteint l’état correspondant aux options de requête fournies ici. Avec cette nouvelle propriété dans la charge utile de création de l’abonnement ainsi que toutes les propriétés existantes, les webhooks envoient des notifications chaque fois qu’une ressource atteint l’état souhaité mentionné dans la propriété notificationQueryOptions . Par exemple, lorsque le travail d’impression est terminé ou lorsqu’une valeur de propriété de ressource de travail isFetchable d’impression true devient, etc. Pris en charge uniquement pour le service d’impression universel. Pour plus d’informations, consultez S’abonner pour modifier les notifications des API d’impression cloud à l’aide de Microsoft Graph. |
| notificationUrl | Chaîne | Obligatoire. URL du point de terminaison qui reçoit les notifications de modification. Cette URL doit utiliser le protocole HTTPS. Tout paramètre de chaîne de requête inclus dans la propriété notificationUrl est inclus dans la requête HTTP POST lorsque Microsoft Graph envoie les notifications de modification. |
| notificationUrlAppId | String | Facultatif. ID d’application que le service d’abonnement peut utiliser pour générer le jeton de validation. La valeur permet au client de valider l’authenticité de la notification reçue. |
| ressource | Chaîne | Obligatoire. Spécifie la ressource dont les modifications sont surveillées. N’incluez pas l’URL de base (https://graph.microsoft.com/beta/). Voir les valeurs possibles de chemin d’accès ressource pour chaque ressource prise en charge. |
| vapidPublicKey | String | Facultatif. Clé publique VAPID du serveur d’applications, codée en base64url (point non compressé P-256, pré-encodage de 65 octets). Obtenu en appelant la fonction getVapidPublicKey sur la collection d’abonnements. Le navigateur transmet cette valeur à pour PushManager.subscribe({ applicationServerKey }) lier l’abonnement push à cette identité de serveur. Obligatoire lorsque notificationUrl cible une origine de service Web Push connue (par exemple, *.push.apple.com, fcm.googleapis.comupdates.push.services.mozilla.com, ) ; rejeté avec 400 Bad Request si fourni sur un abonnement Webhook standard. Pour plus d’informations, reportez-vous à RFC 8292. |
| webPushEncryptionP256dhPublicKey | String | Facultatif. Clé publique ECDH de l’abonné, codée en base64url (point non compressé P-256, pré-encodage de 65 octets). Obtenu à partir du navigateur via PushSubscription.getKey('p256dh'). Utilisée comme clé publique d’homologue pendant l’accord de clé ECDH pour dériver la clé de chiffrement de contenu par message pour le chiffrement de charge utile RFC 8291. Obligatoire lorsque notificationUrl cible une origine connue du service Web Push ; rejeté avec 400 Bad Request si fourni sur un abonnement webhook standard. Pour plus d’informations, reportez-vous à la section 3 RFC 8291. |
| webPushEncryptionSecret | String | Facultatif. Secret d’authentification de l’abonné, codé en base64url (pré-encodage de 16 octets). Obtenu à partir du navigateur via PushSubscription.getKey('auth'). Utilisé comme sel HMAC-SHA-256 pour l’étape de moissonneuse-batteuse HKDF qui dérive le matériel de clé pour le chiffrement de la charge utile RFC 8291. Écriture seule : cette valeur n’est jamais renvoyée dans les réponses GET (renvoyée en tant que null). Traiter comme un secret. Obligatoire lorsque notificationUrl cible une origine connue du service Web Push ; rejeté avec 400 Bad Request si fourni sur un abonnement webhook standard. Pour plus d’informations, reportez-vous à la section 3 RFC 8291. |
Durée de vie de l’abonnement
Les abonnements ont une durée de vie limitée. Les applications doivent renouveler leurs abonnements avant la date d’expiration ; Dans le cas contraire, ils doivent créer un abonnement. Les applications peuvent également annuler leur abonnement à tout moment pour ne plus recevoir de notifications de modifications.
En outre, toute demande dont expirationDateTime est définie sur moins de 45 minutes après l’heure de la demande est automatiquement définie sur 45 minutes après l’heure de la demande.
Le tableau suivant indique les délais d’expiration maximaux des abonnements par ressource dans Microsoft Graph.
| Resource | Délai d’expiration maximal |
|---|---|
| Copilot aiInteraction | 4 320 minutes (trois jours) |
| Alerte de sécurité | 43 200 minutes (moins de 30 jours) |
| Approbations Teams | 43 200 minutes (moins de 30 jours) |
| Teams callRecord | 4 230 minutes (moins de trois jours) |
| Teams callRecording | 4 320 minutes (trois jours) |
| Teams callTranscript | 4 320 minutes (trois jours) |
| Canal Teams | 4 320 minutes (trois jours) |
| Conversation Teams | 4 320 minutes (trois jours) |
| chatmessage Teams | 4 320 minutes (trois jours) |
| conversationMember Teams | 4 320 minutes (trois jours) |
| Teams onlineMeeting | 4 320 minutes (trois jours) |
| Équipe Teams | 4 320 minutes (trois jours) |
| Teams teamsAppInstallation | 4 320 minutes (3 jours) |
| Teams Shifts offerShiftRequest | 360 minutes (6 heures) |
| Teams Shifts openShiftChangeRequest | 360 minutes (6 heures) |
| Teams Shifts | 360 minutes (6 heures) |
| Teams Shifts swapShiftsChangeRequest | 360 minutes (6 heures) |
| Teams Shifts timeOffRequest | 360 minutes (6 heures) |
| Conversation de groupe | 4 230 minutes (moins de trois jours) |
| OneDrive driveItem | 42 300 minutes (moins de 30 jours) |
| Liste SharePoint | 42 300 minutes (moins de 30 jours) |
| Message Outlook, événement, contact | 10 080 minutes (moins de sept jours) Pour les abonnements avec des données de ressources (abonnements à notification enrichie), la durée de vie de l’abonnement est de 1 440 minutes (inférieure à un jour). |
| Ressources d’utilisateur, de groupeet d’annuaire | 41 760 minutes (moins de 29 jours) |
| onlineMeeting | 4 230 minutes (moins de trois jours) |
| présence | 60 minutes (1 heure) |
| Imprimer imprimante | 4 230 minutes (moins de trois jours) |
| Imprimer printTaskDefinition | 4 230 minutes (moins de trois jours) |
| todoTask | 4 230 minutes (moins de trois jours) Les webhooks pour cette ressource sont uniquement disponibles dans le point de terminaison global et non dans les clouds nationaux. |
| Alerte de surveillance de l’intégrité de Microsoft Entra | 42 300 minutes (moins de 30 jours) |
| baseTask (déconseillé) | 4 230 minutes (moins de trois jours) |
Note:les applications existantes et nouvelles ne doivent pas dépasser la valeur prise en charge. À l’avenir, les demandes pour créer ou renouveler un abonnement au-delà de la valeur maximale peut échouer.
Latence
Le tableau suivant indique le temps de latence à prévoir entre un événement survenant dans le service et la remise de la notification de changement.
| Ressource | Latence moyenne | Latence maximale |
|---|---|---|
| aiInteraction | Moins de 10 secondes | 60 minutes |
| Alerte1 | Moins de 3 minutes | 5 minutes |
| Approbations | Moins de 10 secondes | 40 secondes |
| calendar | Less than 1 minute | 3 minutes |
| callRecord2 | Moins de 30 minutes | 150 minutes de film |
| callRecording | Moins de 10 secondes | 60 minutes |
| transcription de callTranscript | Moins de 10 secondes | 60 minutes |
| canal | Moins de 10 secondes | 60 minutes |
| conversation | Moins de 10 secondes | 60 minutes |
| chatMessage | Moins de 10 secondes | 1 minute |
| contact | Less than 1 minute | 3 minutes |
| conversation | Inconnu | Inconnu |
| conversationMember | Moins de 10 secondes | 60 minutes |
| driveItem | Less than 1 minute | 6 heures |
| événement | Inconnu | Inconnu |
| groupe | Inconnu | Inconnu |
| Alerte de surveillance de l’intégrité | Inconnu | Inconnu |
| liste | Less than 1 minute | 6 heures |
| message | Less than 1 minute | 3 minutes |
| offerShiftRequest | Less than 1 minute | 60 minutes |
| onlineMeeting | Moins de 10 secondes | 1 minute |
| openShiftChangeRequest | Less than 1 minute | 60 minutes |
| présence | Moins de 10 secondes | 1 minute |
| imprimante | Less than 1 minute | 5 minutes |
| printTaskDefinition | Less than 1 minute | 5 minutes |
| shift | Less than 1 minute | 60 minutes |
| swapShiftsChangeRequest | Less than 1 minute | 60 minutes |
| équipe | Moins de 10 secondes | 60 minutes |
| teamsAppInstallation | Moins de 10 secondes | 60 minutes |
| timeOffRequest | Less than 1 minute | 60 minutes |
| todoTask | Moins de 2 minutes | 15 minutes |
| utilisateur | Inconnu | Inconnu |
1 La latence fournie pour la ressource d’alerte s’applique uniquement après la création de l’alerte. Il n’inclut pas le temps nécessaire à une règle pour créer une alerte à partir des données. 2 La latence fournie pour la ressource callRecord ne s’applique qu’à la première version d’un enregistrement d’appel. Les versions ultérieures d’un enregistrement d’appel peuvent être mises à jour au-delà des latences indiquées.
Relations
Aucun.
Représentation JSON
La représentation JSON suivante montre le type de ressource.
{
"@odata.type": "#microsoft.graph.subscription",
"applicationId": "String",
"changeType": "String",
"clientState": "String",
"creatorId": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"expirationDateTime": "String (timestamp)",
"id": "String (identifier)",
"includeResourceData": "Boolean",
"latestSupportedTlsVersion": "String",
"lifecycleNotificationUrl": "String",
"notificationContentType": "String",
"notificationQueryOptions": "String",
"notificationUrl": "String",
"notificationUrlAppId": "String",
"resource": "String",
"vapidPublicKey": "String",
"webPushEncryptionP256dhPublicKey": "String",
"webPushEncryptionSecret": "String"
}