Acessar eventos do calendário de um usuário usando o Microsoft Graph

  • 5 minutos

Você executou um aplicativo ASP.NET Core e conectou-o ao Microsoft 365. Nesta unidade, você aprenderá a exibir os eventos de calendário de um usuário para a próxima semana. Você também aprenderá a consultar eventos de dados para um determinado período. Por fim, você aprenderá sobre conceitos como selecionar e pedir para exibir as informações da maneira desejada.

Decidir quais permissões seu aplicativo precisa

Todos os dados expostos pelo Microsoft Graph são protegidos e seu aplicativo deve ter as permissões adequadas concedidas para acessá-los. A permissão necessária depende do tipo de informação que seu aplicativo precisa acessar. Por exemplo, para acessar o calendário do usuário, seu aplicativo precisa ter a permissão Calendars.Read. A lista exata das permissões necessárias para cada operação está disponível na referência da API do Microsoft Graph.

Se seu aplicativo carregar diferentes tipos de dados, os usuários deverão conceder a ele várias permissões necessárias para acessar essas informações. É recomendável que, em seu aplicativo, você solicite apenas as permissões necessárias.

Especificar as permissões necessárias

A lista de permissões concedidas ao seu aplicativo é inserida diretamente no token de acesso. O padrão OAuth os chama de escopos. Quando a sua aplicação utiliza a MSAL para obter o token de acesso, tem de incluir uma lista de âmbitos no pedido para o ID do Microsoft Entra. Cada operação no Microsoft Graph tem sua própria lista de escopos. Se o token de acesso não tiver um deles, a solicitação será negada.

O aplicativo de exemplo armazena as permissões necessárias no arquivo appsettings.json em uma propriedade Scopes como você viu anteriormente.

"Scopes": "user.read presence.read mailboxsettings.read calendars.read"

O valor da propriedade Scopes é usado pelo middleware ASP.NET Core do aplicativo, que manipula a recuperação de um token de acesso depois que o usuário entra com êxito.

Middleware: plataforma de identidade da Microsoft e Microsoft Graph

ASP.NET Core dá suporte a middleware que pode ser usado para autenticar e autorizar usuários. Ele também pode ser usado para recuperar um token que pode ser usado para chamar o Microsoft Graph, injetar um objeto do SDK do Microsoft Graph chamado GraphServiceClient no aplicativo, criar um cache de token e muito mais. O middleware é configurado em Startup.cs e manipula as tarefas a seguir.

  1. Recupere as permissões necessárias definidas na propriedade Scopes de appsettings.json.
  2. Adicione suporte para autenticação OpenId.
  3. Especifique que o aplicativo é um aplicativo Web da plataforma de identidade da Microsoft que requer um fluxo de código de autenticação.
  4. Adicione a capacidade de chamar APIs do Microsoft Graph com permissões específicas.
  5. Habilite a injeção de dependência do GraphServiceClient (um objeto fornecido pelo SDK do Microsoft Graph que é usado para fazer chamadas no Microsoft Graph).
  6. Adicione um cache de token na memória.
  7. Será necessário um usuário autenticado para acessar o aplicativo.
  8. Habilite suporte ao Razor Pages.
  9. Adicione páginas de interface do usuário do Microsoft Identity que forneçam suporte para entrada e saída do usuário.

Você pode ver cada uma dessas etapas no código a seguir definido no método ConfigureServices() do Startup.cs.

// 1. Retrieve required permissions from appsettings
string[] initialScopes =
Configuration.GetValue<string>("DownstreamApi:Scopes")?.Split(' ');


services
  // 2. Add support for OpenId authentication
  .AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)

  // 3. Microsoft identity platform web app that requires an auth code flow
  .AddMicrosoftIdentityWebApp(Configuration)

  // 4. Add ability to call Microsoft Graph APIs with specific permissions
  .EnableTokenAcquisitionToCallDownstreamApi(initialScopes)

  // 5. Enable dependency injection for GraphServiceClient
  .AddMicrosoftGraph(Configuration.GetSection("DownstreamApi"))

  // 6. Add in-memory token cache
  .AddInMemoryTokenCaches();


// 7. Require an authenticated user
services.AddControllersWithViews(options =>
{
  var policy = new AuthorizationPolicyBuilder()
      .RequireAuthenticatedUser()
      .Build();
  options.Filters.Add(new AuthorizeFilter(policy));
});

services
  // 8. Add Razor Pages support
  .AddRazorPages()

  // 9. Add Microsoft Identity UI pages that provide user
  // sign-in and sign-out support
  .AddMicrosoftIdentityUI();

Depois que o middleware necessário for configurado, o aplicativo manipulará automaticamente a entrada do usuário e a recuperação do token de acesso. O token de acesso pode ser usado para recuperar eventos de calendário de um usuário, pois ele conterá as permissões necessárias. Vamos examinar como esse processo funciona.

Recuperar eventos de calendário de um usuário por um determinado período de tempo

Para obter eventos de calendário de um usuário do Microsoft Graph, você precisa chamar o ponto de extremidade /me/calendarview . Ele retorna uma lista de eventos de calendário do calendário padrão do usuário conectado. Você pode fazer a chamada para o Microsoft Graph usando o objeto GraphServiceClient que foi mencionado anteriormente na seção de middleware. GraphServiceClient fornece APIs que podem ser usadas para chamar o Microsoft Graph sem precisar fazer chamadas HTTP manualmente. Para mostrar eventos de calendário para a próxima semana, você precisa definir as datas de início e fim da semana.

// Configure a calendar view for the current week
var startOfWeek = DateTime.Now;
var endOfWeek = startOfWeek.AddDays(7);

Essas datas são adicionadas a uma lista QueryOption que define o intervalo de eventos a serem selecionados.

var viewOptions = new List<QueryOption>
{
  new QueryOption("startDateTime", startOfWeek.ToString("o")),
  new QueryOption("endDateTime", endOfWeek.ToString("o"))
};

Um objeto GraphServiceClient (injetado no construtor da classe de modelo da Página Razor) é então usado para chamar Me.CalendarViewe a lista viewOptions é passada para o método Request para limitar os resultados. O código também inclui o fuso horário preferencial do usuário chamando método Header.

// Use the injected GraphServiceClient object to call into Me.CalendarView
var calendarEvents = await _graphServiceClient
    .Me
    .CalendarView
    .Request(viewOptions)
    .Header("Prefer", $"outlook.timezone=\"{userTimeZone}\"")

Minimizar a quantidade de dados que Microsoft Graph recupera e transfere melhora significativamente o desempenho do aplicativo. O método selecionado GraphServiceClient’s pode ser usado para selecionar propriedades específicas nos resultados que o aplicativo usará.

.Select(evt => new
{
    evt.Subject,
    evt.Organizer,
    evt.Start,
    evt.End
})

Por fim, o método OrderBy é usado para especificar como classificar os itens resultantes e GetAsync é chamado para iniciar a solicitação.

.OrderBy("start/DateTime")
.GetAsync();

Nesse caso, o código classificará os resultados pela start sub-propriedade da propriedade chamada DateTime. Para classificar por vários campos, especifique uma lista de campos separados por vírgula. Você também pode especificar se deseja classificar os itens em ordem crescente ou decrescente acrescentando as palavras-chave asc ou desc à sua consulta. A versão completa do código é mostrada a seguir:

// Configure a calendar view for the current week
var startOfWeek = DateTime.Now;
var endOfWeek = startOfWeek.AddDays(7);

var viewOptions = new List<QueryOption>
{
    new QueryOption("startDateTime", startOfWeek.ToString("o")),
    new QueryOption("endDateTime", endOfWeek.ToString("o"))
};

// Use the injected GraphServiceClient object to call into Me.CalendarView
var calendarEvents = await _graphServiceClient
    .Me
    .CalendarView
    .Request(viewOptions)
    .Header("Prefer", $"outlook.timezone=\"{userTimeZone}\"")
    .Select(evt => new
    {
        evt.Subject,
        evt.Organizer,
        evt.Start,
        evt.End
    })
    .OrderBy("start/DateTime")
    .GetAsync();

Vamos examinar como você pode usar esse código no aplicativo.