Desenvolver aplicativos multilocatário escalonáveis com inserção do Power BI

Este artigo descreve como desenvolver um aplicativo de multilocação que insira conteúdo do Power BI e, ao mesmo tempo, alcance os níveis mais altos de escalabilidade, desempenho e segurança. Ao projetar e implementar um aplicativo com perfis de entidade de serviço, você pode criar e gerenciar uma solução multilocatária composta por dezenas de milhares de locatários do cliente que podem fornecer relatórios para públicos de mais de 100 mil usuários.

Os perfis de entidade de serviço são recursos que facilitam o gerenciamento de conteúdo organizacional no Power BI e o uso das suas capacidades com mais eficiência. No entanto, o uso de perfis de entidade de serviço pode adicionar complexidade ao design do aplicativo. Portanto, você só deve usá-los quando houver a necessidade de alcançar uma escala significativa. É recomendável usar perfis de entidade de serviço quando você tiver muitos workspaces e mais de 1.000 usuários de aplicativos.

Observação

O valor do uso de perfis de entidade de serviço aumenta de acordo com o aumento da sua necessidade de escalar, bem como sua necessidade de alcançar os níveis mais altos de segurança e isolamento de locatário.

Você pode obter a inserção do Power BI usando dois cenários de inserção diferentes: Inserir para sua organização e Inserir para seu cliente.

O cenário Inserir para sua organização se aplica quando o público-alvo do aplicativo é composto por usuários internos. Os usuários internos têm contas organizacionais e devem se autenticar com a ID do Microsoft Entra. Nesse cenário, o Power BI é SaaS (software como serviço). Às vezes, esse cenário é chamado de Usuário proprietário dos dados.

O cenário Inserir para seu cliente se aplica quando o público-alvo do aplicativo é composto por usuários externos. O aplicativo é responsável por autenticar os usuários. Para acessar conteúdo do Power BI, o aplicativo depende de uma identidade de incorporação (entidade de serviço do Microsoft Entra ou conta de usuário mestre) para se autenticar no Microsoft Entra. Nesse cenário, o Power BI é uma PaaS (plataforma como serviço). Às vezes, esse cenário é chamado de Aplicativo proprietário dos dados.

Observação

É importante entender que o recurso de perfis de entidade de serviço foi projetado para uso com o cenário Inserir para o cliente. Isto porque esse cenário oferece aos ISVs e às organizações empresariais a capacidade de inserir com maior escala para um grande número de usuários e para um grande número de locatários do cliente.

Desenvolvimento de aplicativos de multilocação

Se você estiver familiarizado com o Microsoft Entra, a palavra locatário poderá levar você a pensar em um locatário do Microsoft Entra. No entanto, o conceito de um locatário é diferente no contexto da criação de uma solução de multilocação que insira conteúdo do Power BI. Nesse contexto, um locatário do cliente é criado em nome de cada cliente para o qual o aplicativo insere conteúdo do Power BI usando o cenário Inserir para o cliente. Normalmente, você provisiona cada locatário do cliente criando um único workspace do Power BI.

Para criar uma solução de multilocação escalonável, você precisa automatizar a criação de novos locatários do cliente. O provisionamento de um novo locatário do cliente normalmente envolve escrever código que usa a API REST do Power BI para criar um novo workspace do Power BI, criar modelos semânticos importando arquivos do Power BI Desktop (.pbix), atualizar parâmetros de fonte de dados, definir credenciais de fonte de dados e configurar a atualização de modelo semântico agendada. O diagrama a seguir mostra como você faz para adicionar itens do Power BI (como relatórios e modelos semânticos) a workspaces para configurar locatários do cliente.

Quando você desenvolve um aplicativo que usa o cenário Inserir para o cliente, é possível fazer chamadas à API REST do Power BI usando uma identidade de incorporação que seja uma conta de usuário mestre ou uma entidade de serviço. É recomendável usar uma entidade de serviço para aplicativos de produção. Ele fornece a maior segurança e, por esse motivo, é a abordagem recomendada pelo Microsoft Entra. Além disso, dá suporte a uma melhor automação e escala e há menos sobrecarga de gerenciamento. No entanto, ela requer direitos de administrador do Power BI para configurar e gerenciar.

Ao usar uma entidade de serviço, você pode evitar problemas comuns associados a contas de usuário mestre, como erros de autenticação em ambientes em que os usuários precisam entrar usando a MFA (autenticação multifator). O uso de uma entidade de serviço também é consistente com a ideia de que o cenário Inserção para o cliente se baseia na inserção de conteúdo do Power BI usando uma mentalidade de PaaS em vez de uma mentalidade de SaaS.

Limitação de 1.000 workspaces

Ao criar um ambiente multilocatário que implementa o cenário Inserção para o cliente, considere que a identidade de incorporação não pode receber acesso a mais de 1.000 workspaces. O serviço do Power BI impõe essa limitação para garantir um bom desempenho ao fazer chamadas à API REST. O motivo dessa limitação está relacionado a como o Power BI mantém metadados relacionados à segurança para cada identidade.

O Power BI usa metadados para rastrear os workspaces e os itens de workspace que uma identidade pode acessar. Na verdade, o Power BI deve manter uma ACL (lista de controle de acesso) separada para cada identidade em seu subsistema de autorização. Quando uma identidade faz uma chamada à API REST para acessar um workspace, o Power BI deve fazer uma verificação de segurança em relação à ACL da identidade para garantir que ela esteja autorizada. O tempo necessário para determinar se o workspace de destino está dentro da ACL aumenta exponencialmente à medida que o número de workspaces aumenta.

Observação

O Power BI não impõe a limitação de 1.000 workspaces por meio do código. Se tentar, você vai conseguir adicionar uma identidade incorporada a mais de 1.000 workspaces e as chamadas à API REST continuarão sendo executadas com êxito. No entanto, seu aplicativo passará para um estado sem suporte, o que poderá ter implicações caso você tente solicitar ajuda do suporte da Microsoft.

Considere um cenário em que dois aplicativos multilocatários foram configurados para usar uma única entidade de serviço. Agora considere que o primeiro aplicativo criou 990 workspaces, e o segundo aplicativo criou 1.010 workspaces. Do ponto de vista do suporte, o primeiro aplicativo está dentro dos limites com suporte, enquanto o segundo não está.

Agora, compare esses dois aplicativos puramente de uma perspectiva de desempenho. Não há muita diferença porque as ACLs de ambas as entidades de serviço deixaram os metadados de suas ACLs crescerem até um ponto em que isso prejudicará o desempenho em certa medida.

Este é o ponto principal: o número de workspaces criados por uma entidade de serviço tem um impacto direto no desempenho e na escalabilidade. Uma entidade de serviço que é membro de 100 workspaces executará chamadas à API REST mais rapidamente do que uma entidade de serviço que é membro de 1.000 workspaces. Da mesma forma, uma entidade de serviço que é membro de apenas 10 workspaces executará chamadas à API REST mais rapidamente do que uma entidade de serviço que é membro de 100 workspaces.

Importante

Da perspectiva do desempenho e da escalabilidade, o número ideal de workspaces para os quais uma entidade de serviço é membro é exatamente um.

Gerenciar o isolamento de modelos semânticos e credenciais da fonte de dados

Outro aspecto importante ao criar um aplicativo de multilocação é isolar os locatários do cliente. É fundamental que os usuários de um locatário do cliente não vejam dados que pertençam a outro locatário do cliente. Portanto, você precisa entender como gerenciar a propriedade do modelo semântico e as credenciais da fonte de dados.

Propriedade do modelo semântico

Cada modelo semântico do Power BI tem um único proprietário, que pode ser uma conta de usuário ou uma entidade de serviço. A propriedade do modelo semântico é necessária para configurar a atualização agendada e definir os parâmetros do modelo semântico.

Dica

No serviço do Power BI, você pode determinar quem é o proprietário do modelo semântico abrindo as configurações do modelo semântico.

Se necessário, você pode transferir a propriedade do modelo semântico para outra conta de usuário ou entidade de serviço. Você pode fazer isso no serviço do Power BI ou usando a operação TakeOver da API REST. Quando você importa um arquivo do Power BI Desktop para criar um modelo semântico usando uma entidade de serviço, a entidade de serviço é definida automaticamente como o proprietário do modelo semântico.

Credenciais da fonte de dados

Para conectar um modelo semântico à fonte de dados subjacente, o proprietário do modelo semântico precisa definir as credenciais da fonte de dados. As credenciais da fonte de dados são criptografadas e armazenadas em cache pelo Power BI. Depois, o Power BI usa essas credenciais para se autenticar na fonte de dados subjacente ao atualizar os dados (para importar tabelas de armazenamento) ou executar consultas de passagem (para tabelas de armazenamento do DirectQuery).

Recomendamos que você aplique um padrão de design comum ao provisionar um novo locatário do cliente. Você pode executar uma série de chamadas à API REST usando a identidade da entidade de serviço:

1. Criar um workspace.
2. Associar o novo workspace a uma capacidade dedicada.
3. Importar um arquivo do Power BI Desktop para criar um modelo semântico.
4. Defina as credenciais de origem do modelo semântico para esse modelo semântico.

Após a conclusão dessas chamadas à API REST, a entidade de serviço será uma administradora do novo workspace e a proprietária do modelo semântico e das credenciais da fonte de dados.

Importante

Há um equívoco comum de que as credenciais da fonte de dados do modelo semântico têm escopo no nível do workspace. Isso não é verdade. As credenciais da fonte de dados têm como escopo a entidade de serviço (ou a conta de usuário) e esse escopo se estende a todos os workspaces do Power BI no locatário do Microsoft Entra.

É possível que uma entidade de serviço crie credenciais de fonte de dados compartilhadas por modelos semânticos em diferentes workspaces entre locatários do cliente, conforme mostrado no diagrama a seguir.

Quando as credenciais da fonte de dados são compartilhadas por modelos semânticos que pertencem a locatários do cliente diferentes, os locatários não ficam totalmente isolados.

Estratégias de design anteriores aos perfis de entidade de serviço

Entender as estratégias de design anteriores à disponibilização do recurso de perfil da entidade de serviço poderá ajudar a avaliar a necessidade do recurso. Antes disso, os desenvolvedores criavam aplicativos de multilocação usando uma das seguintes três estratégias de design:

• Entidade de serviço única
• Pooling de entidade de serviço
• Uma entidade de serviço por workspace

Há pontos fortes e fracos associados a cada uma dessas estratégias de design.

A estratégia de design de entidade de serviço única requer a criação de um registro de aplicativo do Microsoft Entra uma única vez. Portanto, isso envolve menor sobrecarga administrativa do que as outras duas estratégias de design porque não há necessidade de criar mais registros de aplicativo do Microsoft Entra. Essa estratégia também é a mais simples de configurar porque não requer escrever código extra que mude o contexto da chamada entre as entidades de serviço ao fazer chamadas à API REST. No entanto, um problema com essa estratégia de design é que ela não escala. Ela só dá suporte a um ambiente de multilocação que pode crescer a até 1.000 workspaces. Além disso, o desempenho certamente será degradado, pois a entidade de serviço recebe acesso a um número maior de workspaces. Também há um problema com o isolamento do locatário do cliente porque a entidade de serviço única se torna a proprietária de todos os modelos semânticos e todas as credenciais de dados em todos os locatários do cliente.

A estratégia de design de pooling da entidade de serviço geralmente é usada para evitar a limitação de 1.000 workspaces. Ela permite que o aplicativo escale para qualquer número de workspaces adicionando o número correto de entidades de serviço ao pool. Por exemplo, um pool de cinco entidades de serviço possibilita escalar para até 5.000 workspaces; um pool de 80 entidades de serviço possibilita escalar para até 80.000 workspaces e assim por diante. No entanto, embora essa estratégia possa ser dimensionada para um grande número de workspaces, ela tem várias desvantagens. Primeiro, ela requer a escrita de código extra e o armazenamento de metadados para permitir a alternância de contexto entre entidades de serviço ao fazer chamadas à API REST. Em segundo lugar, envolve mais esforço administrativo porque você deve criar registros de aplicativo do Microsoft Entra sempre que precisar aumentar o número de entidades de serviço no pool.

Além disso, a estratégia de pooling da entidade de serviço não é otimizada para desempenho porque permite que as entidades de serviço se tornem membros de centenas de workspaces. Também não é ideal da perspectiva do isolamento do locatário do cliente porque as entidades de serviço podem se tornar proprietárias de modelo semântico e das credenciais de dados compartilhadas entre locatários do cliente.

A estratégia de design de uma entidade de serviço por workspace envolve a criação de uma entidade de serviço para cada locatário do cliente. De uma perspectiva teórica, essa estratégia oferece a melhor solução porque otimiza o desempenho de chamadas à API REST, fornecendo isolamento real para modelos semânticos e credenciais de fonte de dados no nível do workspace. No entanto, o que funciona melhor na teoria nem sempre funciona melhor na prática. Isso ocorre porque o requisito de criar uma entidade de serviço para cada locatário do cliente é impraticável para muitas organizações. Isso porque algumas organizações têm processos formais de aprovação ou envolvem burocracia excessiva para criar registros de aplicativo do Microsoft Entra. Esses motivos podem tornar impossível conceder a um aplicativo personalizado a autoridade necessária para criar registros de aplicativo do Microsoft Entra sob demanda e da maneira automatizada necessária para a solução.

Em cenários menos comuns em que um aplicativo personalizado recebeu as permissões adequadas, é possível usar a API do Microsoft Graph para criar registros de aplicativo do Microsoft Entra sob demanda. No entanto, o aplicativo personalizado geralmente é complexo para desenvolver e implantar, pois, de alguma forma, ele deve rastrear as credenciais de autenticação para cada registro de aplicativo do Microsoft Entra. Ele também deve obter acesso a essas credenciais sempre que precisar se autenticar e adquirir tokens de acesso para entidades de serviço individuais.

Perfil de entidade de serviço

O recurso de perfis de entidade de serviço foi projetado para facilitar o gerenciamento de conteúdo organizacional no Power BI e o uso das suas capacidades com mais eficiência. Eles ajudam a enfrentar três desafios específicos que envolvem a menor quantidade de esforço e sobrecarga para desenvolvedores. Esses desafios incluem:

• Dimensionamento para um grande número de workspaces.
• Otimização do desempenho de chamadas à API REST.
• Isolamento de modelos semânticos e credenciais de fonte de dados no nível do locatário do cliente.

Ao criar um aplicativo multilocatário usando perfis de entidade de serviço, você pode se beneficiar dos pontos fortes das três estratégias de design (descritas na seção anterior) evitando os pontos fracos associados.

Os perfis de entidade de serviço são contas locais criadas no contexto do Power BI. Uma entidade de serviço pode usar a operação da API REST Profiles para criar outros perfis de entidade de serviço. Uma entidade de serviço pode criar e gerenciar o próprio conjunto de perfis de entidade de serviço para um aplicativo personalizado, conforme mostrado no diagrama a seguir.

Há sempre uma relação pai-filho entre uma entidade de serviço e os perfis de entidade de serviço que ela cria. Você não pode criar um perfil de entidade de serviço como uma entidade autônoma. Em vez disso, você cria um perfil de entidade de serviço usando uma entidade de serviço específica e essa entidade de serviço serve como pai do perfil. Além disso, um perfil de entidade de serviço nunca fica visível para as contas de usuário ou outras entidades de serviço. Um perfil de entidade de serviço só pode ser visto e usado pela entidade de serviço que o criou.

Os perfis da entidade de serviço não são conhecidos pelo Microsoft Entra

Embora a própria entidade de serviço e seu registro de aplicativo do Microsoft Entra subjacente sejam conhecidos pelo Microsoft Entra, o Microsoft Entra ID não sabe nada sobre perfis da entidade de serviço. Isso ocorre porque os perfis de entidade de serviço são criados pelo Power BI e existem apenas no subsistema do serviço do Power BI que controla a segurança e a autorização do Power BI.

O facto de os perfis principais de serviço não serem conhecidos pelo Microsoft Entra ID tem vantagens e desvantagens. A principal vantagem é que um aplicativo do cenário Inserir para o cliente não precisa de permissões especiais do Microsoft Entra para criar perfis de entidade de serviço. Isso também significa que o aplicativo pode criar e gerenciar um conjunto de identidades locais separadas de Microsoft Entra.

No entanto, há desvantagens. Como os perfis da entidade de serviço não são conhecidos do Microsoft Entra, você não pode adicionar um perfil de entidade de serviço a um grupo do Microsoft Entra para conceder acesso implícito a um workspace. Além disso, fontes de dados externas, como um Banco de Dados SQL do Azure ou o Azure Synapse Analytics, não podem reconhecer perfis de entidade de serviço como a identidade ao se conectar a um banco de dados. Portanto, a estratégia de design de uma entidade de serviço por workspace (criar uma entidade de serviço para cada locatário do cliente) pode ser a melhor escolha quando há um requisito de se conectar a essas fontes de dados usando uma entidade de serviço separada com credenciais de autenticação exclusivas para cada locatário do cliente.

Os perfis de entidade de serviço são entidades de segurança de primeira classe

Embora os perfis de entidade de serviço não sejam conhecidos do Microsoft Entra, o Power BI os reconhece como entidades de segurança de primeira classe. Assim como uma conta de usuário ou uma entidade de serviço, você pode adicionar perfis de entidade de serviço a uma função de workspace (como um Administrador ou Membro). Você também pode torná-lo um proprietário do modelo semântico e o proprietário das credenciais da fonte de dados. Por esses motivos, criar um novo perfil de entidade de serviço para cada novo locatário do cliente é uma prática recomendada.

Dica

Ao desenvolver um aplicativo do cenário Inserir para o cliente usando perfis de entidade de serviço, você só precisa criar um registro de aplicativo do Microsoft Entra para fornecer ao aplicativo uma única entidade de serviço. Essa abordagem reduz significativamente a sobrecarga administrativa em comparação com outras estratégias de design de multilocação, nas quais é necessário criar mais registros de aplicativo do Microsoft Entra de forma contínua depois que o aplicativo é implantado na produção.

Executar chamadas à API REST como um perfil de entidade de serviço

Seu aplicativo pode executar chamadas à API REST usando a identidade de um perfil de entidade de serviço. Isso significa que ele pode executar uma sequência de chamadas à API REST para provisionar e configurar um novo locatário do cliente.

1. Quando um perfil de entidade de serviço cria um workspace, o Power BI adiciona automaticamente esse perfil como um administrador do workspace.
2. Quando um perfil de entidade de serviço importa um arquivo do Power BI Desktop para criar um modelo semântico, o Power BI define esse perfil como proprietário do modelo semântico.
3. Quando um perfil de entidade de serviço define as credenciais da fonte de dados, o Power BI define esse perfil como proprietário das credenciais da fonte de dados.

É importante entender que uma entidade de serviço tem uma identidade no Power BI separada e distinta das identidades de seus perfis. Isso lhe fornece opções como desenvolvedor. Você pode executar chamadas à API REST usando a identidade de um perfil de entidade de serviço. Como alternativa, você pode executar chamadas à API REST sem um perfil, que usa a identidade da entidade de serviço pai.

Recomendamos que você execute chamadas à API REST como a entidade de serviço pai ao criar, exibir ou excluir perfis de entidade de serviço. Você deve usar o perfil da entidade de serviço para executar todas as outras chamadas à API REST. Essas outras chamadas podem criar workspaces, importar arquivos do Power BI Desktop, atualizar parâmetros de modelo semântico e definir credenciais da fonte de dados. Eles também podem recuperar metadados de item do workspace e gerar tokens de inserção.

Considere um exemplo em que você precisa configurar um locatário do cliente para um cliente chamado Contoso. A primeira etapa faz uma chamada à API REST para criar um perfil de entidade de serviço com o nome de exibição definido como Contoso. Essa chamada é feita usando a identidade da entidade de serviço. As etapas restantes da configuração usam o perfil da entidade de serviço para realizar as seguintes tarefas:

1. Crie um workspace.
2. Associar o workspace a uma capacidade.
3. Importar um arquivo do Power BI Desktop.
4. Defina os parâmetros do modelo semântico.
5. Definir credenciais da fonte de dados.
6. Configurar a atualização de dados agendada.

É importante entender que o acesso ao workspace e seu conteúdo deve ser feito usando a identidade do perfil da entidade de serviço que foi usado para criar o locatário do cliente. Também é importante entender que a entidade de serviço pai não precisa de acesso ao workspace ou ao conteúdo.

Dica

Lembre-se: ao fazer chamadas à API REST, use a entidade de serviço para criar e gerenciar perfis de entidade de serviço e use o perfil da entidade de serviço para criar, configurar e acessar o conteúdo do Power BI.

Usar as operações Profiles da API REST

O grupo de operações Profiles da API REST compreende operações que criam e gerenciam perfis de entidade de serviço:

• Create Profile
• Delete Profile
• Get Profile
• Get Profiles
• Update Profile

Criar um perfil de entidade de serviço

Use a operação Create Profile da API REST para criar um perfil de entidade de serviço. Você deve definir a propriedade displayName no corpo da solicitação para fornecer um nome de exibição para o novo locatário. O valor deve ser exclusivo em todos os perfis pertencentes à entidade de serviço. A chamada falhará se outro perfil com esse nome de exibição já existir para a entidade de serviço.

Uma chamada bem-sucedida retorna a propriedade id, que é um GUID que representa o perfil. Ao desenvolver aplicativos que usam perfis de entidade de serviço, recomendamos que você armazene nomes de exibição de perfil e os respectivos valores de ID em um banco de dados personalizado. Dessa forma, seu aplicativo pode recuperar as IDs de maneira simples.

Se você estiver programando com o SDK do .NET do Power BI, use o método Profiles.CreateProfile, que retorna um objeto ServicePrincipalProfile que representa o novo perfil. Isso facilita a determinação do valor da propriedade id.

Aqui está um exemplo da criação de um perfil de entidade de serviço e a concessão de acesso ao workspace.

// Create a service principal profile
string profileName = "Contoso";

var createRequest = new CreateOrUpdateProfileRequest(profileName);
var profile = pbiClient.Profiles.CreateProfile(createRequest);

// Retrieve the ID of the new profile
Guid profileId = profile.Id;

// Grant workspace access
var groupUser = new GroupUser {
    GroupUserAccessRight = "Admin",
    PrincipalType = "App",
    Identifier = ServicePrincipalId,
    Profile = new ServicePrincipalProfile {
        Id = profileId
    }
};

pbiClient.Groups.AddGroupUser(workspaceId, groupUser);

No serviço do Power BI, no painel Acesso do workspace, você pode determinar quais identidades, incluindo entidades de segurança, têm acesso.

Excluir um perfil de entidade de serviço

Use a operação Delete Profile da API REST para excluir um perfil de entidade de serviço. Essa operação só pode ser chamada pela entidade de serviço pai.

Se você estiver programando com o SDK do .NET do Power BI, use o método Profiles.DeleteProfile.

Recuperar todos os perfis de entidade de serviço

Use a operação Get Profiles da API REST para recuperar uma lista de perfis de entidade de serviço que pertencem à entidade de serviço que faz a chamada. Essa operação retorna um conteúdo JSON que contém as propriedades id e displayName de cada perfil de entidade de serviço.

Se você estiver programando com o SDK do .NET do Power BI, use o método Profiles.GetProfiles.

Executar chamadas à API REST usando um perfil de entidade de serviço

Há dois requisitos para fazer chamadas à API REST usando um perfil de entidade de serviço:

• Você deve passar o token de acesso para a entidade de serviço pai no cabeçalho de Autorização.
• Você deve incluir um cabeçalho chamado X-PowerBI-profile-id com o valor da ID do perfil da entidade de serviço.

Se você estiver usando o SDK do .NET do Power BI, defina o valor do cabeçalho X-PowerBI-profile-id explicitamente passando a ID do perfil da entidade de serviço.

// Create the Power BI client
var tokenCredentials = new TokenCredentials(GetACcessToken(). "Bearer");
var uriPowerBiServiceApiRoot = new Uri(uriPowerBiServiceApiRoot);
var pbiClient = new PowerBIClient(uriPowerBiServiceApiRoot, tokenCredentials);

// Add X-PowerBI-profile-id header for service principal profile
string profileId = "11111111-1111-1111-1111-111111111111";
pbiClient.HttpClient.DefaultRequestHeaders.Add("X-PowerBI-profile-id", profileId);

// Retrieve workspaces by using the identity of service principal profile
var workspaces = pbiClient.Groups.GetGroups();

Conforme mostrado no exemplo acima, depois de adicionar o cabeçalho X-PowerBI-profile-id ao objeto PowerBIClient, fica fácil invocar métodos, como o Groups.GetGroups, para que eles sejam executados usando o perfil da entidade de serviço.

Há uma forma mais conveniente de definir o cabeçalho X-PowerBI-profile-id para um objeto PowerBIClient. Você pode inicializar o objeto passando a ID do perfil para o construtor.

// Create the Power BI client
string profileId = "11111111-1111-1111-1111-111111111111";

var tokenCredentials = new TokenCredentials(GetACcessToken(). "Bearer");
var uriPowerBiServiceApiRoot = new Uri(uriPowerBiServiceApiRoot);
var pbiClient = new PowerBiClient(uriPowerBiServiceApiRoot, tokenCredentials, profileId);

Ao programar um aplicativo de multilocação, é provável que você tenha que alternar entre executar chamadas como a entidade de serviço pai e executar chamadas como um perfil de entidade de serviço. Uma abordagem útil para gerenciar a alternância de contextos é declarar uma variável de nível de classe que armazena o objeto PowerBIClient. Em seguida, você pode criar um método auxiliar que define a variável com o objeto correto.

// Class-level variable that stores the PowerBIClient object
private PowerBIClient pbiClient;

// Helper method that sets the correct PowerBIClient object
private void SetCallingContext(string profileId = "") {

    if (profileId.Equals("")) {
        pbiClient = GetPowerBIClient();    
    }
    else {
        pbiClient = GetPowerBIClientForProfile(new Guid(profileId));
    }
}

Se precisar criar ou gerenciar um perfil de entidade de serviço, você pode chamar o método SetCallingContext sem parâmetros. Dessa forma, você pode criar e gerenciar perfis usando a identidade da entidade de serviço.

// Always create and manage profiles as the service principal
SetCallingContext();

// Create a service principal profile
string profileName = "Contoso";

var createRequest = new CreateOrUpdateProfileRequest(profileName);
var profile = pbiClient.Profiles.CreateProfile(createRequest);

Quando precisar criar e configurar um workspace para um novo locatário do cliente, é interessante executar esse código como um perfil de entidade de serviço. Portanto, você deve chamar o método SetCallingContext passando a ID do perfil. Dessa forma, você pode criar o workspace usando a identidade do perfil da entidade de serviço.

// Always create and set up workspaces as a service principal profile
string profileId = "11111111-1111-1111-1111-111111111111";
SetCallingContext(profileId);

// Create a workspace
GroupCreationRequest request = new GroupCreationRequest(workspaceName);
Group workspace = pbiClient.Groups.CreateGroup(request);

Depois de usar um perfil de entidade de serviço específico para criar e configurar um workspace, você deve continuar a usar esse mesmo perfil para criar e configurar o conteúdo do workspace. Não é necessário invocar o método SetCallingContext para concluir a instalação.

Exemplo de desenvolvedor

Incentivamos você a baixar um aplicativo de exemplo chamado AppOwnsDataMultiTenant.

Este aplicativo de exemplo foi desenvolvido usando o .NET 6 e o ASP.NET e demonstra como aplicar as diretrizes e recomendações descritas neste artigo. Você pode examinar o código para saber como desenvolver um aplicativo de multilocação que implementa o cenário Inserir para o cliente usando perfis de entidade de serviço.

Conteúdo relacionado

Para obter mais informações sobre este artigo, confira os seguintes recursos:

• Perfis de entidade de serviço para aplicativos multilocatário no Power BI Embedded
• Migrar aplicativos de vários clientes para o modelo de perfis de entidade de serviço
• Grupo de operações Profiles da API REST do Power BI
• • Aplicativo de exemplo AppOwnsDataMultiTenant
• Perguntas? Experimente perguntar à Comunidade do Power BI
• Sugestões? Contribuir com ideias para aprimorar o Power BI