Incorporar para sua organização

Há duas maneiras de incorporar um Icon Map, e elas atendem a públicos diferentes.

Incorporar mapas trata da primeira: um mapa publicado, congelado e servido a visualizadores que não têm nenhum acesso ao Fabric. Esta página trata da segunda: um mapa ao vivo dentro do seu próprio aplicativo interno, em que cada visualizador entra com a própria identidade.

Se você conhece a inserção do Power BI, esses são os mesmos dois modelos: "inserir para seus clientes" e "inserir para sua organização".

O que é

O mapa é incorporado no seu aplicativo, e a identidade do Microsoft Entra de cada visualizador é usada para ler os dados. Isso significa que:

• Os visualizadores veem somente os dados que suas próprias permissões do Fabric permitem, e a segurança em nível de linha é aplicada automaticamente: a mesma RLS que seus modelos do Fabric e do Power BI já impõem. Não há nada a configurar no Icon Map.
• Os dados são ao vivo, lidos no momento em que o visualizador abre o mapa, e não um instantâneo.
• Não há entidade de serviço de leitura nem cópia publicada. O Icon Map nunca consegue acessar nada que o visualizador já não pudesse abrir por conta própria.

O mapa é somente para visualização: os visualizadores podem explorar, filtrar, usar indicadores e preencher formulários de write-back, mas não há criação nem acesso ao editor.

Quando usar cada modo

Não há licença por usuário com que se preocupar: o Fabric é cobrado pela capacidade, então o público é simplesmente o conjunto de pessoas do seu diretório que têm permissão para ver os dados subjacentes.

Este modo não pode ser usado para compartilhamento público. Todo visualizador entra com sua conta, então não existe link anônimo.

O que você precisa

• Um Icon Map criado com o workload do Icon Map em um workspace do Fabric, em uma capacidade do Fabric (F ou de avaliação).
• Visualizadores com permissão do Fabric para o item de mapa e para os dados por trás dele, concedida da forma habitual, compartilhando o item ou o workspace.
• Um aplicativo do Entra que possa emitir os tokens com os quais o mapa lê os dados. Qual aplicativo depende de como você trata a entrada:
  • Seu aplicativo fornece o token (a escolha habitual): é usado o seu próprio aplicativo do Entra, e o aplicativo visualizador do Icon Map não participa de forma alguma. Seu aplicativo precisa destas permissões delegadas consentidas no seu locatário: Azure Storage user_impersonation, Fabric/Power BI Workspace.Read.All, Item.Read.All e Dataset.Read.All, e Azure Data Explorer user_impersonation se o mapa ler um Eventhouse.
  • O mapa faz a entrada do visualizador: um consentimento do administrador único para o aplicativo Icon Map Embed Viewer no seu locatário.

Adicionar ao seu aplicativo

Incorpore o mapa com o SDK JavaScript do Icon Map. Aponte-o para o item de mapa e informe como obter um token:

<div id="map" style="height: 600px"></div>

<script type="module">
  import { embedForOrganization } from "@iconmap/embed";

  embedForOrganization(document.getElementById("map"), {
    mapItem: {
      workspaceId: "00000000-0000-0000-0000-000000000000",
      itemId: "00000000-0000-0000-0000-000000000000",
    },
    // Your application already signed this user in - hand over a token for
    // the scopes the map asks for.
    getToken: (scopes) =>
      msalInstance
        .acquireTokenSilent({ scopes, account })
        .then((result) => result.accessToken),
    onError: (error) => console.error(error),
  });
</script>

Você encontra as IDs do workspace e do item na URL do mapa no Fabric.

Duas maneiras de tratar a entrada

Seu aplicativo fornece o token (o exemplo acima e a escolha habitual). Seus usuários entram uma vez, no seu aplicativo, e o mapa reutiliza essa sessão. Nada mais aparece para eles.

O mapa pede um token para o recurso que está prestes a ler (seu armazenamento do OneLake, a API do Fabric, um cluster do Eventhouse), então retorne um token para os scopes recebidos, e não um único token fixo.

Como os tokens vêm do seu aplicativo do Entra, o aplicativo visualizador do próprio Icon Map nunca é usado nesse arranjo e não precisa de consentimento.

O mapa faz a entrada do visualizador. Omita getToken e o mapa cuida da entrada por conta própria, mostrando um botão de entrada na primeira vez. É o mais simples de encaixar, mas seus usuários entrarão duas vezes: uma no seu aplicativo e outra no mapa.

Controlar a sessão

const handle = embedForOrganization(element, options);

handle.signOut();  // drop the viewer's session and cached tokens
handle.reload();   // re-read the map as the viewer
handle.destroy();  // remove the map from the page

Segurança

• Privilégio mínimo por construção. Não há identidade do fornecedor no caminho dos dados. Um visualizador só pode ver o que já tem permissão para ver, e um visualizador que perde o acesso aos dados deixa de vê-los imediatamente, sem nova publicação.
• A segurança em nível de linha é do Fabric, não nossa. Nada da sua RLS precisa ser redefinido no Icon Map, então não há nada que possa ficar dessincronizado.
• Nada é copiado. Não existe em lugar nenhum um instantâneo congelado dos seus dados.
• O único risco residual é o habitual para esse modelo: um token de acesso roubado funciona até expirar. Os tokens têm vida curta, exatamente como no modo equivalente do Power BI.

Mais detalhes no white paper de segurança.

Pontos importantes

• Visualizadores convidados (B2B) funcionam na medida em que o Fabric lhes concede acesso aos dados. O Icon Map não pode ampliar cenários de convidados entre locatários.
• Mapas criados com uma compilação de desenvolvimento do workload não podem ser incorporados dessa forma. Use mapas criados com o workload do Icon Map publicado.
• A capacidade do workspace do mapa precisa estar em execução: uma capacidade pausada significa ausência de dados para todos.

Próximas etapas

• Embed API: controle o mapa incorporado a partir do seu próprio aplicativo com JavaScript. A mesma API atende aos dois modos de incorporação.
• Incorporar mapas: o modo publicado, sem entrada.
• Conceder o consentimento do administrador: a configuração única.
• Write-back e edição pelos visualizadores: permita que os visualizadores adicionem dados.