Acesso e Gerenciamento de Dados do Microsoft 365 com Microsoft Graph

Otimize o Acesso e Gerenciamento de Dados do Microsoft 365 com o Aspose.Email Graph Client

Microsoft Graph é uma API REST para acessar os dados do Microsoft 365. A implementação do Graph Client no Aspose.Email para .NET permite o acesso ao Microsoft Graph a partir da nossa API. Nos exemplos abaixo, criaremos uma instância do MS Graph Client, fornecendo o token. Em seguida, examinaremos os principais métodos para gerenciar pastas, atualizar, copiar e excluí‑las. Mensagens, seu conteúdo e anexos também podem ser acessados ou alterados com o nosso MS Graph Client. Gerenciar categorias, regras, cadernos e substituições é um recurso avançado do Microsoft Graph Client da Aspose.Email.

Autenticar e Requisitar com IGraphClient Usando MSAL no .NET

Para interagir com os serviços do Microsoft Graph, você precisará criar um IGraphClient objeto. Uma vez autenticado, esse cliente permite que você faça várias solicitações de serviço. O GetClient método, que cria o IGraphClient, requer um ITokenProvider implementação como seu primeiro parâmetro. Este ITokenProvider é responsável por fornecer o token de autenticação necessário. Para obter o token, usaremos o Biblioteca de Autenticação da Microsoft (MSAL) para .NET.

Veja como configurar o processo de autenticação:

Etapa 1: Configurando a Autenticação

Os passos a seguir irão orientá‑lo sobre como obter um token de autorização:

  1. Crie a Classe AccessParameters.

    Defina uma classe AccessParameters para armazenar suas credenciais.

public class AccessParameters
{
    public string TenantId { get; init; }
    public string ClientId { get; init; }
    public string ClientSecret { get; init; }
    public string UserId { get; init; }
    public Uri Authority => new ($"https://login.microsoftonline.com/{TenantId}");
    public string ApiUrl => "https://graph.microsoft.com/.default";
}

  1. Adicione o Pacote MSAL.NET.

    Instale o Microsoft.Identity.Client Pacote NuGet, que contém os binários MSAL.NET necessários para autenticação.

  2. Implemente a Interface ITokenProvider.

    Crie um GraphTokenProvider classe que implementa o ITokenProvider interface. Esta classe usará a biblioteca MSAL.NET para adquirir um token de acesso.

using Microsoft.Identity.Client;
using Microsoft.Identity.Web;
using Aspose.Email.Clients;

public class GraphTokenProvider : ITokenProvider
{
    private readonly IConfidentialClientApplication _app;
    private readonly string[] _scopes;
    private string? _token;

    public GraphTokenProvider(AccessParameters accessParams)
    {
        _app = ConfidentialClientApplicationBuilder.Create(accessParams.ClientId)
            .WithClientSecret(accessParams.ClientSecret)
            .WithAuthority(accessParams.Authority)
            .Build();

        _app.AddInMemoryTokenCache();

        _scopes = new[] { accessParams.ApiUrl };
    }

    public void Dispose()
    {
        throw new NotImplementedException();
    }

    public OAuthToken GetAccessToken()
    {
        return GetAccessToken(false);
    }

    public OAuthToken GetAccessToken(bool ignoreExistingToken)
    {
        if (!ignoreExistingToken && _token != null)
        {
            return new OAuthToken(_token);
        }

        _token = GetAccessTokenAsync().GetAwaiter().GetResult();
        return new OAuthToken(_token);
    }

    private async Task<string?> GetAccessTokenAsync()
    {
        AuthenticationResult? result;

        try
        {
            result = await _app.AcquireTokenForClient(_scopes)
                .ExecuteAsync();

            Console.WriteLine("Token acquired");
        }
        catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
        {
            Console.WriteLine("Scope provided is not supported");
            result = null;
        }

        if (result == null) return null;
        _token = result.AccessToken;
        return result.AccessToken;
    }

Etapa 2: Criar uma Instância de ITokenProvider

Depois de definir o GraphTokenProvider classe, você pode criar uma instância de AccessParameters e use‑o para instanciar o GraphTokenProvider.

var accessParams = new AccessParameters()
{
    TenantId = "Your Tenant ID",
    ClientId = "Your Client ID",
    ClientSecret = "Your Client Secret",
    UserId = "User's Object ID"
};

var tokenProvider = new GraphTokenProvider(accessParams);

Etapa 3: Fazer Solicitações com IGraphClient

Finalmente, use o GraphTokenProvider para criar um autenticado IGraphClient e comece a fazer solicitações de serviço.

using var client = GraphClient.GetClient(tokenProvider, accessParams.TenantId);

client.Resource = ResourceType.Users;
client.ResourceId = accessParams.UserId;

Com estas etapas concluídas, seu IGraphClient já está pronto para interagir com os serviços Microsoft Graph usando solicitações autenticadas.

Conectando a Endpoints GCC High

O GraphClient suporta conexão com endpoints GCC High usando o EndPoint propriedade. O exemplo de código a seguir demonstra como configurar o GraphClient para conectar ao endpoint GCC High para listar pastas e recuperar mensagens.

client.EndPoint = "https://graph.microsoft.us";

var folders = client.ListFolders();
string folderId = folders.Find(x => x.DisplayName == "Inbox").ItemId;
var msgs = client.ListMessages(folderId);

Gerenciar Pastas com IGraphClient

Listar Pastas

Chamando ListFolders método do MS Graph Client, é possível obter a lista de pastas. Cada pasta tem um conjunto de parâmetros como DisplayName, que pode ser lido em FolderInfo tipo.

var folders = client.ListFolders();

foreach (var folder in folders)
{
    Console.WriteLine(folder.DisplayName);
}

Atualizar Pastas

Para criar pasta com MS Graph Client, use CreateFolder método. Você receberá um FolderInfo objeto e a possibilidade de acessar DisplayName, ItemId, HasSubFolders e outras propriedades.

var folderInfo = client.CreateFolder("FolderName");
folderInfo.DisplayName = "FolderAnotherName";
client.UpdateFolder(folderInfo);

Copiar Pastas

CopyFolder método é o método principal para copiar o objeto de pasta com MS Graph.

var folderInfo1 = client.CreateFolder("Folder1");
var folderInfo2 = client.CreateFolder("Folder2");
    
// copy Folder2 to Folder1
client.CopyFolder(folderInfo1.ItemId, folderInfo2.ItemId);

Mover e Excluir Pastas

Usar MoveFolder método usado para mover a pasta, aceita newParentId e itemId. Excluir método usado para excluir um método por id.

var folderInfo1 = client.CreateFolder("Folder1");
var folderInfo2 = client.CreateFolder("Folder2");
    
// move Folder2 to Folder1
client.MoveFolder(folderInfo1.ItemId, folderInfo2.ItemId);
    
// delete Folder1
client.Delete(folderInfo1.ItemId)

Gerenciar Mensagens com IGraphClient

MS Graph Client, implementado em Aspose.Email para .NET, fornece um conjunto de métodos para gerenciar mensagens e anexos:

Listar Mensagens

var folders = client.ListFolders();

foreach (var folder in folders)
{
    if (folder.DisplayName.Equals("Inbox"))
    {
        // list messages in inbox
        var inboxMessages = client.ListMessages(folder.ItemId);

        foreach (var messageInfo in inboxMessages)
        {
            Console.WriteLine(messageInfo.Subject);
        }
    }
}

Filtrar Mensagens por Data de Envio

O OrderBy método da coleção de biblioteca permite recuperar mensagens com diferentes ordens de classificação (crescente e decrescente) com base na data de envio. O exemplo de código a seguir mostra como ordenar mensagens pela data de envio:

IGraphClient client = GraphClient.GetClient(provider, TenantId);

var builder = new GraphQueryBuilder();

// create orderby messages query 'DESC'
builder.SentDate.OrderBy(false);
var messagePageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(10), builder.GetQuery());
var messages = messagePageInfo.Items;

builder.Clear();

// create orderby messages query 'ASC'
builder.SentDate.OrderBy(true);
messagePageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(10), builder.GetQuery());
messages = messagePageInfo.Items;

Enumerar Mensagens com Suporte a Paginação

A API permite paginação e filtragem das mensagens ao listá‑las. Isso é especialmente útil para caixas de correio com grande volume de mensagens, pois economiza tempo ao recuperar apenas as informações resumidas necessárias.

O exemplo de código e as etapas abaixo demonstram como recuperar mensagens da pasta Inbox usando recursos de paginação e filtragem.

  1. Primeiro, inicie o cliente.
  2. Em seguida, defina o número de itens a exibir por página, por exemplo, 10.
  3. Crie um filtro para recuperar apenas mensagens não lidas usando o GraphQueryBuilder classe. O builder.IsRead.Equals(false) está definindo a condição para filtrar mensagens não lidas.
  4. Chame o ListMessages método no objeto cliente, especificando a pasta (Inbox) e o número de itens por página (PageInfo(itemsPerPage)) como parâmetros. Também passa o objeto de consulta para aplicar o filtro de mensagens não lidas. O objeto PageInfo retornado (pageInfo) contém as mensagens recuperadas para a página atual na propriedade Items.
  5. Crie um loop que continue até que a última página seja alcançada (pageInfo.LastPage é false). As mensagens recuperadas são adicionadas à lista existente de mensagens usando messages.AddRange(pageInfo.Items).
//  reading unread messages with paging
using var client = GraphClient.GetClient(tokenProvider, config.Tenant);

// paging option
var itemsPerPage = 10;
// create unread messages filter
GraphQueryBuilder builder = new GraphQueryBuilder();
builder.IsRead.Equals(false);
var query = builder.GetQuery();

// list messages
var pageInfo = client.ListMessages(KnownFolders.Inbox, new PageInfo(itemsPerPage), query);
var  messages = pageInfo.Items;

while (!pageInfo.LastPage)
{
    pageInfo = client.ListMessages(KnownFolders.Inbox, pageInfo.NextPage, query);
    messages.AddRange(pageInfo.Items);
}

// set messages state as read
foreach (var message in messages)
{
    client.SetRead(message.ItemId);
}

Buscar Mensagens

var folders = client.ListFolders();

foreach (var folder in folders)
{
    if (folder.DisplayName.Equals("Inbox"))
    {
        // list messages in inbox
        var inboxMessages = client.ListMessages(folder.ItemId);

        if (inboxMessages.Count > 0)
        {
            // fetch the first message in inbox
            var msg = client.FetchMessage(inboxMessages[0].ItemId);
            
            Console.WriteLine(msg.BodyHtml);
        }
        
    }
}

Criar Mensagens

var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);

// create message in inbox
client.CreateMessage(KnownFolders.Inbox, msg);

Enviar Mensagens

// prepare the message
var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "John@from.com");

// send message
client.Send(msg);

Enviar Mensagens de Rascunho

// prepare the message
var msg = new MapiMessage(OutlookMessageFormat.Unicode)
{
    Subject = "My message",
    Body = "Hi, it is my message"
};

msg.Recipients.Add("sam@to.com", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "John@from.com");

// add message to Draft folder
var draftMessage = client.CreateMessage(KnownFolders.Drafts, msg);

// send a draft message
client.Send(draftMessage.ItemId);

Enviar Mensagens EML

Criar e enviar e‑mails é fácil usando o objeto MailMessage. O exemplo de código a seguir demonstra como criar e enviar uma mensagem de e‑mail usando a Graph API:

// prepare the message
var eml = new MailMessage
{
    From = "from@domain.com",
    To = "to1@domain.com, to2@domain.com",
    Subject = "New message",
    HtmlBody = "<html><body>This is the HTML body</body></html>"
};

// send the message
graphClient.Send(eml);
graphClient.Create(KnownFolders.Inbox, eml);

Copiar Mensagens


// copy message to Inbox folder
var copiedMsg = client.CopyMessage(KnownFolders.Inbox, msg.ItemId);

Mover Mensagens

// move message to Inbox folder
var movedMsg = client.MoveMessage(KnownFolders.Inbox, msg.ItemId);

Gerenciar Anexos


// create an attachment
var attachment = new MapiAttachment();
attachment.SetProperty(KnownPropertyList.DisplayName, "My Attachment");
attachment.SetProperty(KnownPropertyList.AttachDataBinary, new byte[1024]);

// add an attachment to message
var createdAttachment = client.CreateAttachment(messageInfo.ItemId, attachment);

// fetch a message attachment
var fetchedAttachment = client.FetchAttachment(createdAttachment.ItemId);

// delete a message attachment 
client.DeleteAttachment(createdAttachment.ItemId);

// list the message attachments
var attachments = client.ListAttachments(messageInfo.ItemId);

Gerenciar Itens do Outlook com Graph Client

Gerenciar Eventos de Calendário

Aspose.Email fornece APIs para acessar, gerenciar e interagir com eventos de calendário. Para esses fins, oferece os seguintes métodos no IGraphClient interface:

  • ListCalendars() - Recupera uma coleção de informações de calendário.
  • ListCalendarItems(string id) - Recupera uma coleção de itens de calendário associados ao ID de calendário especificado.
  • FetchCalendarItem(string id) - Recupera um item de calendário específico com base no ID fornecido.
  • CreateCalendarItem(string calId, MapiCalendar mapiCalendar) - Cria um novo item de calendário no calendário especificado.
  • UpdateCalendarItem(MapiCalendar mapiCalendar) - Atualiza um item de calendário existente.
  • UpdateCalendarItem(MapiCalendar mapiCalendar, UpdateSettings updateSettings) - Atualiza um item de calendário existente com as configurações de atualização especificadas.

O exemplo de código a seguir demonstra como interagir com eventos de calendário em um cliente Microsoft Graph API usando os métodos fornecidos pelo Aspose.Email:


// List Calendars
CalendarInfoCollection calendars = graphClient.ListCalendars();

// List Calendar Items
MapiCalendarCollection calendarItems = graphClient.ListCalendarItems("calendarId");

// Fetch Calendar Item
MapiCalendar calendarItem = graphClient.FetchCalendarItem("calendarItemId");

// Create Calendar Item
MapiCalendar newCalendarItem = new MapiCalendar(
    location: "Conference Room",
    summary: "Team Meeting",
    description: "Discuss project status and updates.",
    startDate: startDate,
    endDate: endDate
);

MapiCalendar createdCalendarItem = graphClient.CreateCalendarItem("calendarId", newCalendarItem);

// Update Calendar Item
createdCalendarItem.Location = "Zoom Meeting";
MapiCalendar updatedCalendarItem = graphClient.UpdateCalendarItem(createdCalendarItem);

Gerenciar Categorias

Para gerenciar categorias com MS Graph via Aspose.Email para .NET, use os seguintes métodos:

// create a custom category with Orange color
var category = client.CreateCategory("My custom category", CategoryPreset.Preset1);

// fetch a category
var fetchedCategory = client.FetchCategory(category.Id);

// update category (change color to brown)
fetchedCategory.Preset = CategoryPreset.Preset2;
var updatedCategory = client.UpdateCategory(fetchedCategory);

// list available categories
var categories = client.ListCategories();

foreach (var cat in categories)
{
    Console.WriteLine(cat.DisplayName);
}

// delete a category
client.Delete(fetchedCategory.Id);

Gerenciar Contatos

Aspose.Email fornece APIs para acessar, gerenciar e interagir com itens de contato. Para esses fins, oferece os seguintes métodos no IGraphClient interface:

  • ListContacts(string id) - Recupera uma coleção de contatos MAPI associados ao ID da pasta especificada.
  • FetchContact(string id) - Recupera um contato específico com base no ID do item fornecido.
  • CreateContact(string folderId, MapiContact contact) - Cria um novo contato na pasta especificada.
  • UpdateContact(MapiContact contact) - Atualiza um contato existente.

O exemplo de código a seguir demonstra como interagir com contatos em um cliente Microsoft Graph API usando os métodos fornecidos pelo Aspose.Email:

// List Contacts
MapiContactCollection contacts = graphClient.ListContacts("contactFolderId");

// Fetch Contact
MapiContact contact = graphClient.FetchContact("contactId");

// Create Contact
MapiContact newContact = new MapiContact("Jane Smith", "jane.smith@example.com", "XYZ Corporation", "777-888-999");

MapiContact createdContact = graphClient.CreateContact("contactFolderId", newContact);

// Update Contact
createdContact.Telephones.PrimaryTelephoneNumber = "888-888-999";

MapiContact updatedContact = graphClient.UpdateContact(createdContact);

Gerenciar Substituições

Para gerenciar substituições com MS Graph via Aspose.Email para .NET, use os seguintes métodos:

// Create an user's override
var userOverride = client.CreateOrUpdateOverride
    (new MailAddress("JohnBrown@someorg.com", "JohnBrown"), ClassificationType.Focused);

// list the overrides
var overrides = client.ListOverrides();

// update override
userOverride.Sender.DisplayName = "John Brown";
var updatedOverride = client.UpdateOverride(userOverride);

// delete override
client.Delete(updatedOverride.Id);

Gerenciar Regras

Para gerenciar regras com MS Graph via Aspose.Email para .NET, use os seguintes métodos:

// Create a rule
var rule = PrepareRule("user@someorg.com", "User");
var createdRule = client.CreateRule(rule);

// List all rules defined for Inbox
var rules = client.ListRules();

// Fetch a rule
var fetchedRule = client.FetchRule(createdRule.RuleId);

// Update a rule
fetchedRule.DisplayName = "Renamed rule";
fetchedRule.IsEnabled = false;
var updatedRule = client.UpdateRule(createdRule);

// Delete a rule
client.Delete(updatedRule.RuleId);

InboxRule PrepareRule(string email, string displayName)
{
    var rule = new InboxRule()
    {
        DisplayName = "My rule",
        Priority = 1,
        IsEnabled = true,
        Conditions = new RulePredicates(),
        Actions = new RuleActions()
    };

    rule.Conditions.ContainsSenderStrings = new StringCollection { displayName };
    rule.Actions.ForwardToRecipients = new MailAddressCollection
        { new MailAddress(email, displayName, true) };
    rule.Actions.StopProcessingRules = true;

    return rule;
}

Gerenciar Notebooks

Para gerenciar notebooks com MS Graph via Aspose.Email para .NET, use os seguintes métodos:

// create a OneNote notebook
var newNotebook = new Notebook()
{
    DisplayName = "My Notebook"
};
var createdNotebook = client.CreateNotebook(newNotebook);

// fetch a notebook
var fetchedNotebook = client.FetchNotebook(createdNotebook.Id);

// list the notebooks
var notebooks = client.ListNotebooks();

Gerenciamento de Tarefas no Microsoft Graph

Aspose.Email fornece aos desenvolvedores APIs para acessar, gerenciar e interagir com as tarefas e listas de tarefas dos usuários usando os seguintes métodos do IGraphClient interface:

O exemplo de código a seguir demonstra como gerenciar listas de tarefas:

// List Task Lists
var taskLists = graphClient.ListTaskLists();

foreach (var tList in taskLists)
{
    Console.WriteLine($"Task List: {tList.DisplayName}");
}

// Get Task List
var taskList = graphClient.GetTaskList("taskListId");

// Delete Task List
graphClient.DeleteTaskList("taskListId");

O exemplo de código a seguir demonstra como gerenciar tarefas:

// List Tasks in a Task List
MapiTaskCollection tasks = graphClient.ListTasks("taskListId");

// Fetch Task
MapiTask task = graphClient.FetchTask("taskId");

// Create Task
var newTask = new MapiTask
{
    Subject = "New Task",
    DueDate = new DateTime(2023, 12, 31),
    Status = MapiTaskStatus.NotStarted
};

MapiTask createdTask = graphClient.CreateTask(newTask, "taskListUri");

// Update Task
createdTask.Subject = "Updated Task Subject";
MapiTask updatedTask = graphClient.UpdateTask(createdTask);

// Update Task with UpdateSettings
var updateSettings = new UpdateSettings { SkipAttachments  = true };
MapiTask updatedTaskWithSettings = graphClient.UpdateTask(createdTask, updateSettings);
Recursos de Utilitário do Microsoft Graph Gerenciar Pastas de Email no Microsoft Graph (Aspose.Email)