Criar um conector personalizado do Microsoft Graph em C#

Artigo
11/07/2024

Este artigo descreve como utilizar o SDK do conector do Microsoft Graph para criar um conector personalizado em C#.

Pré-requisitos

Transfira, instale e conclua a configuração do agente do conector do Microsoft Graph.
Instale o Visual Studio 2019 ou posterior com o SDK .NET 7.0.
Transfira o ficheiro ApplianceParts.csv a partir do repositório de exemplo do conector personalizado.

Instale a extensão

Abra o Visual Studio e aceda a Extensões>Gerir extensões.
Procure a extensão GraphConnectorsTemplate e transfira-a.
Feche e reinicie o Visual Studio para instalar o modelo.
Aceda a Ficheiro>Novo>Projeto e procure GraphConnectorsTemplate. Selecione o modelo e selecione Seguinte.
Indique um nome para o projeto e selecione Seguinte.
Selecione .NET Core 3.1, dê o nome CustomConnector ao conector e selecione Criar.
O projeto de modelo de conector personalizado está agora criado.

Criar o conector personalizado

Antes de criar o conector, utilize os seguintes passos para instalar pacotes NuGet e criar os modelos de dados que serão utilizados.

Instalar pacotes NuGet

Clique com o botão direito do rato no projeto e selecione Abrir no Terminal.

Execute o seguinte comando:

dotnet add package CsvHelper --version 27.2.1

Criar modelos de dados

Crie uma pasta denominada Modelos em CustomConnector e crie um ficheiro com o nome AppliancePart.cs na pasta .

Cole o seguinte código no AppliancePart.cs.

using System;
using System.Collections.Generic;
using System.ComponentModel.DataAnnotations;
using System.Text;

namespace CustomConnector.Models
{
    public class AppliancePart
    {
        [Key]
        public int PartNumber { get; set; }
        public string Name { get; set; }
        public string Description { get; set; }
        public double Price { get; set; }
        public int Inventory { get; set; }
        public List<string> Appliances { get; set; }
    }
}

Atualizar ConnectionManagementServiceImpl.cs

Irá implementar três métodos no ConnectionManagementServiceImpl.cs.

ValidateAuthentication

O método ValidateAuthentication é utilizado para validar as credenciais e o URL da origem de dados fornecido. Tem de ligar ao URL da origem de dados com as credenciais fornecidas e devolver êxito se a ligação for bem-sucedida ou a falha de autenticação status se a ligação falhar.

Crie uma pasta denominada Dados em CustomConnector e crie um ficheiro CsvDataLoader.cs na pasta.

Copie o seguinte código para CsvDataLoader.cs:

using CsvHelper;
using CsvHelper.Configuration;
using CsvHelper.TypeConversion;

using CustomConnector.Models;

using System.Collections.Generic;
using System.Globalization;
using System.IO;

namespace CustomConnector.Data
{
    public static class CsvDataLoader
    {
        public static void ReadRecordFromCsv(string filePath)
        {
            using (var reader = new StreamReader(filePath))
            using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
            {
                csv.Context.RegisterClassMap<AppliancePartMap>();
                csv.Read();
            }
        }
    }

    public class ApplianceListConverter : DefaultTypeConverter
    {
        public override object ConvertFromString(string text, IReaderRow row, MemberMapData memberMapData)
        {
            var appliances = text.Split(';');
            return new List<string>(appliances);
        }
    }

    public class AppliancePartMap : ClassMap<AppliancePart>
    {
        public AppliancePartMap()
        {
            Map(m => m.PartNumber);
            Map(m => m.Name);
            Map(m => m.Description);
            Map(m => m.Price);
            Map(m => m.Inventory);
            Map(m => m.Appliances).TypeConverter<ApplianceListConverter>();
        }
    }
}

O método ReadRecordFromCsv abre o ficheiro CSV e lê o primeiro registo do ficheiro. Podemos utilizar este método para validar que o URL da origem de dados fornecido (caminho do ficheiro CSV) é válido. Este conector está a utilizar autenticação anónima; Por conseguinte, as credenciais não são validadas. Se o conector utilizar outro tipo de autenticação, a ligação à origem de dados tem de ser efetuada com as credenciais fornecidas para validar a autenticação.

Adicione a seguinte diretiva using no ConnectionManagementServiceImpl.cs.
```
using CustomConnector.Data;
```

Atualize o método ValidateAuthentication no ConnectionManagementServiceImpl.cs com o seguinte código para chamar o método ReadRecordFromCsv da classe CsvDataLoader .

public override Task<ValidateAuthenticationResponse> ValidateAuthentication(ValidateAuthenticationRequest request, ServerCallContext context)
{
    try
    {
        Log.Information("Validating authentication");
        CsvDataLoader.ReadRecordFromCsv(request.AuthenticationData.DatasourceUrl);
        return this.BuildAuthValidationResponse(true);
    }
    catch (Exception ex)
    {
        Log.Error(ex.ToString());
        return this.BuildAuthValidationResponse(false, "Could not read the provided CSV file with the provided credentials");
    }
}

ValidateCustomConfiguration

O método ValidateCustomConfiguration é utilizado para validar quaisquer outros parâmetros necessários para a ligação. O conector que está a criar não requer parâmetros adicionais; por conseguinte, o método valida que os parâmetros adicionais estão vazios.

Atualize o método ValidateCustomConfiguration no ConnectionManagementServiceImpl.cs com o seguinte código.

public override Task<ValidateCustomConfigurationResponse> ValidateCustomConfiguration(ValidateCustomConfigurationRequest request, ServerCallContext context)
{
    Log.Information("Validating custom configuration");
    ValidateCustomConfigurationResponse response;

    if (!string.IsNullOrWhiteSpace(request.CustomConfiguration.Configuration))
    {
        response = new ValidateCustomConfigurationResponse()
        {
            Status = new OperationStatus()
            {
                Result = OperationResult.ValidationFailure,
                StatusMessage = "No additional parameters are required for this connector"
            },
        };
    }
    else
    {
        response = new ValidateCustomConfigurationResponse()
        {
            Status = new OperationStatus()
            {
                Result = OperationResult.Success,
            },
        };
    }

    return Task.FromResult(response);
}

GetDataSourceSchema

O método GetDataSourceSchema é utilizado para obter o esquema do conector.

Adicione as seguintes diretivas de utilização no AppliancePart.cs.

using Microsoft.Graph.Connectors.Contracts.Grpc;
using static Microsoft.Graph.Connectors.Contracts.Grpc.SourcePropertyDefinition.Types;

Adicione o seguinte método GetSchema na classe AppliancePart.cs.

public static DataSourceSchema GetSchema()
{
    DataSourceSchema schema = new DataSourceSchema();

    schema.PropertyList.Add(
        new SourcePropertyDefinition
        {
            Name = nameof(PartNumber),
            Type = SourcePropertyType.Int64,
            DefaultSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
            RequiredSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
        });

    schema.PropertyList.Add(
        new SourcePropertyDefinition
        {
            Name = nameof(Name),
            Type = SourcePropertyType.String,
            DefaultSearchAnnotations = (uint)(SearchAnnotations.IsSearchable | SearchAnnotations.IsRetrievable),
            RequiredSearchAnnotations = (uint)(SearchAnnotations.IsSearchable | SearchAnnotations.IsRetrievable),
        });

    schema.PropertyList.Add(
        new SourcePropertyDefinition
        {
            Name = nameof(Price),
            Type = SourcePropertyType.Double,
            DefaultSearchAnnotations = (uint)(SearchAnnotations.IsRetrievable),
            RequiredSearchAnnotations = (uint)(SearchAnnotations.IsRetrievable),
        });

    schema.PropertyList.Add(
        new SourcePropertyDefinition
        {
            Name = nameof(Inventory),
            Type = SourcePropertyType.Int64,
            DefaultSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
            RequiredSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
        });

    schema.PropertyList.Add(
        new SourcePropertyDefinition
        {
            Name = nameof(Appliances),
            Type = SourcePropertyType.StringCollection,
            DefaultSearchAnnotations = (uint)(SearchAnnotations.IsSearchable | SearchAnnotations.IsRetrievable),
            RequiredSearchAnnotations = (uint)(SearchAnnotations.IsSearchable | SearchAnnotations.IsRetrievable),
        });

    schema.PropertyList.Add(
        new SourcePropertyDefinition
        {
            Name = nameof(Description),
            Type = SourcePropertyType.String,
            DefaultSearchAnnotations = (uint)(SearchAnnotations.IsSearchable | SearchAnnotations.IsRetrievable),
            RequiredSearchAnnotations = (uint)(SearchAnnotations.IsSearchable | SearchAnnotations.IsRetrievable),
        });

    return schema;
}

Observação

A propriedade RequiredSearchAnnotations marca as anotações de propriedade como obrigatórias e inalteráveis durante a configuração do conector. O exemplo anterior define todas as propriedades como pesquisáveis e recuperáveis de forma obrigatória; no entanto, pode optar por não definir RequiredSearchAnnotations numa ou mais propriedades.
A propriedade DefaultSearchAnnotations marca as anotações de propriedade como predefinição, mas podem ser alteradas durante a configuração do conector.

Adicione a seguinte diretiva using no ConnectionManagementServiceImpl.cs.
```
using CustomConnector.Models;
```

Atualize o método GetDataSourceSchema no ConnectionManagementServiceImpl.cs com o seguinte código.

public override Task<GetDataSourceSchemaResponse> GetDataSourceSchema(GetDataSourceSchemaRequest request, ServerCallContext context)
{
    Log.Information("Trying to fetch datasource schema");

    var opStatus = new OperationStatus()
    {
        Result = OperationResult.Success,
    };

    GetDataSourceSchemaResponse response = new GetDataSourceSchemaResponse()
    {
        DataSourceSchema = AppliancePart.GetSchema(),
        Status = opStatus,
    };

    return Task.FromResult(response);
}

Atualizar ConnectorCrawlerServiceImpl.cs

Esta classe tem os métodos que são chamados pela plataforma durante as pesquisas.

O método GetCrawlStream é chamado durante as pesquisas completas ou periódicas completas.

Adicione a seguinte diretiva using no AppliancePart.cs.
```
using System.Globalization;
```

Adicione os seguintes métodos no AppliancePart.cs para converter o registo AppliancePart em CrawlItem.

public CrawlItem ToCrawlItem()
{
    return new CrawlItem
    {
        ItemType = CrawlItem.Types.ItemType.ContentItem,
        ItemId = this.PartNumber.ToString(CultureInfo.InvariantCulture),
        ContentItem = this.GetContentItem(),
    };
}

private ContentItem GetContentItem()
{
    return new ContentItem
    {
        AccessList = this.GetAccessControlList(),
        PropertyValues = this.GetSourcePropertyValueMap()
    };
}

private AccessControlList GetAccessControlList()
{
    AccessControlList accessControlList = new AccessControlList();
    accessControlList.Entries.Add(this.GetAllowEveryoneAccessControlEntry());
    return accessControlList;
}

private AccessControlEntry GetAllowEveryoneAccessControlEntry()
{
    return new AccessControlEntry
    {
        AccessType = AccessControlEntry.Types.AclAccessType.Grant,
        Principal = new Principal
        {
            Type = Principal.Types.PrincipalType.Everyone,
            IdentitySource = Principal.Types.IdentitySource.AzureActiveDirectory,
            IdentityType = Principal.Types.IdentityType.AadId,
            Value = "EVERYONE",
        }
    };
}

private SourcePropertyValueMap GetSourcePropertyValueMap()
{
    SourcePropertyValueMap sourcePropertyValueMap = new SourcePropertyValueMap();

    sourcePropertyValueMap.Values.Add(
        nameof(this.PartNumber),
        new GenericType
        {
            IntValue = this.PartNumber,
        });

    sourcePropertyValueMap.Values.Add(
        nameof(this.Name),
        new GenericType
        {
            StringValue = this.Name,
        });

    sourcePropertyValueMap.Values.Add(
        nameof(this.Price),
        new GenericType
        {
            DoubleValue = this.Price,
        });

    sourcePropertyValueMap.Values.Add(
        nameof(this.Inventory),
        new GenericType
        {
            IntValue = this.Inventory,
        });

    var appliancesPropertyValue = new StringCollectionType();
    foreach(var property in this.Appliances)
    {
        appliancesPropertyValue.Values.Add(property);
    }
    sourcePropertyValueMap.Values.Add(
        nameof(this.Appliances),
        new GenericType
        {
            StringCollectionValue = appliancesPropertyValue,
        });

    sourcePropertyValueMap.Values.Add(
        nameof(this.Description),
        new GenericType
        {
            StringValue = Description,
        });

    return sourcePropertyValueMap;
}

Adicione a seguinte diretiva using no CsvDataLoader.cs.
```
using Microsoft.Graph.Connectors.Contracts.Grpc;
```

Adicione o seguinte método no CsvDataLoader.cs.

public static IEnumerable<CrawlItem> GetCrawlItemsFromCsv(string filePath)
{
    using (var reader = new StreamReader(filePath))
    using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
    {
        csv.Context.RegisterClassMap<AppliancePartMap>();

        // The GetRecords<T> method returns an IEnumerable<T> that yields records. This means that only one record is returned at a time as you iterate the records.
        foreach (var record in csv.GetRecords<AppliancePart>())
        {
            yield return record.ToCrawlItem();
        }
    }
}

Adicione a seguinte diretiva using no ConnectorCrawlerServiceImpl.cs.
```
using CustomConnector.Data;
```

Adicione o seguinte método no ConnectorCrawlerServiceImpl.cs.

private CrawlStreamBit GetCrawlStreamBit(CrawlItem crawlItem)
{
    return new CrawlStreamBit
    {
        Status = new OperationStatus
        {
            Result = OperationResult.Success,
        },
        CrawlItem = crawlItem,
        CrawlProgressMarker = new CrawlCheckpoint
        {
            CustomMarkerData = crawlItem.ItemId,
        },
    };
}

Atualize o método GetCrawlStream para o seguinte.

public override async Task GetCrawlStream(GetCrawlStreamRequest request, IServerStreamWriter<CrawlStreamBit> responseStream, ServerCallContext context)
{
    try
    {
        Log.Information("GetCrawlStream Entry");
        var crawlItems = CsvDataLoader.GetCrawlItemsFromCsv(request.AuthenticationData.DatasourceUrl);
        foreach (var crawlItem in crawlItems)
        {
            CrawlStreamBit crawlStreamBit = this.GetCrawlStreamBit(crawlItem);
            await responseStream.WriteAsync(crawlStreamBit).ConfigureAwait(false);
        }
    }
    catch (Exception ex)
    {
        Log.Error(ex.ToString());
        CrawlStreamBit crawlStreamBit = new CrawlStreamBit
        {
            Status = new OperationStatus
            {
                Result = OperationResult.DatasourceError,
                StatusMessage = "Fetching items from datasource failed",
                RetryInfo = new RetryDetails
                {
                    Type = RetryDetails.Types.RetryType.Standard,
                },
            },
        };
        await responseStream.WriteAsync(crawlStreamBit).ConfigureAwait(false);
    }
}

Agora, o conector é criado e pode compilar e executar o projeto.

Próximas etapas

Testar seu conector

Compartilhar via