Configurar uma ligação externa e implementar o esquema

Concluído

Nesta unidade, vai aprender a configurar um registo de aplicações Microsoft Entra para utilização com um conector personalizado do Graph. Também irá aprender a criar uma ligação externa e a configurar um esquema para importar conteúdo externo.

Configurar Microsoft Entra registo de aplicações

Para importar conteúdo externo para o Microsoft 365, um conector do Graph precisa de uma ligação externa e de um esquema. Um conector personalizado do Graph utiliza as APIs do Microsoft Graph para criar a ligação externa e implementar o esquema. Para comunicar com as Graph APIs, é autenticado com o Microsoft 365 através de uma Microsoft Entra registo de aplicações. Normalmente, os conectores do Graph são aplicações que são executadas sem interação do utilizador. Para permitir que os conectores criem a ligação, implementem o esquema e ingeram conteúdo externo, conceda-lhes as seguintes permissões de aplicação:

• ExternalConnection.ReadWrite.OwnedBy – que permite ao conector criar a ligação e implementar o esquema,
• ExternalItem.ReadWrite.OwnedBy – que permite ao conector ingerir itens externos

Ambas as permissões permitem que o conector aceda apenas à ligação e aos itens que possui, que é a prática de segurança recomendada.

Criar uma ligação externa

Um conector personalizado do Graph cria uma ligação externa com o ponto final ligação externa do Microsoft Graph. Ao criar uma ligação, tem de especificar o respetivo ID, nome e descrição. O ID tem de ser exclusivo no seu inquilino do Microsoft 365 e ter entre 3 e 32 carateres. O fragmento de código seguinte mostra como criar uma ligação externa:

using Microsoft.Graph.Models.ExternalConnectors;

var requestBody = new ExternalConnection
{
  Id = "msgraphdocs",
  Name = "Microsoft Graph documentation",
  Description = "Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.",
};

await graphClient.External.Connections.PostAsync(requestBody);

Implementar o esquema

Depois de criar uma ligação externa, o passo seguinte é implementar o esquema. O esquema consiste numa ou mais propriedades. Para cada propriedade, tem de especificar o respetivo nome e tipo de dados que armazena. Também pode definir se os respetivos dados devem ser utilizados para pesquisa e ordenação em texto completo. Por fim, pode adicionar uma ou mais etiquetas semânticas que ajudam o Microsoft 365 a compreender as informações que a propriedade representa. Microsoft 365 Copilot requer uma ligação externa para definir no respetivo esquema, pelo menos, o título, o URL e as etiquetas semânticas iconUrl. O fragmento de código seguinte mostra como implementar um esquema:

using Microsoft.Graph.Models.ExternalConnectors;

var schema = new Schema
{
  BaseType = "microsoft.graph.externalItem",
  Properties = new()
  {
    new Property
    {
      Name = "title",
      Type = PropertyType.String,
      IsQueryable = true,
      IsSearchable = true,
      IsRetrievable = true,
      Labels = new() { Label.Title }
    },
    new Property
    {
      Name = "iconUrl",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.IconUrl }
    },
    new Property
    {
      Name = "url",
      Type = PropertyType.String,
      IsRetrievable = true,
      Labels = new() { Label.Url }
    },
  }
};

await graphClient.External
  .Connections["{externalConnection-id}"]
  .Schema
  .PatchAsync(schema);

A implementação de um esquema de ligação externa é uma operação de execução prolongada que demora entre 5 e 15 minutos. Para saber quando o aprovisionamento está concluído e a ligação está pronta a ser utilizada, obtenha informações sobre a ligação e marcar o respetivo status. Se a ligação ainda não estiver pronta, aguarde 1 minuto antes de verificar a status novamente.

do {
  var externalConnection = await GraphService.Client.External
    .Connections["{externalConnection-id}"]
    .GetAsync();

  if (externalConnection?.State != ConnectionState.Draft)
  {
    break;
  }

  await Task.Delay(60_000);
}
while (true);