Configuración de una conexión externa e implementación del esquema

Completado

En esta unidad, aprenderá a configurar un registro de aplicación de Microsoft Entra para usarlo con un conector de Graph personalizado. También aprenderá a crear una conexión externa y a configurar un esquema para importar contenido externo.

Configuración del registro de Microsoft Entra aplicación

Para importar contenido externo a Microsoft 365, un conector de Graph necesita una conexión externa y un esquema. Un conector de Graph personalizado usa las API de Microsoft Graph para crear la conexión externa e implementar el esquema. Para comunicarse con las API de Graph, se autentica con Microsoft 365 mediante un registro de aplicación Microsoft Entra. Normalmente, los conectores de Graph son aplicaciones que se ejecutan sin interacción del usuario. Para permitir que los conectores creen la conexión, implementen el esquema e ingieren contenido externo, debe concederles los siguientes permisos de aplicación:

• ExternalConnection.ReadWrite.OwnedBy : que permite al conector crear la conexión e implementar el esquema,
• ExternalItem.ReadWrite.OwnedBy : que permite al conector ingerir elementos externos

Ambos permisos permiten que el conector solo acceda a la conexión y a los elementos que posee, que es la práctica de seguridad recomendada.

Creación de una conexión externa

Un conector de Graph personalizado crea una conexión externa mediante el punto de conexión externo de Microsoft Graph. Al crear una conexión, debe especificar su identificador, nombre y descripción. El identificador debe ser único en el inquilino de Microsoft 365 y tener entre 3 y 32 caracteres. El siguiente fragmento de código muestra cómo crear una conexión 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);

Implementación del esquema

Después de crear una conexión externa, el siguiente paso es implementar el esquema. El esquema consta de una o varias propiedades. Para cada propiedad, debe especificar su nombre y tipo de datos que almacena. También puede definir si sus datos deben usarse para la búsqueda y ordenación de texto completo. Por último, puede agregar una o varias etiquetas semánticas que ayuden a Microsoft 365 a comprender qué información representa la propiedad. Microsoft 365 Copilot requiere una conexión externa para definir en su esquema al menos las etiquetas semánticas title, url e iconUrl. El siguiente fragmento de código muestra cómo implementar un 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);

La implementación de un esquema de conexión externa es una operación de larga duración que tarda entre 5 y 15 minutos. Para saber cuándo finaliza el aprovisionamiento y la conexión está lista para usarse, recupere información sobre la conexión y compruebe su estado. Si la conexión aún no está lista, espere 1 minuto antes de comprobar de nuevo su estado.

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

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

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