Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Espacio de nombres: microsoft.graph
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
Precaución
Las aplicaciones existentes que usan esta característica con baseTask o baseTaskList deben actualizarse, ya que el conjunto de API de tareas pendientes creado a partir de estos recursos está en desuso a partir del 31 de mayo de 2022. Ese conjunto de API dejará de devolver datos el 31 de agosto de 2022. Utilice el conjunto de API creado en todoTask.
Representa una suscripción que permite a una aplicación cliente recibir notificaciones de cambios sobre cambios en los datos de Microsoft Graph.
Para obtener más información sobre las suscripciones y las notificaciones de cambios, incluidos los recursos que admiten notificaciones de cambios, vea Configurar notificaciones para cambios en los datos de recursos.
Métodos
| Método | Tipo de valor devuelto | Descripción |
|---|---|---|
| List | subscripción | Enumerar las suscripciones activas. |
| Crear | subscripción | Suscríbase a una aplicación de escucha para recibir notificaciones de cambios cuando cambien los datos de Microsoft Graph. Cuando se crea una suscripción y se valida correctamente, Microsoft Graph envía a la aplicación al menos un objeto changeNotificationCollection cada vez que se produce un cambio en el recurso suscrito. |
| Get | subscripción | Lea las propiedades y relaciones del objeto de suscripción. |
| Actualizar | subscripción | Renueva una suscripción actualizando su hora de expiración. |
| Delete | Ninguno | Eliminar un objeto de suscripción. |
| Reautorizar | Ninguno | Reautorice una suscripción cuando reciba un desafío reauthorizationRequired . |
| Obtener VAPID | Cadena | Obtenga la clave pública VAPID (Identificación voluntaria del servidor de aplicaciones) que se usará para crear la suscripción después de RFC8292. |
Propiedades
| Propiedad | Tipo | Descripción |
|---|---|---|
| applicationId | Cadena | Opcional. Identificador de la aplicación usado para crear la suscripción. Solo lectura. |
| changeType | Cadena | Obligatorio. Indica el tipo de cambio en el recurso suscrito que genera una notificación de cambio. Los valores admitidos son: created, updated, deleted. Se pueden combinar varios valores mediante una lista separada por comas. Nota:
|
| clientState | Cadena | Opcional. Especifica el valor de la propiedad clientState enviada por el servicio en cada notificación de cambio. La longitud máxima es 255 caracteres. El cliente puede comprobar que la notificación de cambio procede del servicio comparando el valor de la propiedad clientState enviada con la suscripción con el valor de la propiedad clientState recibida con cada notificación de cambio. |
| creatorId | Cadena | Opcional. Identificador de usuario o entidad de servicio que creó la suscripción. Si la aplicación usó permisos delegados para crear la suscripción, este campo contiene el identificador del usuario con la sesión iniciada por el que llamó la aplicación. Si la aplicación usó permisos de aplicación, este campo contiene el identificador de la entidad de servicio correspondiente a la aplicación. Solo lectura. |
| encryptionCertificate | Cadena | Opcional. Representación codificada en Base64 de un certificado con una clave pública que se usa para cifrar los datos de los recursos en las notificaciones de cambios. Opcional pero necesario cuando includeResourceData estrue. |
| encryptionCertificateId | Cadena | Opcional. Un identificador personalizado proporcionado por la aplicación que le ayude a identificar el certificado necesario para descifrar los datos del recurso. Se requiere cuando includeResourceData es true. |
| expirationDateTime | DateTimeOffset | Necesario. Especifica la fecha y hora en que expira la suscripción de webhook. La hora está en UTC y puede ser un periodo de tiempo desde la creación de la suscripción que varía para el recurso al que se está suscrito. Cualquier valor inferior a 45 minutos después de la hora de la solicitud se establece automáticamente en 45 minutos después de la hora de la solicitud. Para obtener el período máximo de tiempo de suscripción compatible, consulte Duración de la suscripción. |
| id | Cadena | Opcional. Identificador único de la suscripción. Solo lectura. |
| includeResourceData | Booleano | Opcional. Cuando se establece en true, las notificaciones de cambios incluyen datos del recurso (como el contenido de un mensaje de chat). |
| latestSupportedTlsVersion | Cadena | Opcional. Especifica la versión más reciente de Seguridad de la capa de transporte (TLS) que es compatible con el punto de conexión de notificación, especificado por notificationUrl. Los valores posibles son: v1_0, v1_1, v1_2, v1_3.
Para los suscriptores cuyo punto de conexión de notificación admite una versión inferior a la versión recomendada actualmente (TLS 1.2), la especificación de esta propiedad mediante una escala de tiempo establecida les permite usar temporalmente su versión en desuso de TLS antes de completar la actualización a TLS 1.2. Para estos suscriptores, no establecer esta propiedad por la escala de tiempo produciría un error en las operaciones de suscripción. Para los suscriptores cuyo punto de conexión de notificación ya admite TLS 1.2, establecer esta propiedad es opcional. En estos casos, Microsoft Graph establece de forma predeterminada la propiedad en v1_2. |
| lifecycleNotificationUrl | Cadena | Necesario para los recursos de Teams si el expirationDateTime valor es de más de 1 hora a partir de ahora; opcional en caso contrario. La dirección URL del punto de conexión que recibe notificaciones del ciclo de vida, incluidas subscriptionRemoved, reauthorizationRequiredy missed notificaciones. Esta dirección URL debe usar el protocolo HTTPS. Para obtener más información, consulte Reducción de las suscripciones que faltan y notificaciones de cambio. |
| notificationContentType | Cadena | Opcional. Tipo de contenido deseado para los cambios de notificaciones en Microsoft Graph para tipos de recursos admitidos. El tipo de contenido predeterminado esapplication/json. |
| notificationQueryOptions | Cadena | Opcional. Opciones de consulta OData para especificar el valor del recurso de destino. Los clientes reciben notificaciones cuando el recurso alcanza el estado que coincide con las opciones de consulta proporcionadas aquí. Con esta nueva propiedad en la carga de creación de suscripciones junto con todas las propiedades existentes, los webhooks entregan notificaciones cada vez que un recurso alcanza el estado deseado mencionado en la propiedad notificationQueryOptions . Por ejemplo, cuando se completa el trabajo de impresión o cuando el valor de propiedad de un recurso de trabajo de impresión isFetchable se convierte en true etc. Solo se admite para el servicio de impresión universal. Para obtener más información, consulte Suscribirse para cambiar las notificaciones de las API de impresión en la nube con Microsoft Graph. |
| notificationUrl | Cadena | Obligatorio. La dirección URL del punto de conexión que recibe las notificaciones de cambios. Esta dirección URL debe usar el protocolo HTTPS. Cualquier parámetro de cadena de consulta incluido en la propiedad notificationUrl se incluye en la solicitud HTTP POST cuando Microsoft Graph envía las notificaciones de cambio. |
| notificationUrlAppId | Cadena | Opcional. El identificador de aplicación que el servicio de suscripción puede usar para generar el token de validación. El valor permite al cliente validar la autenticidad de la notificación recibida. |
| resource | Cadena | Obligatorio. Especifica el recurso que se supervisa para los cambios. No incluyas la URL base (https://graph.microsoft.com/beta/). Vea los posibles valores de ruta de acceso para cada recurso compatible. |
| vapidPublicKey | Cadena | Opcional. La clave pública VAPID del servidor de aplicaciones, codificada en base64url (punto sin comprimir P-256, 65 bytes de precodificación). Se obtiene llamando a la función getVapidPublicKey en la colección de suscripción. El explorador pasa este valor para PushManager.subscribe({ applicationServerKey }) enlazar la suscripción de inserción a esta identidad del servidor. Se requiere cuando notificationUrl se dirige a un origen de servicio de inserción web conocido (por ejemplo, *.push.apple.comfcm.googleapis.com, , updates.push.services.mozilla.com); rechazado con 400 Bad Request si se proporciona en una suscripción de webhook estándar. Para obtener más información, vea RFC 8292. |
| webPushEncryptionP256dhPublicKey | Cadena | Opcional. La clave pública ECDH del suscriptor, codificada en base64url (punto sin comprimir P-256, 65 bytes de precodificación). Obtenido del navegador a través de PushSubscription.getKey('p256dh'). Se usa como clave pública del mismo nivel durante el acuerdo de clave ECDH para derivar la clave de cifrado de contenido por mensaje para el cifrado de carga útil RFC 8291. Se requiere cuando notificationUrl se dirige a un origen conocido de servicio de inserción web; 400 Bad Request Si se proporciona en una suscripción de webhook estándar. Para obtener más información, consulte RFC 8291 Sección 3. |
| webPushEncryptionSecret | Cadena | Opcional. El secreto de autenticación del suscriptor, codificado en base64url (16 bytes de precodificación). Obtenido del navegador a través de PushSubscription.getKey('auth'). Se usa como sal HMAC-SHA-256 para el paso de combinación HKDF que deriva el material clave para el cifrado de carga útil RFC 8291. Solo escritura: este valor nunca se devuelve en las respuestas GET (devueltas como null). Trátalo como un secreto. Se requiere cuando notificationUrl se dirige a un origen conocido de servicio de inserción web; 400 Bad Request Si se proporciona en una suscripción de webhook estándar. Para obtener más información, consulte RFC 8291 Sección 3. |
Duración de la suscripción
Las suscripciones tienen una duración limitada. Las aplicaciones deben renovar sus suscripciones antes de la hora de expiración; De lo contrario, tendrán que crear una nueva suscripción. Las aplicaciones también pueden cancelar la suscripción en cualquier momento para dejar de recibir notificaciones.
Además, cualquier solicitud con expirationDateTime establecida en menos de 45 minutos después de la hora de la solicitud se establece automáticamente en 45 minutos después de la hora de la solicitud.
En la tabla siguiente se muestran los tiempos máximos de expiración de las suscripciones por recurso en Microsoft Graph.
| Resource | Tiempo de expiración máximo |
|---|---|
| Copilot aiInteraction | 4,320 minutos (tres días) |
| alerta de seguridad | 43.200 minutos (menos de 30 días) |
| Aprobaciones de Teams | 43.200 minutos (menos de 30 días) |
| callRecord de Teams | 4.230 minutos (menos de tres días) |
| Grabación de llamadas de Teams | 4,320 minutos (tres días) |
| Teams callTranscript | 4,320 minutos (tres días) |
| Canal de Teams | 4,320 minutos (tres días) |
| Chat de Teams | 4,320 minutos (tres días) |
| chatmessage de Teams | 4,320 minutos (tres días) |
| conversationMember de Teams | 4,320 minutos (tres días) |
| onlineMeeting de Teams | 4,320 minutos (tres días) |
| Equipo de Teams | 4,320 minutos (tres días) |
| Teams teamsAppInstallation | 4.320 minutos (3 días) |
| Oferta de turnos de TeamsShiftRequest | 360 minutos (6 horas) |
| Turnos de Teams openShiftChangeRequest | 360 minutos (6 horas) |
| Turno de Turnos de Teams | 360 minutos (6 horas) |
| Cambios de turnos de Teams swapShiftsChangeRequest | 360 minutos (6 horas) |
| Turnos de Teams timeOffRequest | 360 minutos (6 horas) |
| Conversación de grupo | 4.230 minutos (menos de tres días) |
| driveItem de OneDrive | 42.300 minutos (menos de 30 días) |
| lista de SharePoint | 42.300 minutos (menos de 30 días) |
| Mensaje, evento, contacto de Outlook | 10.080 minutos (menos de siete días) En el caso de las suscripciones con datos de recursos (suscripciones de notificación enriquecidas), la duración de la suscripción es de 1440 minutos (menos de un día). |
| usuario, grupo, otros recursos del directorio | 41.760 minutos (menos de 29 días) |
| onlineMeeting | 4.230 minutos (menos de tres días) |
| presencia | 60 minutos (1 hora) |
| Imprimir printer | 4.230 minutos (menos de tres días) |
| Imprimir printTaskDefinition | 4.230 minutos (menos de tres días) |
| todoTask | 4.230 minutos (menos de tres días) Los webhooks para este recurso solo están disponibles en el punto de conexión global y no en las nubes nacionales. |
| Alerta de supervisión de mantenimiento de Microsoft Entra | 42.300 minutos (menos de 30 días) |
| baseTask (obsoleto) | 4.230 minutos (menos de tres días) |
Nota: Las nuevas aplicaciones y las aplicaciones existentes no deben superar el valor admitido. En el futuro, se producirá un error en las solicitudes para crear o renovar una suscripción si se supera el valor máximo.
Latencia
En la siguiente tabla se muestra una lista de la latencia esperada entre el momento en que ocurren los eventos en el servicio y el envío de la notificación de cambios.
| Recurso | Latencia promedio | Latencia máxima |
|---|---|---|
| aiInteracción | Menos de 10 segundos | 60 minutos |
| Alerta1 | Menos de 3 minutos | 5 minutos |
| Aprobaciones | Menos de 10 segundos | 40 segundos |
| calendar | Menos de 1 minuto | 3 minutos |
| callRecord2 | Menos de 30 minutos | 150 minutos |
| grabación de llamadas | Menos de 10 segundos | 60 minutos |
| Transcripción de llamadas | Menos de 10 segundos | 60 minutos |
| channel | Menos de 10 segundos | 60 minutos |
| chat | Menos de 10 segundos | 60 minutos |
| chatMessage | Menos de 10 segundos | 1 minuto |
| contact | Menos de 1 minuto | 3 minutos |
| conversation | Unknown | Unknown |
| conversationMember | Menos de 10 segundos | 60 minutos |
| driveItem | Menos de 1 minuto | 6 horas |
| event | Unknown | Unknown |
| group | Unknown | Unknown |
| alerta de supervisión de mantenimiento | Unknown | Unknown |
| list | Menos de 1 minuto | 6 horas |
| message | Menos de 1 minuto | 3 minutos |
| offerShiftRequest | Menos de 1 minuto | 60 minutos |
| onlineMeeting | Menos de 10 segundos | 1 minuto |
| openShiftChangeRequest | Menos de 1 minuto | 60 minutos |
| presencia | Menos de 10 segundos | 1 minuto |
| printer | Menos de 1 minuto | 5 minutos |
| printTaskDefinition | Menos de 1 minuto | 5 minutos |
| shift | Menos de 1 minuto | 60 minutos |
| swapShiftsChangeRequest | Menos de 1 minuto | 60 minutos |
| team | Menos de 10 segundos | 60 minutos |
| teamsAppInstallation | Menos de 10 segundos | 60 minutos |
| timeOffRequest | Menos de 1 minuto | 60 minutos |
| todoTask | Menos de 2 minutos | 15 minutos |
| user | Unknown | Unknown |
1 La latencia proporcionada para el recurso de alerta solo es aplicable después de crear la alerta. No incluye el tiempo que tarda una regla en crear una alerta a partir de los datos. 2 La latencia proporcionada para el recurso callRecord solo es aplicable a la primera versión de un registro de llamada. Las versiones posteriores de un registro de llamada pueden actualizarse más allá de las latencias indicadas.
Relaciones
Ninguna.
Representación JSON
La siguiente representación JSON muestra el tipo de recurso.
{
"@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"
}