Desenvolva aplicativos escaláveis de multilocação com a incorporação do Power BI

Este artigo descreve como desenvolver um aplicativo de multilocação que incorpora conteúdo do Power BI e, ao mesmo tempo, alcança os mais altos níveis 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 de multilocação composta por dezenas de milhares de locatários de clientes que podem entregar relatórios para públicos de mais de 100.000 usuários.

Os perfis de entidade de serviço são um recurso que facilita o gerenciamento de conteúdo organizacional no Power BI e o uso de 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 necessidade de alcançar uma escala significativa. Recomendamos o uso de perfis de entidade de serviço quando você tiver muitos espaços de trabalho e mais de 1.000 usuários de aplicativos.

Nota

O valor do uso de perfis de entidade de serviço aumenta à medida que sua necessidade de dimensionamento aumenta, bem como sua necessidade de alcançar os mais altos níveis de segurança e isolamento de locatário.

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

O cenário Incorporar para sua organização se aplica quando o público do aplicativo é composto por usuários internos . Os usuários internos têm contas organizacionais e devem se autenticar com o Microsoft Entra ID (anteriormente conhecido como Azure Ative Directory). Nesse cenário, o Power BI é software como serviço (SaaS). Às vezes, é chamado de dados de propriedade do usuário.

O cenário Incorporar para seu cliente se aplica quando o público do aplicativo é composto por usuários externos . O aplicativo é responsável por autenticar os usuários. Para acessar o 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 autenticar com o Microsoft Entra. Nesse cenário, o Power BI é plataforma como serviço (PaaS). Às vezes, é chamado de aplicativo possui dados.

Nota

É importante entender que o recurso de perfis da entidade de serviço foi projetado para uso com o cenário Incorporar para seu cliente . Isso porque esse cenário oferece aos ISVs e organizações empresariais a capacidade de incorporar com maior escala a um grande número de usuários e a um grande número de locatários de clientes.

Desenvolvimento de aplicações de multilocação

Se você estiver familiarizado com o Microsoft Entra, a palavra locatário pode levá-lo a pensar em um locatário do Microsoft Entra. No entanto, o conceito de locatário é diferente no contexto da criação de uma solução de multilocação que incorpora conteúdo do Power BI. Nesse contexto, um locatário de cliente é criado em nome de cada cliente para o qual o aplicativo incorpora conteúdo do Power BI usando o cenário Incorporar para seu cliente . Normalmente, você provisiona cada locatário do cliente criando um único espaço de trabalho do Power BI.

Para criar uma solução escalável de multilocação, você deve ser capaz de automatizar a criação de novos locatários de clientes. O provisionamento de um novo locatário de cliente normalmente envolve escrever código que usa a API REST do Power BI para criar um novo espaço de trabalho do Power BI, criar modelos semânticos (anteriormente conhecidos como conjuntos de dados) importando arquivos do Power BI Desktop (.pbix), atualizar parâmetros da fonte de dados, definir credenciais da fonte de dados e configurar a atualização agendada do modelo semântico. O diagrama a seguir mostra como você pode adicionar itens do Power BI, como relatórios e modelos semânticos, a espaços de trabalho para configurar locatários de clientes.

Quando você desenvolve um aplicativo que usa a incorporação para o cenário do cliente , é possível fazer chamadas de 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. Recomendamos o uso de uma entidade de serviço para aplicativos de produção. Ele fornece a mais alta segurança e, por esse motivo, é a abordagem recomendada pelo Microsoft Entra. Além disso, suporta melhor automação e escala e há menos sobrecarga de gerenciamento. No entanto, ele requer direitos de administrador do Power BI para configurar e gerenciar.

Usando uma entidade de serviço, você pode evitar problemas comuns associados a contas de usuário mestre, como erros de autenticação em ambientes onde os usuários precisam entrar usando a autenticação multifator (MFA). Usar uma entidade de serviço também é consistente com a ideia de que o cenário Incorporar para seu cliente é baseado na incorporação de conteúdo do Power BI usando uma mentalidade PaaS em vez de uma mentalidade SaaS.

Limitação de 1.000 espaços de trabalho

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

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

Nota

O Power BI não impõe a limitação de 1.000 espaços de trabalho por meio de código. Se você tentar, adicionará uma identidade de incorporação a mais de 1.000 espaços de trabalho e as chamadas à API REST ainda serão executadas com êxito. No entanto, seu aplicativo será movido para um estado sem suporte , o que pode ter implicações se você tentar 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 espaços de trabalho, enquanto o segundo aplicativo criou 1.010 espaços de trabalho. De uma perspetiva de suporte, o primeiro aplicativo está dentro dos limites suportados, enquanto o segundo aplicativo não está.

Agora, compare esses dois aplicativos puramente de uma perspetiva de desempenho. Não há muita diferença porque as ACLs de ambas as entidades de serviço permitiram que os metadados de suas ACLs crescessem até um ponto em que degradariam o desempenho em algum grau.

Aqui está a principal observação: O número de espaços de trabalho criados por uma entidade de serviço tem um impacto direto no desempenho e na escalabilidade. Uma entidade de serviço que seja membro de 100 espaços de trabalho executará chamadas de API REST mais rapidamente do que uma entidade de serviço que seja membro de 1.000 espaços de trabalho. Da mesma forma, uma entidade de serviço que seja membro de apenas 10 espaços de trabalho executará chamadas de API REST mais rapidamente do que uma entidade de serviço que seja membro de 100 espaços de trabalho.

Importante

Do ponto de vista do desempenho e da escalabilidade, o número ideal de espaços de trabalho dos quais uma entidade de serviço é membro é exatamente um.

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

Outro aspeto importante ao projetar um aplicativo de multilocação é isolar os locatários do cliente. É fundamental que os usuários de um locatário de cliente não vejam dados que pertencem a outro locatário de cliente. Portanto, você deve 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 parâmetros do modelo semântico.

Gorjeta

No serviço 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 da API TakeOver REST. Quando você importa um arquivo do Power BI Desktop para criar um novo 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 origem de dados

Para conectar um modelo semântico à sua fonte de dados subjacente, o proprietário do modelo semântico deve definir as credenciais da fonte de dados. As credenciais da fonte de dados são criptografadas e armazenadas em cache pelo Power BI. A partir desse ponto, o Power BI usa essas credenciais para autenticar com a fonte de dados subjacente ao atualizar os dados (para importar tabelas de armazenamento) ou executar consultas de passagem (para tabelas de armazenamento 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 de API REST usando a identidade da entidade de serviço:

1. Crie uma nova área de trabalho.
2. Associe o novo espaço de trabalho a uma capacidade dedicada.
3. Importe 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 de API REST, a entidade de serviço será um administrador do novo espaço de trabalho e o proprietário 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 espaço de trabalho. Isso não é verdade. As credenciais da fonte de dados têm como escopo a entidade de serviço (ou conta de usuário) e esse escopo se estende a todos os espaços de trabalho do Power BI no locatário do Microsoft Entra.

É possível para uma entidade de serviço criar credenciais de fonte de dados que são compartilhadas por modelos semânticos em diferentes espaços de trabalho entre locatários clientes, conforme mostrado no diagrama a seguir.

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

Projetar estratégias antes dos perfis da entidade de serviço

Compreender as estratégias de design antes que o recurso de perfil da entidade de serviço esteja disponível pode ajudá-lo a avaliar a necessidade do recurso. Antes disso, os desenvolvedores criavam aplicativos de multilocação usando uma das três estratégias de design a seguir:

• Entidade de serviço única
• Agrupamento de entidades de serviço
• Uma entidade de serviço por espaço de trabalho

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 uma criação única de um registro de aplicativo Microsoft Entra. Portanto, envolve menos sobrecarga administrativa do que as outras duas estratégias de design, porque não há necessidade de criar mais registros de aplicativos do Microsoft Entra. Essa estratégia também é a mais simples de configurar porque não requer a escrita de código extra que alterna o contexto de chamada entre entidades de serviço ao fazer chamadas de API REST. No entanto, um problema com essa estratégia de design é que ela não é dimensionada. Ele suporta apenas um ambiente de multilocação que pode crescer até 1.000 espaços de trabalho. Além disso, o desempenho certamente diminuirá à medida que a entidade de serviço tiver acesso a um número maior de espaços de trabalho. Há também um problema com o isolamento do locatário do cliente porque a entidade de serviço única se torna proprietária de todos os modelos semânticos e de todas as credenciais de dados em todos os locatários do cliente.

A estratégia de design de pool de entidade de serviço é comumente usada para evitar a limitação de 1.000 espaços de trabalho. Ele permite que o aplicativo seja dimensionado para qualquer número de espaços de trabalho, adicionando o número correto de entidades de serviço ao pool. Por exemplo, um pool de cinco entidades de serviço torna possível dimensionar até 5.000 espaços de trabalho; Um pool de 80 entidades de serviço torna possível dimensionar até 80.000 espaços de trabalho e assim por diante. No entanto, embora essa estratégia possa ser dimensionada para um grande número de espaços de trabalho, ela tem várias desvantagens. Primeiro, ele requer escrever código extra e armazenar metadados para permitir a alternância de contexto entre entidades de serviço ao fazer chamadas de API REST. Em segundo lugar, envolve mais esforço administrativo porque você deve criar registros de aplicativo Microsoft Entra sempre que precisar aumentar o número de entidades de serviço no pool.

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

A estratégia de design de uma entidade de serviço por espaço de trabalho envolve a criação de uma entidade de serviço para cada locatário do cliente. De uma perspetiva teórica, essa estratégia oferece a melhor solução porque otimiza o desempenho de chamadas de API REST enquanto fornece isolamento verdadeiro para modelos semânticos e credenciais de fonte de dados no nível do espaço de trabalho. No entanto, o que funciona melhor na teoria nem sempre funciona melhor na prática. Isso 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 aplicativos Microsoft Entra. Esses motivos podem tornar impossível conceder a um aplicativo personalizado a autoridade necessária para criar registros de aplicativos Microsoft Entra sob demanda e da maneira automatizada que sua solução exige.

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

Perfis da entidade de serviço

O recurso de perfis da entidade de serviço foi projetado para facilitar o gerenciamento de conteúdo organizacional no Power BI e usar 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 do desenvolvedor. Estes desafios incluem:

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

Ao projetar um aplicativo de multilocação 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 seus pontos fracos associados.

Os perfis da 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 Profiles API REST para criar novos perfis de entidade de serviço. Uma entidade de serviço pode criar e gerenciar seu 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. Não é possível 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 é visível para 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 entidade de serviço em si e seu registro de aplicativo Microsoft Entra subjacente sejam conhecidos pelo Microsoft Entra, a ID do Microsoft Entra não sabe nada sobre perfis de entidade de serviço. Isso ocorre porque os perfis da entidade de serviço são criados pelo Power BI e existem apenas no subsistema de serviço do Power BI que controla a segurança e a autorização do Power BI.

O facto de os perfis da entidade de serviço não serem conhecidos pelo Microsoft Entra ID tem vantagens e desvantagens. A principal vantagem é que um aplicativo de cenário Embed for your customer não precisa de nenhuma permissão especial 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 que são separadas do Microsoft Entra.

No entanto, também existem desvantagens. Como os perfis da entidade de serviço não são conhecidos pelo Microsoft Entra, não é possível adicionar um perfil da entidade de serviço a um grupo do Microsoft Entra para conceder-lhe implicitamente acesso a um espaço de trabalho. 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 espaço de trabalho (criando uma entidade de serviço para cada locatário do cliente) pode ser uma escolha melhor quando há um requisito para 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 da entidade de serviço são entidades de segurança de primeira classe

Embora os perfis da entidade de serviço não sejam conhecidos pelo Microsoft Entra, o Power BI reconhece-os 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 espaço de trabalho (como Administrador ou Membro). Você também pode torná-lo um proprietário de modelo semântico e o proprietário de credenciais de fonte de dados. Por esses motivos, a criação de um novo perfil de entidade de serviço para cada novo locatário do cliente é uma prática recomendada.

Gorjeta

Ao desenvolver um aplicativo de cenário Incorporar para seu cliente usando perfis de entidade de serviço, você só precisa criar um único registro de aplicativo Microsoft Entra para fornecer seu aplicativo com 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, onde é necessário criar registros adicionais de aplicativos Microsoft Entra continuamente depois que o aplicativo é implantado na produção.

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

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

1. Quando um perfil de entidade de serviço cria um novo espaço de trabalho, o Power BI adiciona automaticamente esse perfil como administrador de espaço de trabalho.
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 o proprietário do modelo semântico.
3. Quando um perfil de entidade de serviço define credenciais de fonte de dados, o Power BI define esse perfil como o 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 dá a escolha como desenvolvedor. Você pode executar chamadas de API REST usando a identidade de um perfil de entidade de serviço. Como alternativa, você pode executar chamadas de API REST sem um perfil, que usa a identidade da entidade de serviço pai.

Recomendamos que você execute chamadas de 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 de API REST. Essas outras chamadas podem criar espaços de trabalho, importar arquivos do Power BI Desktop, atualizar parâmetros de modelo semântico e definir credenciais de fonte de dados. Eles também podem recuperar metadados de item de espaço de trabalho e gerar tokens de incorporação.

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

1. Crie um espaço de trabalho.
2. Associe o espaço de trabalho a uma capacidade.
3. Importe um arquivo do Power BI Desktop.
4. Defina parâmetros de modelo semântico.
5. Defina credenciais de fonte de dados.
6. Configure a atualização de dados agendada.

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

Gorjeta

Lembre-se: ao fazer chamadas de 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 conteúdo do Power BI.

Usar as operações da API REST de perfis

O grupo de operações da API REST de perfis 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 Criar API REST de perfil para criar um perfil de entidade de serviço. Você deve definir a displayName propriedade no corpo da solicitação para fornecer um nome para 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 já existir outro perfil com esse nome de exibição para a entidade de serviço.

Uma chamada bem-sucedida retorna a id propriedade, 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 seus valores de ID em um banco de dados personalizado. Dessa forma, é simples para seu aplicativo recuperar os IDs.

Se você estiver programando com o SDK do Power BI .NET, poderá usar o Profiles.CreateProfile método, que retorna um ServicePrincipalProfile objeto que representa o novo perfil. Torna simples determinar o valor da id propriedade.

Veja um exemplo de como criar um perfil de entidade de serviço e conceder-lhe acesso ao espaço de trabalho.

// 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 ao espaço de trabalho, você pode determinar quais identidades, incluindo entidades de segurança, têm acesso.

Excluir um perfil da entidade de serviço

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

Se você estiver programando com o Power BI .NET SDK, poderá usar o Profiles.DeleteProfile método.

Recuperar todos os perfis da entidade de serviço

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

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

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

Há dois requisitos para fazer chamadas de 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 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 Power BI .NET, poderá definir 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();

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

Há uma maneira mais conveniente de definir o cabeçalho X-PowerBI-profile-id para um PowerBIClient objeto. 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ê precise alternar entre a execução de chamadas como a entidade de serviço pai e a execução de chamadas como um perfil de entidade de serviço. Uma abordagem útil para gerenciar a alternância de contexto é declarar uma variável de nível de classe que armazena o PowerBIClient objeto. 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));
    }
}

Quando você precisa criar ou gerenciar um perfil de entidade de serviço, você pode chamar o SetCallingContext método sem quaisquer 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 espaço de trabalho para um novo locatário cliente, você deseja executar esse código como um perfil de entidade de serviço. Portanto, você deve chamar o SetCallingContext método passando o ID do perfil. Dessa forma, você pode criar o espaço de trabalho 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 espaço de trabalho, você deve continuar a usar esse mesmo perfil para criar e configurar o conteúdo do espaço de trabalho. Não há necessidade de invocar o SetCallingContext método para concluir a configuração.

Exemplo de desenvolvedor

Recomendamos que você baixe um aplicativo de exemplo chamado AppOwnsDataMultiTenant.

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

Conteúdos relacionados

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

• Perfis de entidade de serviço para aplicativos de multilocação no Power BI Embedded
• Migrar aplicativos multicliente para o modelo de perfis da entidade de serviço
• Perfis Power BI REST API grupo de operação
• • Aplicativo de exemplo AppOwnsDataMultiTenant
• Perguntas? Tente perguntar à Comunidade do Power BI
• Sugestões? Contribua com ideias para melhorar o Power BI