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

  • Artículo

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 aparecerán 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 compatibles con Power BI, como se detalla a continuación.

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 que se recuperen las licencias, se almacenarán en caché en el lado host de Power BI durante la sesión de Power BI y cualquier otra llamada a la misma devolverá los datos almacenados en caché.

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

La recuperación de las licencias puede ser una operación larga, por lo que la llamada a getAvailableServicePlans es asincrónica y se debe controlar 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) Screenshot showing an example of a Service ID string.

    • 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.
      Desconocido Valor de 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 a getAvailableServicePlans (con el identificador de servicio de la imagen anterior):

this.licenseManager.getAvailableServicePlans().then((result: LicenseInfoResult) => {
            this.notificationType = result.isLicenseUnsupportedEnv ?  powerbi.LicenseNotificationType.UnsupportedEnv : powerbi.LicenseNotificationType.General;
            this.hasServicePlans = !!(result.plans && result.plans.length && result.plans[0].spIdentifier == "test_isvconnect1599092224747.powerbivisualtransact.plan1" && 
                ( result.plans[0].state == powerbi.ServicePlanState.Active ||  result.plans[0].state == powerbi.ServicePlanState.Warning));
            
            // display notification if the user doesn't have licenses
            if (!this.hasServicePlans) {
                this.licenseManager.notifyLicenseRequired(this.notificationType).then((value) => {
                    if (value) {
                        this.isIconDisplayed = true;
                    }
                }).catch((err) => {
                    console.log('ERROR', err);
                })
            }
        }).catch((err) => {
            this.hasServicePlans = undefined;
            console.log(err);
        });

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

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 que se desencadene, el icono se conservará durante toda la duración del objeto visual hasta que se llame a clearLicenseNotification o notifyLicenseRequired.

Nota

La notificación LicenseNotificationType.General solo se aplica cuando ambas se aplican: compatibles con el entorno de licencias y los escenarios de edición de Power BI. Si se llama a esto en un entorno no compatible o cuando el informe está en modo de lectura o en el panel, el icono no se aplicará y se devolverá false en la respuesta de la llamada.

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

visual display containing the

visual display containing the

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 que se desencadene, esta notificación se conservará durante toda la duración del objeto visual hasta que se llame a clearLicenseNotification o notifyLicenseRequired.

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

Visual display containing the *visual blocked* notification.

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 que se desencadene, el icono se conservará durante toda la duración del objeto visual hasta que se llame a clearLicenseNotification o notifyLicenseRequired.

Nota

La notificación LicenseNotificationType.UnsupportedEnv solo se aplica cuando se llama en el contexto de un entorno de licencias no admitido. Al realizar la llamada en cualquier otro entorno, la notificación no se aplicará y devolverá false en la respuesta de la llamada.

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

visual display containing the

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

Cuando para aplicar la funcionalidad de un objeto visual específico se necesitan licencias que faltan, puede usar la llamada a notifyFeatureBlocked, que mostrará un banner como parte del contenedor del objeto visual. El banner también admite una información sobre herramientas personalizada que se puede establecer y usar para proporcionar información adicional sobre la característica que ha desencadenado la notificación.

Nota

La notificación de característica bloqueada solo se aplica cuando se llama en el contexto admitido para el entorno de licencias y en caso de que no se apliquen superposiciones de bloqueo (LicenseNotificationType.UnsupportedEnv, LicenseNotificationType.VisualIsBlocked). Al llamar a esta notificación en un entorno no admitido, no se aplicará y devolverá 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 que se desencadena, el banner se mostrará durante 10 segundos, o bien hasta que se desencadene otro banner de "característica bloqueada", o bien hasta que se llame a clearLicenseNotification (lo que ocurra primero).

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

visual display containing the

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 será visible para esta cuenta de prueba para comprar. 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 ocultará 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.
  • La agrupación de licencias (es decir, una licencia que cubre varias ofertas del mismo publicador) aún no se admite.

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