Configurer une connexion externe et déployer un schéma

  • 3 minutes

Dans cette unité, vous allez apprendre à configurer une inscription d’application Microsoft Entra pour une utilisation avec un connecteur Graph personnalisé. Vous apprenez également à créer une connexion externe et à configurer un schéma pour l’importation de contenu externe.

Configurer l’inscription de l’application Microsoft Entra

Pour importer du contenu externe dans Microsoft 365, un connecteur Graph a besoin d’une connexion externe et d’un schéma. Un connecteur Graph personnalisé utilise des API Microsoft Graph pour créer la connexion externe et déployer le schéma. Pour communiquer avec les API Graph, il s’authentifie auprès de Microsoft 365 à l’aide d’une inscription d’application Microsoft Entra. En règle générale, les connecteurs Graph sont des applications qui s’exécutent sans interaction utilisateur. Pour permettre aux connecteurs de créer la connexion, de déployer le schéma et d’ingérer du contenu externe, vous leur accordez les autorisations d’application suivantes :

  • ExternalConnection.ReadWrite.OwnedBy : qui permet au connecteur de créer la connexion et de déployer le schéma,
  • ExternalItem.ReadWrite.OwnedBy : qui permet au connecteur d’ingérer des éléments externes

Les deux autorisations permettent au connecteur d’accéder uniquement à la connexion et aux éléments qu’il possède, ce qui est la pratique de sécurité recommandée.

Créer une connexion externe

Un connecteur Graph personnalisé crée une connexion externe à l’aide du point de terminaison Microsoft Graph connexion externe. Lors de la création d’une connexion, vous devez spécifier son ID, son nom et sa description. L’ID doit être unique dans votre client Microsoft 365 et comporter entre 3 et 32 caractères. L’extrait de code suivant montre comment créer une connexion externe :

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

Déployer le schéma

Après avoir créé une connexion externe, l’étape suivante consiste à déployer le schéma. Le schéma se compose d’une ou plusieurs propriétés. Pour chaque propriété, vous devez spécifier son nom et son type de données qu’elle stocke. Vous pouvez également définir si ses données doivent être utilisées pour la recherche et le tri en texte intégral. Enfin, vous pouvez ajouter une ou plusieurs étiquettes sémantiques qui aident Microsoft 365 à comprendre les informations que la propriété représente. Copilot pour Microsoft 365 nécessite une connexion externe pour définir dans son schéma au moins les étiquettes sémantiques title, URL et iconUrl . L’extrait de code suivant montre comment déployer un schéma :

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

Le déploiement d’un schéma de connexion externe est une opération de longue durée qui prend entre 5 et 15 minutes. Pour savoir quand l’approvisionnement est terminé et que la connexion est prête à être utilisée, récupérez des informations sur la connexion et vérifiez son état. Si la connexion n’est pas encore prête, attendez 1 minute avant de vérifier à nouveau son état.

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

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

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