Tipo de recurso subscription

Artículo
10/30/2023

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 basado en 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. Use el conjunto de API basado en todoTask.

Representa una suscripción que permite a una aplicación cliente recibir notificaciones de cambios sobre los cambios en los datos de Microsoft Graph.

Para obtener más información sobre las suscripciones y las notificaciones de cambio, incluidos los recursos que admiten notificaciones de cambio, consulte Configuración de notificaciones para cambios en los datos de recursos.

Métodos

Método	Tipo de valor devuelto	Descripción
Enumerar suscripciones	subscription	Enumera las suscripciones activas.
Crear suscripción	subscripción	Suscríbase a una aplicación de escucha para recibir notificaciones de cambio cuando cambien los datos de Microsoft Graph.
Obtener suscripción	subscription	Lee las propiedades y las relaciones del objeto de suscripción.
Actualizar suscripción	subscription	Renueve una suscripción actualizando su hora de expiración.
Eliminar suscripción	Ninguno	Eliminar un objeto de suscripción.
Volver a autorizar	Ninguno	Vuelva a autorizar una suscripción cuando reciba un desafío reauthorizationRequired .

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: Las notificaciones de cambio de lista y elemento raíz de unidad solo admiten`updated` changeType. Los cambios de notificaciones de usuario y de grupo admiten `updated` y `deleted` changeType. Use `updated` para recibir notificaciones cuando el usuario o grupo se cree, actualice o elimine temporalmente. Use `deleted` para recibir notificaciones cuando el usuario o el grupo se eliminen permanentemente.
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 que inició sesión al que llamó la aplicación en nombre de . 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 es`true`.
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. Necesario 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. Para obtener la duración máxima de la suscripción admitida, 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), especificar esta propiedad mediante una escala de tiempo establecida les permite usar temporalmente su versión en desuso de TLS antes de completar su 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	Es 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. Dirección URL del punto de conexión que recibe notificaciones de ciclo de vida, incluidas `subscriptionRemoved`las notificaciones , `reauthorizationRequired`y `missed` . 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 es`application/json`.
notificationQueryOptions	Cadena	Opcional. Opciones de consulta de 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 la suscripción 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 mediante Microsoft Graph.
notificationUrl	Cadena	Obligatorio. Dirección URL del punto de conexión que recibe las notificaciones de cambio. 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 incluya la dirección URL base (`https://graph.microsoft.com/beta/`). Vea los posibles valores de ruta de acceso para cada recurso compatible.

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, deben crear una nueva suscripción. Las aplicaciones también pueden cancelar la suscripción en cualquier momento para dejar de recibir notificaciones.

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
Alerta de seguridad	43 200 minutos (menos de 30 días)
callRecord de Teams	4.230 minutos (menos de 3 días)
Llamada de TeamsRegistro	4.320 minutos (3 días)
Llamada de TeamsTranscript	4.320 minutos (3 días)
Canal de Teams	4.320 minutos (3 días)
Chat de Teams	4.320 minutos (3 días)
chatmessage de Teams	4.320 minutos (3 días)
conversationMember de Teams	4.320 minutos (3 días)
onlineMeeting de Teams	4.320 minutos (3 días)
Equipo de Teams	4.320 minutos (3 días)
Conversación de grupo	4.230 minutos (menos de 3 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	4.230 minutos (menos de 3 días)
usuario, grupo, otros recursos del directorio	41 760 minutos (menos de 29 días)
onlineMeeting	4.230 minutos (menos de 3 días)
presencia	60 minutos (1 hora)
Imprimir printer	4.230 minutos (menos de 3 días)
Imprimir printTaskDefinition	4.230 minutos (menos de 3 días)
todoTask	4.230 minutos (menos de 3 días) Los webhooks para este recurso solo están disponibles en el punto de conexión global y no en las nubes nacionales.
baseTask (en desuso)	4.230 minutos (menos de 3 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
alerta¹	Menos de 3 minutos	5 minutos
calendar	Menos de 1 minuto	3 minutos
callRecord	Menos de 15 minutos	60 minutos
callRecording	Menos de 10 segundos	60 minutos
callTranscript	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	5 minutos
event	Unknown	Unknown
group	Unknown	Unknown
list	Menos de 1 minuto	5 minutos
message	Menos de 1 minuto	3 minutos
onlineMeeting	Menos de 10 segundos	1 minuto
presencia	Menos de 10 segundos	1 minuto
printer	Menos de 1 minuto	5 minutos
printTaskDefinition	Menos de 1 minuto	5 minutos
team	Menos de 10 segundos	60 minutos
todoTask	Menos de 2 minutos	15 minutos
user	Menos de 2 minutos	15 minutos

¹ 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.

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