Acceso y gestión de datos de Microsoft 365 con Microsoft Graph

Optimizar el acceso y la gestión de datos de Microsoft 365 con el Cliente Graph de Aspose.Email

Microsoft Graph es una API REST para acceder a los datos de Microsoft 365. La implementación del Cliente Graph en Aspose.Email para .NET permite el acceso a Microsoft Graph desde nuestra API. En los ejemplos a continuación, crearemos una instancia del Cliente MS Graph, proporcionando el token. Luego, examinaremos los métodos principales para gestionar carpetas, actualizar, copiar y eliminarlas. Los mensajes, su contenido y sus archivos adjuntos también pueden ser accedidos o modificados con nuestro Cliente MS Graph. La gestión de categorías, reglas, cuadernos y anulaciones es una característica ampliada del Cliente Microsoft Graph de Aspose.Email.

Autenticar y solicitar con IGraphClient usando MSAL en .NET

Para interactuar con los servicios de Microsoft Graph, necesitará crear un IGraphClient objeto. Una vez autenticado, este cliente le permite realizar varias solicitudes de servicio. El GetClient método, que crea el IGraphClient, requiere un ITokenProvider implementación como su primer parámetro. Esto ITokenProvider es responsable de proporcionar el token de autenticación necesario. Para obtener el token, usaremos el Biblioteca de Autenticación de Microsoft (MSAL) para .NET.

Así es como se configura el proceso de autenticación:

Paso 1: Configurar la autenticación

Los siguientes pasos le guiarán sobre cómo obtener un token de autorización:

  1. Crear la clase AccessParameters.

    Define una clase AccessParameters para almacenar tus credenciales.

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. Agregar el Paquete MSAL.NET.

    Instala el Microsoft.Identity.Client Paquete NuGet, que contiene los binarios MSAL.NET necesarios para la autenticación.

  2. Implementar la interfaz ITokenProvider.

    Cree un GraphTokenProvider clase que implementa el ITokenProvider interfaz. Esta clase usará la biblioteca MSAL.NET para adquirir un token de acceso.

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;
    }

Paso 2: Crear una instancia de ITokenProvider

Después de definir el GraphTokenProvider clase, puede crear una instancia de AccessParameters y úselo para instanciar el 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);

Paso 3: Realizar solicitudes con IGraphClient

Finalmente, use el GraphTokenProvider para crear un autenticado IGraphClient y comenzar a hacer solicitudes de servicio.

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

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

Con estos pasos completados, su IGraphClient está ahora listo para interactuar con los servicios de Microsoft Graph usando solicitudes autenticadas.

Conectándose a endpoints GCC High

El GraphClient soporta la conexión a endpoints GCC High usando el EndPoint propiedad. El siguiente ejemplo de código muestra cómo configurar GraphClient para conectarse al endpoint GCC High para listar carpetas y recuperar mensajes.

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

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

Administrar carpetas con IGraphClient

Listar carpetas

Al llamar ListFolders método de MS Graph Client, es posible obtener la lista de carpetas. Cada carpeta tiene un conjunto de parámetros como DisplayName, que se pueden leer en FolderInfo tipo.

var folders = client.ListFolders();

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

Actualizar carpetas

Para crear una carpeta con MS Graph Client, use CreateFolder método. Obtendrá un FolderInfo objeto y la posibilidad de acceder a DisplayName, ItemId, HasSubFolders y otras propiedades.

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

Copiar carpetas

CopyFolder el método es el método clave para copiar el objeto de carpeta con MS Graph.

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

Mover y eliminar carpetas

Usar MoveFolder el método se usa para mover la carpeta, acepta newParentId e itemId. Eliminar el método se usa para eliminar un 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)

Administrar mensajes con IGraphClient

MS Graph Client, implementado en Aspose.Email para .NET, proporciona un conjunto de métodos para gestionar mensajes y archivos adjuntos:

Listar mensajes

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 mensajes por fecha de envío

El OrderBy El método de la colección de la biblioteca le permite recuperar mensajes con diferentes órdenes de clasificación (ascendente y descendente) basados en la fecha de envío. El siguiente ejemplo de código muestra cómo ordenar los mensajes por su fecha de envío:

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 mensajes con soporte de paginación

La API permite la paginación y el filtrado de los mensajes al listarlos. Es especialmente útil para buzones con un alto volumen de mensajes, ya que ahorra tiempo al recuperar solo la información resumida necesaria.

El ejemplo de código y los pasos a continuación demuestran cómo recuperar mensajes de la carpeta Inbox usando funcionalidades de paginación y filtrado.

  1. Primero, inicie el cliente.
  2. Luego, establezca el número de elementos a mostrar por página, por ejemplo, 10.
  3. Cree un filtro para recuperar solo los mensajes no leídos usando el GraphQueryBuilder clase. El builder.IsRead.Equals(false) establece la condición para filtrar mensajes no leídos.
  4. Llame al ListMessages método en el objeto cliente, especificando la carpeta (Inbox) y los elementos por página (PageInfo(itemsPerPage)) como parámetros. También pasa el objeto de consulta para aplicar el filtro de mensajes no leídos. El objeto PageInfo devuelto (pageInfo) contiene los mensajes recuperados para la página actual en la propiedad Items.
  5. Cree un bucle que continúe hasta que se alcance la última página (pageInfo.LastPage es false). Los mensajes recuperados se añaden a la lista de mensajes existente 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);
}

Recuperar mensajes

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);
        }
        
    }
}

Crear mensajes

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 mensajes

// 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 borradores de mensajes

// 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 mensajes EML

Crear y enviar correos electrónicos es fácil usando el objeto MailMessage. El siguiente ejemplo de código muestra cómo crear y enviar un mensaje de correo electrónico usando la API Graph:

// 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 mensajes


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

Mover mensajes

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

Gestionar archivos adjuntos


// 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);

Administrar elementos de Outlook con Graph Client

Administrar eventos de calendario

Aspose.Email proporciona APIs para acceder, gestionar e interactuar con eventos de calendario. Para estos propósitos, ofrece los siguientes métodos en el IGraphClient interfaz:

  • ListCalendars() - Recupera una colección de información de calendarios.
  • ListCalendarItems(string id) - Recupera una colección de elementos de calendario asociados al ID de calendario especificado.
  • FetchCalendarItem(string id) - Recupera un elemento de calendario específico basado en el ID proporcionado.
  • CreateCalendarItem(string calId, MapiCalendar mapiCalendar) - Crea un nuevo elemento de calendario en el calendario especificado.
  • UpdateCalendarItem(MapiCalendar mapiCalendar) - Actualiza un elemento de calendario existente.
  • UpdateCalendarItem(MapiCalendar mapiCalendar, UpdateSettings updateSettings) - Actualiza un elemento de calendario existente con los ajustes de actualización especificados.

El siguiente ejemplo de código muestra cómo interactuar con eventos de calendario en un cliente de la API Microsoft Graph utilizando los métodos proporcionados por 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);

Administrar categorías

Para gestionar categorías con MS Graph mediante Aspose.Email para .NET, use los siguientes 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);

Administrar contactos

Aspose.Email proporciona APIs para acceder, gestionar e interactuar con elementos de contacto. Para estos propósitos, ofrece los siguientes métodos en el IGraphClient interfaz:

  • ListContacts(string id) - Recupera una colección de contactos MAPI asociados al ID de carpeta especificado.
  • FetchContact(string id) - Recupera un contacto específico basado en el ID de elemento proporcionado.
  • CreateContact(string folderId, MapiContact contact) - Crea un nuevo contacto en la carpeta especificada.
  • UpdateContact(MapiContact contact) - Actualiza un contacto existente.

El siguiente ejemplo de código muestra cómo interactuar con contactos en un cliente de la API Microsoft Graph utilizando los métodos proporcionados por 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);

Administrar anulaciones

Para gestionar anulaciones con MS Graph mediante Aspose.Email para .NET, use los siguientes 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);

Administrar reglas

Para gestionar reglas con MS Graph mediante Aspose.Email para .NET, use los siguientes 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;
}

Administrar cuadernos

Para gestionar cuadernos con MS Graph mediante Aspose.Email para .NET, use los siguientes 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();

Gestión de tareas en Microsoft Graph

Aspose.Email brinda a los desarrolladores APIs para acceder, gestionar e interactuar con tareas y listas de tareas de los usuarios usando los siguientes métodos del IGraphClient interfaz:

El siguiente ejemplo de código demuestra cómo administrar listas de tareas:

// 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");

El siguiente ejemplo de código demuestra cómo administrar tareas:

// 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);
Creando un proyecto en Azure Active Directory Admin Center Administrar carpetas de correo en Microsoft Graph (Aspose.Email)