Cumplimiento de licencias y capacidad de transacción (versión preliminar pública)

Al crear objetos visuales de Power BI para su descarga en AppSource, ahora puede administrar y aplicar sus licencias mediante sistemas de Microsoft. El usuario final asigna y administra licencias mediante herramientas conocidas como el Centro de administración de Microsoft 365, y la API de licencias le permite aplicar estas licencias y asegurarse de que solo los usuarios con licencia pueden representar los objetos visuales.

Proceso de cumplimiento de licencias

En la tabla siguiente se muestran los pasos necesarios para administrar las licencias de objeto visual desde Microsoft:

Paso	Detalles
Creación de una oferta en el Centro de partners	Elija realizar transacciones mediante el sistema de comercio de Microsoft. Habilite Microsoft para administrar licencias. Establezca los precios y la disponibilidad de las aplicaciones.
Adición del cumplimiento de licencias al paquete de objetos visuales de Power BI	Cree o vuelva a configurar el paquete para usar la licencia en tiempo de ejecución de Power BI, que exige licencias según el acceso de cada usuario.
Los clientes detectan la oferta en AppSource y compran una suscripción	Cuando los clientes compran la oferta en AppSource, también obtienen licencias para el objeto visual de Power BI.
Los clientes administran sus suscripciones y asignan o anulan la asignación de licencias de usuario	Los clientes administran suscripciones y asignan licencias para estos objetos visuales y ofertas en el Centro de administración de Microsoft 365, al igual que lo hacen para cualquiera de sus otras suscripciones, como Office o Power BI.
Aplicación de comprobaciones en tiempo de ejecución	Ofrezca a los clientes una experiencia uniforme mediante nuestras API de serie para aplicar comprobaciones de licencia en tiempo de ejecución.
Visualización de informes para impulsar el crecimiento	Obtenga conclusiones sobre los ingresos, la información de pagos y los detalles de pedidos y licencias. Vea información sobre licencias y pedidos comprados, renovados y cancelados en el tiempo y por geografía.

API de licencias

La API de licencias permite a los desarrolladores de objetos visuales de Power BI aplicar licencias de objetos visuales de Power BI. La API admite la recuperación de información sobre las licencias visuales de Power BI asignadas al usuario de Power BI. También permite desencadenar las notificaciones relacionadas con las licencias que aparecen en el objeto visual de Power BI e informar al usuario de que necesita comprar las licencias que faltan. El objeto visual no debe mostrar su propia experiencia de usuario de licencia, sino usar una de las notificaciones predefinidas admitidas por Power BI, tal como se detalla en las secciones siguientes.

Para más información sobre las licencias de Power BI, vea cumplimiento de licencias.

Nota

La API de licencias está disponible desde la versión 4.7. Para averiguar qué versión usa, compruebe apiVersion en el archivo pbiviz.json.

Recuperación de los planes de servicio del objeto visual asignados al usuario activo

Para obtener los planes de servicio asignados, agregue una llamada a getAvailableServicePlans (disponible desde IVisualLicenseManager). Desde la perspectiva del rendimiento, intente capturar las licencias una vez, preferiblemente en las llamadas a constructor o init, y guarde el resultado.
Una vez recuperadas las licencias, se almacenan en caché en el lado host de Power BI durante la sesión de Power BI y las llamadas adicionales a la misma devuelven los datos almacenados en caché.

export interface IVisualLicenseManager {
        getAvailableServicePlans(): IPromise<powerbi.extensibility.visual.LicenseInfoResult>;
    }

Recuperar las licencias puede ser una operación larga, por lo que la getAvailableServicePlans llamada es una llamada asincrónica y debe controlarse como tal en el código.
Como respuesta a la llamada al método, se devuelve el objeto LicenseInfoResult.

export interface LicenseInfoResult {
        plans: ServicePlan[] | undefined;
        isLicenseUnsupportedEnv: boolean; 
        isLicenseInfoAvailable: boolean; 
    }

• plans: matriz de planes de servicio comprados por el usuario activo para este objeto visual. (Las licencias comparadas para cualquier otro objeto visual no se incluyen en la respuesta).
  Un objeto ServicePlan contiene el identificador de servicio (spIdentifier) y su estado (ServicePlanState).

  • spIdentifier: el valor de cadena del identificador de servicio generado al configurar los planes de la oferta en el Centro de partners (vea el ejemplo siguiente)

  • state: enumeración (ServicePlanState) que representa el estado de los planes asignados.
    Estados de plan de servicio admitidos:

    State	Descripción
    Inactivo	Indica que la licencia no está activa y no se debe usar para las ventajas de aprovisionamiento.
    Activo	Indica que la licencia está activa y se puede usar para las ventajas de aprovisionamiento.
    Advertencia	Indica que la licencia está en período de gracia probablemente debido a una infracción de pago.
    Suspended	Indica que la licencia está suspendida probablemente debido a una infracción de pago.
    Unknown	Valor de Microsoft Sentinel.

    Solo los estados activos y advertencia representan una licencia utilizable. Todos los demás estados se deben tratar como la imposibilidad de una licencia utilizable.

• isLicenseUnsupportedEnv: indica que el objeto visual se representa en un entorno de Power BI que no admite la administración ni el cumplimiento de licencias. Actualmente, los siguientes entornos de Power BI no admiten la administración ni el cumplimiento de licencias:

  • Embedded: Publicar en web, inserción de PaaS
  • Nubes nacionales o regionales (según la compatibilidad general con la capacidad de transacción en nubes nacionales o regionales)
  • RS Server (sin compatibilidad planeada)
  • Exportación (PDF\PPT) mediante la API REST

• isLicenseInfoAvailable: indica si se puede recuperar la información de licencias. El error en la recuperación de licencias se puede producir en caso de que el usuario de Power BI Desktop no haya iniciado sesión o no esté conectado a Internet (sin conexión). Para la web, se puede producir un error en la recuperación de licencias debido a una interrupción temporal del servicio.

Ejemplo de llamada getAvailableServicePlans para recuperar los planes de servicio del usuario para este objeto visual:

private currentUserValidPlans: ServicePlan[] | undefined;
private hasServicePlans: boolean | undefined;
private isLicenseUnsupportedEnv: boolean | undefined;

this.licenseManager.getAvailableServicePlans()
 .then(({ plans, isLicenseUnsupportedEnv, isLicenseInfoAvailable }: LicenseInfoResult) => {
  if (isLicenseInfoAvailable && !isLicenseUnsupportedEnv) {
   this.currentUserValidPlans = plans?.filter(({ spIdentifier, state }) => 
    (state === powerbi.ServicePlanState.Active || state === powerbi.ServicePlanState.Warning)
   );
   this.hasServicePlans = !!currentUserValidPlans?.length;
  }
  this.isLicenseUnsupportedEnv = isLicenseUnsupportedEnv;
 }).catch((err) => {
  this.currentUserValidPlans = undefined;
  this.hasServicePlans = undefined;
  console.log(err);
 });

Nota:

En este ejemplo solo se muestra cómo comprobar si el usuario tiene planes válidos para este objeto visual. La plans matriz puede contener valores diferentes spIdentifier y cada identificador puede aparecer varias veces con estados diferentes.

Notificación al usuario de que faltan las licencias necesarias

La plataforma Power BI proporciona varias experiencias rápidas que se pueden usar para realizar notificaciones:

• Las licencias se deben comprar para disfrutar de las funcionalidades completas del objeto visual
• La característica de un objeto visual determinado está bloqueada debido a que faltan licencias
• Se bloquea todo el objeto visual debido a que faltan licencias
• Se bloquea todo el objeto visual porque el entorno de Power BI en uso no admite la administración o el cumplimiento de licencias

export interface IVisualLicenseManager {
        notifyLicenseRequired(notificationType: LicenseNotificationType): IPromise<boolean>;
        notifyFeatureBlocked(tooltip: string): IPromise<boolean>;
        clearLicenseNotification(): IPromise<boolean>;
    }

Ejemplo de llamada a notifyLicenseRequired:

private defaultNotificationType: powerbi.LicenseNotificationType = powerbi.LicenseNotificationType.General;
private isNotificaitonDisplayed: boolean = false;

if (!this.isNotificaitonDisplayed) {
    const notificationType = this.isLicenseUnsupportedEnv ? powerbi.LicenseNotificationType.UnsupportedEnv : this.defaultNotificationType
    this.licenseManager.notifyLicenseRequired(this.getNotificationType())
        .then((value) => {
            this.isNotificaitonDisplayed = value;
        }).catch((err) => {
            console.log(err);
        });
}

Icono general que indica que falta una licencia necesaria

Use la llamada a notifyLicenseRequired con LicenseNotificationType.General para mostrar un icono como parte del contenedor del objeto visual.
Una vez desencadenado, el icono se conserva durante toda la vigencia del objeto visual hasta clearLicenseNotification que se llama a o notifyLicenseRequired .

Nota:

La LicenseNotificationType.General notificación solo se aplica desde un entorno que admite la administración de licencias y para escenarios de edición de Power BI. Llamar a esto en un entorno no admitido o cuando el informe está en modo de lectura o en el panel no aplica el icono y devuelve false en la respuesta de la llamada.

Ejemplo de la presentación del objeto visual que contiene el icono general "Se requieren licencias":

Superposición de la presentación del objeto visual con una notificación de licencia que falta

Use la llamada a notifyLicenseRequired con LicenseNotificationType.VisualIsBlocked para superponer a la presentación del objeto visual una notificación de que el objeto visual está bloqueado porque faltan las licencias necesarias.
Una vez desencadenada, esta notificación se conserva durante toda la vigencia del objeto visual hasta clearLicenseNotification que se llama a o notifyLicenseRequired .

Ejemplo de la presentación visual que contiene la notificación de objeto visual bloqueado. Power BI Desktop solo muestra la opción Obtener una licencia :

Superponer a la presentación del objeto visual una notificación de entorno no compatible

Use la llamada notifyLicenseRequired con LicenseNotificationType.UnsupportedEnv para superponer a la presentación del objeto visual una notificación de que el objeto visual está bloqueado, ya que la instancia de Power BI en uso no admite la administración o el cumplimiento de licencias.
Una vez desencadenado, el icono se conserva durante toda la vigencia del objeto visual hasta clearLicenseNotification que se llama a o notifyLicenseRequired .

Nota:

La notificación LicenseNotificationType.UnsupportedEnv solo se aplica cuando se llama en el contexto de un entorno de licencias no admitido. Llamar a esto en cualquier otro entorno no aplica la notificación y devuelve false en la respuesta de la llamada.

Ejemplo de la presentación visual que contiene la notificación "Entorno no admitido":

Mostrar un banner que notifica que no se ha podido aplicar la funcionalidad de un objeto visual específico

Al aplicar la funcionalidad de un objeto visual específico, es necesario que falten licencias, puede usar la notifyFeatureBlocked llamada que muestra un banner emergente como parte del contenedor del objeto visual. El banner también admite una información sobre herramientas personalizada que puede establecer y usar para proporcionar información adicional sobre la característica que desencadenó la notificación.

Nota:

La característica se bloquea solo se aplica cuando se aplican las dos condiciones siguientes:

• Se llama desde un entorno de licencias admitido.
• No se aplican superposiciones de bloqueo (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked).

Llamar a esta notificación en un entorno no admitido no aplica la notificación y devuelve false en la respuesta de la llamada.

Nota:

Para admitir el entorno de Power BI localizado, se recomienda mantener las versiones localizadas de la información sobre herramientas en uso. Use Localization API para recuperar el idioma de configuración regional de Power BI.

Una vez desencadenado, el banner se muestra durante 10 segundos, o hasta que se desencadene otro banner de "característica bloqueada", o hasta clearLicenseNotification que se llame a (lo que ocurra primero).

Ejemplo de la presentación del objeto visual que contiene la notificación de banner "característica bloqueada":

Probar un objeto visual con licencia

Para probar un objeto visual con licencia de un extremo a otro antes de que esté disponible públicamente:

• Si va a crear una nueva oferta, agregue el objeto visual como un plan privado para una cuenta de cliente de prueba. La oferta solo es visible para esta cuenta de prueba para la compra. Use esta cuenta para validar la oferta antes de que sea pública.
• Si el objeto visual ya está disponible en AppSource y quiere actualizarlo a un objeto visual con licencia, no puede convertirlo en un plan privado porque oculta el objeto visual de AppSource y los usuarios existentes no tendrán acceso a él. Actualmente no hay ninguna manera de probar un objeto visual publicado de un extremo a otro. Pruébelo del mismo modo que probó el objeto visual original para AppSource, mediante la simulación del valor de la API de licencias para comprobar las distintas posibilidades.

Consideraciones y limitaciones

• La información sobre herramientas para el banner de características está limitada a 500 caracteres.
• La información sobre herramientas para el banner de características se debe localizar.
• Todavía no se admite la agrupación de licencias (es decir, una licencia que cubre varias ofertas del mismo publicador).

Contenido relacionado

Publicación de un objeto visual personalizado de Power BI

¿Tiene más preguntas? Pruebe a preguntar a la comunidad de Power BI