Microsoft Graph Toolkit provedoresMicrosoft Graph Toolkit providers

Os provedores de Toolkit do Microsoft Graph permitem que seu aplicativo se autenture com a Microsoft Identity e acesse o Microsoft Graph em apenas algumas linhas de código.The Microsoft Graph Toolkit providers enable your application to authenticate with Microsoft Identity and access Microsoft Graph in only few lines of code. Cada provedor lida com a autenticação do usuário e a aquisição dos tokens de acesso para chamar APIs do Microsoft Graph, para que você não tenha que escrever esse código por conta própria.Each provider handles user authentication and acquiring the access tokens to call Microsoft Graph APIs, so that you don't have to write this code yourself.

Você pode usar os provedores por conta própria, sem componentes, para implementar rapidamente a autenticação para seu aplicativo e fazer chamadas para o Microsoft Graph por meio do SDK do cliente JavaScript.You can use the providers on their own, without components, to quickly implement authentication for your app and make calls to Microsoft Graph via the JavaScript client SDK.

Os provedores são necessários ao usar os componentes do Microsoft Graph Toolkit como os componentes os usam para acessar o Microsoft Graph.The providers are required when using the Microsoft Graph Toolkit components as the components use them to access Microsoft Graph. Se você já tiver sua própria autenticação e quiser usar os componentes, poderá usar um provedor personalizado.If you already have your own authentication and want to use the components, you can use a custom provider instead.

O Toolkit inclui os seguintes provedores.The Toolkit includes the following providers.

ProvedoresProviders DescriçãoDescription
MsalMsal Usa MSAL.js para entrar em usuários e adquirir tokens para usar com o Microsoft Graph em um aplicativo Web.Uses MSAL.js to sign in users and acquire tokens to use with Microsoft Graph in a web application.
TronElectron Autentica e fornece acesso do Microsoft Graph a componentes dentro dos aplicativos Dols.Authenticates and provides Microsoft Graph access to components inside of Electron apps.
SharePointSharePoint Autentica e fornece acesso do Microsoft Graph a componentes dentro das Web Parts do SharePoint.Authenticates and provides Microsoft Graph access to components inside of SharePoint web parts.
TeamsTeams Autentica e fornece acesso do Microsoft Graph a componentes dentro das guias do Microsoft Teams.Authenticates and provides Microsoft Graph access to components inside Microsoft Teams tabs.
ProxyProxy Permite o uso da autenticação de back-end roteamento de todas as chamadas para o Microsoft Graph por meio do back-end.Allows the use of backend authentication by routing all calls to Microsoft Graph through your backend.
PersonalizadosCustom Crie um provedor personalizado para habilitar a autenticação e o acesso ao Microsoft Graph com o código de autenticação existente do aplicativo.Create a custom provider to enable authentication and access to Microsoft Graph with your application's existing authentication code.

Inicializando um provedorInitializing a provider

Para usar um provedor em seu aplicativo, você precisa inicializar um novo provedor e defini-lo como o provedor global no namespace Provedores.To use a provider in your app, you need to initialize a new provider and then set it as the global provider in the Providers namespace. Recomendamos fazer isso antes de começar a usar qualquer um dos componentes.We recommend doing this before you start using any of the components. Você pode fazer isso de duas maneiras:You can do this one of two ways:

Opção 1: Usar o componente do provedorOption 1: Use the provider component

Você pode usar a versão do componente do provedor diretamente em seu HTML.You can use the component version of the provider directly in your HTML. Nos bastidores, um novo provedor é inicializado e definido como o provedor global.Behind the scenes, a new provider is initialized and set as the global provider. O exemplo a seguir mostra como usar o MsalProvider.The following example shows how to use the MsalProvider.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal-provider client-id="YOUR_CLIENT_ID"></mgt-msal-provider>

Opção 2: Inicializar no códigoOption 2: Initialize in code

Inicializar seu provedor em seu código JavaScript permite que você forneça mais opções.Initializing your provider in your JavaScript code enables you to provide more options. Para fazer isso, crie uma nova instância de provedor e de definir o valor da propriedade para o Providers.globalProvider provedor que você gostaria de usar.To do this, create a new provider instance and set the value of the Providers.globalProvider property to the provider you'd like to use. O exemplo a seguir mostra como usar o MsalProvider.The following example shows how to use the MsalProvider.

import {Providers, MsalProvider } from "@microsoft/mgt";
Providers.globalProvider = new MsalProvider({
  clientId: 'YOUR_CLIENT_ID'
});

Observação: Para obter detalhes sobre como registrar seu aplicativo e obter uma ID do cliente, consulte Create an Azure Active Directory app.Note: For details about how to register your app and get a client ID, see Create an Azure Active Directory app.

Escopos de permissãoPermission Scopes

Recomendamos adicionar todos os escopos de permissão que seu aplicativo precisa ao atributo ou propriedade ao inicializar seu provedor (isso não se aplica scopes ao provedor do SharePoint).We recommend adding all the permission scopes your application needs to the scopes attribute or property when initializing your provider (this does not apply to the SharePoint provider). Isso é opcional, mas melhorará a experiência do usuário apresentando uma única tela de consentimento para o usuário com uma lista agregada de permissões solicitadas por todos os componentes em seu aplicativo, em vez de apresentar telas separadas para cada componente.This is optional, but will improve your user experience by presenting a single consent screen to the user with an aggregated list of permissions requested by all components in your app, rather than presenting separate screens for each component. Os exemplos a seguir mostram como fazer isso com o MsalProvider.The following examples show how to do this with the MsalProvider.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal-provider client-id="YOUR_CLIENT_ID"
                   scopes="user.read,people.read"
                   ></mgt-msal-provider>

Se você estiver inicializando o provedor em código, forneça os escopos de permissão em uma matriz na scopes propriedade.If you're initializing the provider in code, provide the permission scopes in an array in the scopes property.

import {Providers, MsalProvider } from "@microsoft/mgt";
Providers.globalProvider = new MsalProvider({
  clientId: 'YOUR_CLIENT_ID'
  scopes:['user.read','people.read']
});

Você pode encontrar a lista de escopos de permissão exigidos por cada componente na seção permissões do Microsoft Graph da página de documentação de cada componente.You can find the list of permission scopes required by each component in the Microsoft Graph permissions section of each component's documentation page.

Estado do provedorProvider state

O provedor mantém o controle do estado de autenticação do usuário e o comunica aos componentes.The provider keeps track of the user's authentication state and communicates it to the components. Por exemplo, quando um usuário faz entrada com êxito, o é atualizado para , sinalizando para os componentes que agora são capazes de fazer chamadas ProviderState SignedIn para o Microsoft Graph.For example, when a user successfully signs in, the ProviderState is updated to SignedIn, signaling to the components that they are now able to make calls to Microsoft Graph. O ProviderState número define três estados, conforme mostrado.The ProviderState enum defines three states, as shown.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn
}

Em alguns cenários, você vai querer mostrar determinada funcionalidade ou executar uma ação somente depois que um usuário tiver se assinado com êxito.In some scenarios, you will want to show certain functionality or perform an action only after a user has successfully signed in. Você pode acessar e verificar o estado do provedor, conforme mostrado no exemplo a seguir.You can access and check the provider state, as shown in the following example.

import { Providers, ProviderState } from '@microsoft/mgt'

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  //your code here
}

Você também pode usar o Providers.onProviderUpdated método para ser notificado sempre que o estado do provedor mudar.You can also use the Providers.onProviderUpdated method to get notified whenever the state of the provider changes.

import { Providers, ProviderState } from "@microsoft/mgt";

//assuming a provider has already been initialized

const providerStateChanged = () => {
  if (Providers.globalProvider.state === ProviderState.SignedIn) {
    // user is now signed in
  }
}

// register a callback for when the state changes
Providers.onProviderUpdated(providerStateChanged);

// remove callback if necessary
Providers.removeProviderUpdatedListener(providerStateChanged);

Obter um token de acessoGetting an access token

Cada provedor expõe uma função chamada que pode recuperar o token de acesso atual ou recuperar um novo token de getAccessToken acesso para os escopos fornecidos.Each provider exposes a function called getAccessToken that can retrieve the current access token or retrieve a new access token for the provided scopes. O exemplo a seguir mostra como obter um novo token de acesso com o User.Read escopo de permissão.The following example shows how to get a new access token with the User.Read permission scope.

import { Providers, ProviderState } from "@microsoft/mgt";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  const token = await Providers.globalProvider.getAccessToken({scopes: ['User.Read']})
}

Fazendo suas próprias chamadas para o Microsoft GraphMaking your own calls to Microsoft Graph

Todos os componentes podem acessar o Microsoft Graph sem qualquer personalização necessária desde que você inicialize um provedor (conforme descrito nas seções anteriores).All components can access Microsoft Graph without any customization required as long as you initialize a provider (as described in the previous sections). Se quiser fazer suas próprias chamadas para o Microsoft Graph, faça isso fazendo referência ao mesmo SDK do Microsoft Graph usado pelos componentes.If you want to make your own calls to Microsoft Graph, you can do so by getting a reference to the same Microsoft Graph SDK used by the components. Primeiro, obter uma referência para o global IProvider e, em seguida, usar o graph objeto conforme mostrado:First, get a reference to the global IProvider and then use the graph object as shown:

import { Providers } from '@microsoft/mgt';

let provider = Providers.globalProvider;
if (provider) {
  let graphClient = provider.graph.client;
  let userDetails = await graphClient.api('me').get();
}

Pode haver casos em que você precisa passar permissões adicionais, dependendo da API que você está chamando.There might be cases where you need to pass additional permissions, depending on the API you're calling. O exemplo a seguir mostra como fazer isso.The following example shows how to do this.

import { prepScopes } from '@microsoft/mgt';

graphClient
  .api('me')
  .middlewareOptions(prepScopes('user.read', 'calendar.read'))
  .get();

Usando vários provedoresUsing multiple providers

Em alguns cenários, seu aplicativo será executado em ambientes diferentes e exigirá um provedor diferente para cada um.In some scenarios, your application will run in different environments and require a different provider for each. Por exemplo, o aplicativo pode ser executado como um aplicativo Web e uma guia do Microsoft Teams, o que significa que talvez seja necessário usar o MsalProvider e o TeamsProvider.For example, the app might run as both a web application and a Microsoft Teams tab, which means you might need to use both the MsalProvider and the TeamsProvider. Para esse cenário, todos os componentes do provedor têm o atributo para criar uma cadeia depends-on de fallback, conforme mostrado no exemplo a seguir.For this scenario, all provider components have the depends-on attribute to create a fallback chain, as shown in the following example.

<mgt-teams-provider
  client-id="[CLIENT-ID]"
  auth-popup-url="auth.html" ></mgt-teams-provider>

<mgt-msal-provider
  client-id="[CLIENT-ID]"
  depends-on="mgt-teams-provider" ></mgt-msal-provider>

Nesse cenário, o MsalProvider só será usado se seu aplicativo estiver sendo executado como um aplicativo Web e o TeamsProvider não estiver disponível no ambiente atual.In this scenario, the MsalProvider will only be used if your app is running as a web application and the TeamsProvider is not available in the current environment.

Para fazer o mesmo no código, você pode usar a isAvailable propriedade no provedor, conforme mostrado.To accomplish the same in code, you can use the isAvailable property on the provider, as shown.

if (TeamsProvider.isAvailable) {
    Providers.globalProvider = new TeamsProvider(teamsConfig);
} else {
    Providers.globalProvider = new MsalProvider(msalConfig)
}

Logout/Logout do UsuárioUser Login/Logout

Quando você tem os provedores corretos inicializados para seu aplicativo, você pode adicionar o componente de Logon do Toolkit para implementar logon e logout do usuário de forma fácil e rápida.When you have the right providers initialized for your application, you can add the Toolkit's Login component to easily and quickly implement user login and logout. O componente funciona com o provedor para lidar com toda a lógica de autenticação e a funcionalidade de logout/logout.The component works with the provider to handle all of the authentication logic and login/logout functionality. O exemplo a seguir usa o MsalProvider e o componente Logon.The following example uses the MsalProvider and the Login component.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal-provider client-id="YOUR_CLIENT_ID"></mgt-msal-provider>
<mgt-login></mgt-login>

Em cenários em que você deseja implementar isso por conta própria, em vez de usar o componente de Logon do Toolkit, você pode fazer isso usando os métodos e login logout do provedor.In scenarios where you want to implement this yourself, rather than using the Toolkit's Login component, you can do so by using the login and logout methods of the provider.

Implementar seu próprio provedorImplement your own provider

Em cenários em que você deseja adicionar Toolkit componentes a um aplicativo com código de autenticação pré-existente, você pode criar um provedor personalizado que se ligue ao mecanismo de autenticação, em vez de usar nossos provedores predefinidos.In scenarios where you want to add Toolkit components to an application with pre-existing authentication code, you can create a custom provider that hooks into your authentication mechanism, instead of using our predefined providers. O kit de ferramentas fornece duas maneiras de criar novos provedores:The toolkit provides two ways to create new providers:

  • Crie um novo que retorna um token de acesso do código de SimpleProvider autenticação passando uma função.Create a new SimpleProvider that returns an access token from your authentication code by passing in a function.
  • Estender a IProvider classe abstrata.Extend the IProvider abstract class.

Para obter mais detalhes sobre cada um, consulte provedores personalizados.For more details about each one, see custom providers.