Cómo usar GraphClient para Microsoft Graph

Trabajando con GraphClient

Microsoft Graph es una API REST para acceder a los datos de Microsoft 365. La implementación de Graph Client en Aspose.Email para .NET, permite acceder a Microsoft Graph desde nuestra API. En los siguientes ejemplos, crearemos una instancia de MS Graph Client y le proporcionaremos el token. A continuación, examinaremos los principales métodos para gestionar las carpetas, actualizarlas, copiarlas y eliminarlas. También se puede acceder a los mensajes, su contenido y sus archivos adjuntos o modificarlos con nuestro cliente MS Graph. La administración de categorías, reglas, libretas y anulaciones es una función ampliada de Microsoft Graph Client de Aspose.Email, que aprenderás con facilidad.

Crear objeto GraphClient

Create IGraphClient oponerse a realizar solicitudes contra el servicio. Después de tener un IGraphClient si está autenticado, puede empezar a hacer llamadas contra el servicio.

A GetClient el método requiere un ITokenProvider instancia de implementación como primer parámetro.

Para obtener el token usaremos Biblioteca de autenticación de Microsoft (MSAL) para.NET.

Los siguientes son los pasos para obtener el token de autorización.

• Cree una clase AccessParameters para almacenar las credenciales.
• Añada el Paquete nuget Microsoft.Identity.Client que contiene los archivos binarios de MSAL.NET.
• Implemente un ITokenProvidery cree un método que acepte los parámetros de acceso y utilice MSAL.NET para obtener un token de acceso.

Para conservar las credenciales, añada lo siguiente AccessParameters class:

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

Crea el GraphTokenProvider clase que implementa un ITokenProvider interfaz. Usa el Microsoft.Identity.Client biblioteca para obtener un token. Vea el ejemplo de dicha implementación:

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

A continuación, cree un AccessParameters instancia de clase:

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

Por último, crea un ITokenProvider instancia y llama a GetClient método. Pase el tokenProvider como primer parámetro y accessParams.TenantId como el segundo:

var tokenProvider = new GraphTokenProvider(accessParams);

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

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

Administrar carpetas

Listar carpetas

Llamando 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 type.

var folders = client.ListFolders();

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

Carpeta de actualización

Para crear una carpeta con MS Graph Client, utilice CreateFolder método. Obtendrás 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 carpeta

CopyFolder El método es el método clave para copiar el objeto de la 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 carpeta

Use MoveFolder el método se usa para mover la carpeta, acepta newParentID e ItemID. Delete 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

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

• List messages
• Fetch message
• Create message
• Send message
• CopyMessage message
• Move message
• CreateAttachment
• FetchAttachment
• DeleteAttachment
• ListAttachments

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

Listar los mensajes por fecha de envío

The OrderBy El método de la colección de la biblioteca le permite recuperar mensajes con diferentes órdenes de clasificación (ascendente y descendente) según la fecha en que se enviaron. El siguiente ejemplo de código muestra cómo ordenar los mensajes por 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;

Enumeración de mensajes con soporte de paginación mediante Graph Client

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

El ejemplo de código y los pasos siguientes muestran cómo recuperar mensajes de la carpeta Bandeja de entrada mediante funciones de paginación y filtrado.

1. En primer lugar, inicie el cliente.
2. A continuación, defina el número de elementos que se mostrarán por página, por ejemplo, 10.
3. Cree un filtro para recuperar solo los mensajes no leídos mediante el GraphQueryBuilder clase. El builder.isRead.equals (false) establece la condición para filtrar los mensajes no leídos.
4. Llame al ListMessages método en el objeto cliente, especificando la carpeta (Bandeja de entrada) 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 (PageInfo) devuelto contiene los mensajes recuperados de la página actual en la propiedad Items.
5. Cree un bucle que continúe hasta llegar a la última página (pageInfo.lastPage es falso). Los mensajes recuperados se agregan a la lista de mensajes existente mediante 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 mensaje

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 mensaje

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

msg.Recipients.Add("[e-mail]", "Sam", MapiRecipientType.MAPI_TO);

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

Enviar mensaje

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

msg.Recipients.Add("[e-mail]", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "[e-mail]");

// send message
client.Send(msg);

Enviar borrador de mensaje

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

msg.Recipients.Add("[e-mail]", "Sam", MapiRecipientType.MAPI_TO);
msg.SetProperty(KnownPropertyList.SenderName, "John");
msg.SetProperty(KnownPropertyList.SentRepresentingEmailAddress, "[e-mail]");

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

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

Enviar un mensaje EML

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

// prepare the message
var eml = new MailMessage
{
    From = "[e-mail]",
    To = "[e-mail], [e-mail]",
    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 mensaje

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

Mover mensaje

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

Administrar 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 los eventos del calendario

Aspose.Email proporciona API para acceder, administrar e interactuar con los eventos del calendario. Para estos fines, ofrece los siguientes métodos en el IGraphClient interface:

• ListCalendars() - Recupera una colección de información del calendario.

• ListCalendarItems (identificador de cadena) - Recupera una colección de elementos del calendario asociados al ID de calendario especificado.

• fetchCalendarItem (identificador de cadena) - Recupera un elemento de calendario específico en función del ID proporcionado.

• createCalendarItem (cadena calID, mapiCalendar mapiCalendar) - Crea un nuevo elemento de calendario en el calendario especificado.

• Actualizar elemento de calendario (MapiCalendar MapiCalendar) - Actualiza un elemento de calendario existente.

• Actualizar elemento de calendario (MapiCalendar, MapiCalendar, actualizar configuración, actualizar configuración) - Actualiza un elemento del calendario existente con la configuración de actualización especificada.

El siguiente ejemplo de código muestra cómo interactuar con los eventos del calendario en un cliente de la API de Microsoft Graph mediante 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 administrar categorías con MS Graph de Aspose.Email para.NET, utilice los siguientes métodos:

• CreateCategory
• FetchCategory
• ListCategories
• UpdateCategory

// 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 API para acceder, administrar e interactuar con los elementos de contacto. Para estos fines, ofrece los siguientes métodos en el IGraphClient interface:

• ListContacts (identificador de cadena) - Recupera una colección de contactos MAPI asociados al ID de carpeta especificado.

• fetchContact (identificador de cadena) - Recupera un contacto específico en función del identificador del artículo proporcionado.

• CreateContact (string folderId, mapiContact contact) - Crea un nuevo contacto en la carpeta especificada.

• UpdateContact (contacto de MapiContact) - Actualiza un contacto existente.

El siguiente ejemplo de código muestra cómo interactuar con los contactos en un cliente de la API de Microsoft Graph mediante 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", "[e-mail]", "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 las anulaciones con MS Graph de Aspose.Email para .NET, utilice los métodos siguientes:

• CreateOrUpdateOverride
• ListOverrides
• UpdateOverride

// Create an user's override
var userOverride = client.CreateOrUpdateOverride
    (new MailAddress("[e-mail]", "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 administrar las reglas con MS Graph de Aspose.Email para.NET, utilice los métodos siguientes:

• CreateRule
• FetchRule
• UpdateRule
• ListRules

// Create a rule
var rule = PrepareRule("[e-mail]", "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 administrar libretas con MS Graph de Aspose.Email para.NET, utilice los siguientes métodos:

• CreateNotebook
• CopyNotebook
• FetchNotebook
• ListNotebooks

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