Criar um aplicativo Web com o Kit de Ferramentas do Microsoft Graph

  • Artigo

Este tópico descreve como começar a usar o Microsoft Graph Toolkit em um aplicativo Web escrito no JavaScript de baunilha. Para um tutorial passo a passo, experimente o módulo Introdução ao Microsoft Graph Toolkit. Se você quiser aprender a usar o Kit de Ferramentas com uma estrutura Web, consulte Criar um aplicativo Web (React) ou Criar um aplicativo Web (Angular).

Introdução ao Kit de Ferramentas envolve as seguintes etapas:

  1. Adicione o Microsoft Graph Toolkit ao seu projeto.
  2. Inicialize o provedor MSAL2 (Biblioteca de Autenticação da Microsoft 2).
  3. Adicione os componentes.
  4. Teste seu aplicativo.

Adicionar o Microsoft Graph Toolkit ao seu projeto

Você pode usar o Microsoft Graph Toolkit em seu aplicativo instalando os pacotes npm ou carregando-os de uma CDN (Rede de Entrega de Conteúdo).

Para usar o kit de ferramentas por meio de uma CDN, adicione o seguinte script e a marcação à sua página HTML:

<script type="module">
  import {
    registerMgtComponents,
    Providers,
    Msal2Provider,
  } from "https://unpkg.com/@microsoft/mgt@4";
  Providers.globalProvider = new Msal2Provider({ clientId: "[CLIENT-ID]" });
  registerMgtComponents();
</script>

Inicializar o provedor MSAL2

Os provedores do Kit de ferramentas do Microsoft Graph permitem autenticação e acesso ao Microsoft Graph para os componentes. Para saber mais, confira Usando os provedores. O Provedor MSAL2 usa o navegador MSAL para entrar usuários e adquirir tokens. Você pode inicializar esse provedor em seu HTML ou JavaScript.

Observação: se você estiver usando o Provedor MSAL no momento e quiser atualizar para o Provedor MSAL2, consulte Migrando do Provedor MSAL para o Provedor MSAL2. Se você quiser usar sua própria autenticação de back-end, use o Provedor de Proxy no lugar do Provedor MSAL2.

Você pode optar por inicializar o provedor em seu código JavaScript ou HTML.

Para inicializar o provedor MSAL em seu JavaScript, adicione o seguinte código ao seu aplicativo:

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";

Providers.globalProvider = new Msal2Provider({
  clientId: "<YOUR_CLIENT_ID>",
});

A ID do cliente é a única propriedade necessária para inicializar o provedor, mas você pode definir mais opções. Para obter a lista completa, consulte Provedor MSAL2.

Criando uma ID de aplicativo/cliente

Para obter uma ID do cliente, você precisa registrar seu aplicativo no Microsoft Entra ID.

Adicionar os componentes

Depois de inicializar o provedor MSAL2, você pode começar a usar qualquer um dos componentes do Kit de Ferramentas.

Este exemplo usa os módulos ES6, o Provedor MSAL2 inicializado em JavaScript e o Login componente:

import { Providers } from "@microsoft/mgt-element";
import { registerMgtLoginComponent } from "@microsoft/mgt-components";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";

Providers.globalProvider = new Msal2Provider({
  clientId: "<YOUR_CLIENT_ID>",
});

registerMgtLoginComponent();

function component() {
  const element = document.createElement("div");
  element.innerHTML = "<mgt-login></mgt-login>";
  return element;
}

document.body.appendChild(component());

O exemplo a seguir usa os módulos ES6, o Provedor MSAL2 inicializado em HTML e o Login componente:

<script type="module">
  import { registerMgtMsal2Provider } from "node_modules/@microsoft/mgt-msal2-provider/dist/es6/index.js";
  import { registerMgtLoginComponent } from "node_modules/@microsoft/mgt-components/dist/es6/index.js";
  registerMgtMsal2Provider();
  registerMgtLoginComponent();
</script>

<mgt-msal2-provider client-id="<YOUR_CLIENT_ID>"></mgt-msal2-provider>
<mgt-login></mgt-login>

Testar seu aplicativo

Para testar seu aplicativo, o MSAL exige que a página seja hospedada em um servidor Web para os redirecionamentos de autenticação.

Se você estiver apenas começando e quiser brincar, poderá usar o Live Server no Visual Studio Code ou em qualquer servidor de desenvolvimento leve semelhante. Baixe a extensão e abra seu arquivo HTML usando o servidor ao vivo.

Nota: Verifique se o URI de redirecionamento no registro do aplicativo está definido para a porta localhost em que seu aplicativo está hospedado. Acesse o registro do aplicativo no centro de administração do Microsoft Entra, clique em Autenticação em gerenciar e adicione o URI de redirecionamento correto.

Controlar o estado de entrada de um usuário

Você pode detectar quando um usuário é conectado com êxito e exibir componentes específicos de acordo. Por exemplo, exiba o componente de agenda se o usuário estiver conectado. Caso contrário, exiba a interface de entrada.

O pacote mgt-element fornece a isSignedIn função de utilitário que você pode chamar para verificar se um usuário está conectado.

Se você estiver usando o kit de ferramentas por meio dos pacotes npm, poderá importar o Provider e ProviderState de @microsoft/mgt-element.

import { Providers } from "@microsoft/mgt-element";
import {
  registerMgtLoginComponent,
  registerMgtAgendaComponent,
} from "@microsoft/mgt-components";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
import { isSignedIn } from "@microsoft/mgt-element";

Providers.globalProvider = new Msal2Provider({
  clientId: "<YOUR_CLIENT_ID>",
});

registerMgtLoginComponent();
registerMgtAgendaComponent();

const loadAgenda = () => {
  if (isSignedIn()) {
    document.getElementById("main").innerHTML = "<mgt-agenda></mgt-agenda>";
  }
};

Providers.onProviderUpdated(loadAgenda);

Próximas etapas