Cómo: Obtener datos de contexto

La getContext función recupera información contextual sobre la aplicación y el usuario que ha iniciado sesión. Esta información permite a las aplicaciones ofrecer experiencias personalizadas y tomar decisiones fundamentadas en tiempo de ejecución en función de los metadatos. La getContext función se comunica con el reproductor web para obtener datos de contexto. La getContext función es ligera y se centra en metadatos y propiedades relacionadas con la autenticación.

¿Por qué usar datos de contexto?

Los datos de contexto devueltos por la getContext función proporcionan detalles completos sobre la aplicación y el usuario, lo que permite escenarios que van más allá de la funcionalidad básica de la aplicación. Este es el motivo por el que importan estas propiedades:

• Telemetría y depuración mejoradas: los parámetros como sessionId permiten correlacionar sesiones de aplicaciones con telemetría de plataforma, lo que facilita la solución de problemas. El acceso a identificadores como IAppContext.appId e IUserContext.userPrincipalName ayuda a realizar un seguimiento de los patrones de uso y diagnosticar problemas rápidamente.

• Experiencias personalizadas: las propiedades de contexto de usuario simplifican la personalización sin necesidad de más llamadas de datos. Puede adaptar el comportamiento de la aplicación en función de la identidad del usuario, ofreciendo experiencias dinámicas para diferentes roles o individuos.

• Control de características y lógica condicional: los parámetros pueden actuar como puertas o marcas de características, lo que le permite activar o desactivar características para usuarios o entornos específicos. También se pueden usar para mostrar diferentes elementos de interfaz de usuario o flujos de trabajo en función del contexto.

• Coherencia con Canvas apps: estos parámetros se ajustan a los detalles de la sesión disponibles en Canvas apps, pero ahora puede usarlos directamente en el código, lo que ofrece más flexibilidad.

Pasos

1. Importe la getContext función .

   import { getContext } from '@microsoft/power-apps/app'; 
   

2. Recuperar el contexto.

   Llame getContext a como una función asincrónica para obtener el objeto de contexto.

   const ctx = await getContext();
   
   // Now you can access these context properties
   const appId = ctx.app.appId;
   const environmentId = ctx.app.environmentId;
   const queryParams = ctx.app.queryParams;
   const dataverseOrgUrl = ctx.app.dataverseOrgUrl;
   const appUrl = ctx.app.appUrl;
   const fullName = ctx.user.fullName;
   const objectId = ctx.user.objectId;
   const systemUserId = ctx.user.systemUserId;
   const tenantId = ctx.user.tenantId;
   const userPrincipalName = ctx.user.userPrincipalName;
   const sessionId = ctx.host.sessionId;
   

Obtención del identificador de Dataverse del usuario actual

Usa ctx.user.systemUserId para obtener el identificador de la fila del systemuser usuario actual en el entorno vinculado de Dataverse de la aplicación sin una consulta independiente. Este valor difiere de ctx.user.objectId, que identifica al usuario en Microsoft Entra ID. Use systemUserId cuando necesite hacer referencia a la fila de Dataverse del usuario.

Respuesta de la API

El contexto que se devuelve implementa la IContext interfaz.

IContext

En la tabla siguiente se describen las propiedades disponibles en la IContext interfaz:

Propiedad	Tipo	Description
app	IAppContext	Contexto de la aplicación
user	IUserContext	Contexto del usuario
host	IHostContext	Contexto del host

IAppContext

En la tabla siguiente se describen las propiedades disponibles en la IAppContext interfaz:

Propiedad	Tipo	Description
appId	cuerda / cadena	El identificador de la aplicación que se está reproducendo
environmentId	cuerda / cadena	Identificador del entorno en el que reside la aplicación
queryParams	Cadena de registro<, cadena>	Parámetros de consulta agregados a la dirección URL
dataverseOrgUrl	cuerda / cadena	Dirección URL del dataverse del entorno donde reside la aplicación.
appUrl	cuerda / cadena	Dirección URL de la aplicación.

IUserContext

En la tabla siguiente se describen las propiedades disponibles en la IUserContext interfaz:

Propiedad	Tipo	Description
fullName	cuerda / cadena	Nombre completo del usuario que utiliza la aplicación
objectId	cuerda / cadena	Identificador de objeto Microsoft Entra del usuario que usa la aplicación.
systemUserId	cadena (opcional)	Identificador de la fila del usuario actual systemuser en el entorno vinculado de Dataverse. La propiedad se puede omitir o estar vacía cuando no está disponible.
tenantId	cuerda / cadena	Identificador del inquilino donde reside la aplicación
userPrincipalName	cuerda / cadena	El nombre principal de usuario (UPN) del usuario que está utilizando la aplicación

IHostContext

En la tabla siguiente se describe la propiedad disponible en la IHostContext interfaz :

Propiedad	Tipo	Description
sessionId	cuerda / cadena	Identificador de la sesión actual. Este valor cambia cada vez que se abre la aplicación.