Compartir a través de


presence: setPresence

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.

Establezca el estado de disponibilidad y actividad en una sesión de presencia de una aplicación para un usuario.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet

Sesiones de presencia

Un usuario puede tener varias sesiones de presencia porque el usuario puede estar en varios clientes de Teams (escritorio, móvil y web). Cada cliente de Teams tiene una sesión de presencia independiente y la presencia del usuario es un estado agregado de todas las sesiones subyacentes.

De forma similar, una aplicación puede tener su propia sesión de presencia para un usuario y poder actualizar el estado.

A continuación se muestra la precedencia de cómo se agregan los estados de sesión, con "A > B" que representa A con prioridad sobre B:

  • Estados de nivel de sesión de estado > preferidos por el usuario (el estado preferido por el usuario invalida los estados de nivel de sesión)
  • Entre los estados de nivel de sesión: DoNotDisturb > Busy > Available > Away

Nota: Cuando cambia la presencia de un usuario en Microsoft Graph, dado que el cliente de Teams usa el modo de sondeo, el estado de presencia tardará unos minutos en actualizarse.

Tiempo de espera, expiración y mantenimiento activo

Una sesión de presencia puede agotar el tiempo de espera y expirar, por lo que la aplicación debe llamar a esta API antes del tiempo de espera para mantener el estado de la sesión; o antes de la expiración, para mantener activa la sesión.

Una sesión de presencia puede agotar el tiempo de espera si la disponibilidad es Available y el tiempo de espera es de 5 minutos. Cuando se agota el tiempo de espera, el estado de presencia se desvanece en fases. Por ejemplo, si una aplicación establece la sesión de presencia como Available/Available, el estado cambiaría a Available/AvailableInactive en 5 minutos con el primer tiempo de espera, a continuación Away/Away , en otros 5 minutos con el segundo tiempo de espera.

La expiración de una sesión de presencia se puede configurar con el expirationDuration parámetro . Cuando una sesión expira, se convierte Offlineen .

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Presence.ReadWrite No disponible.
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Presence.ReadWrite.All No disponible.

Solicitud HTTP

POST /users/{userId}/presence/setPresence

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Type application/json. Obligatorio.

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione un objeto JSON con los siguientes parámetros.

Parámetro Tipo Descripción
sessionId string Identificador de la sesión de presencia de la aplicación.
disponibilidad string Información de presencia base.
actividad string Información complementaria a la disponibilidad.
expirationDuration duration Expiración de la sesión de presencia de la aplicación. El valor se representa en formato ISO 8601 para las duraciones.

Si no se proporciona, se aplicará una expiración predeterminada de 5 minutos.

Importante

Proporcione el identificador de la aplicación como sessionId en la solicitud.

Las combinaciones admitidas de availability y activity son:

disponibilidad actividad Descripción
Disponible Disponible Novedades la sesión de presencia como Disponible.
Ocupado InACall Novedades la sesión de presencia como Busy, InACall.
Ocupado InAConferenceCall Novedades la sesión de presencia como Busy, InAConferenceCall.
Lejos Lejos Novedades la sesión de presencia como Ausente.
Donotdisturb Presentando Novedades la sesión de presencia como DoNotDisturb, Presenting.

Respuesta

Si se ejecuta correctamente, este método devuelve un código de respuesta 200 OK.

Ejemplos

En la solicitud siguiente se muestra la aplicación con el identificador 22553876-f5ab-4529-bffb-cfe50aa89f87 que establece su sesión de presencia para el usuario fa8bf3dc-eca7-46b7-bad1-db199b62afc3.

Solicitud

POST https://graph.microsoft.com/beta/users/fa8bf3dc-eca7-46b7-bad1-db199b62afc3/presence/setPresence
Content-Type: application/json

{
  "sessionId": "22553876-f5ab-4529-bffb-cfe50aa89f87",
  "availability": "Available",
  "activity": "Available",
  "expirationDuration": "PT1H"
}

Respuesta

HTTP/1.1 200 OK