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

8 minutes

Dans cet exercice, vous créez un connecteur Microsoft Graph personnalisé en tant qu’application console. Vous inscrivez une nouvelle Microsoft Entra’inscription d’application et ajoutez le code pour créer une connexion externe et déployer son schéma.

Créer un projet de connecteur Graph

Commencez par créer un projet de connecteur Graph. Bien que vous puissiez créer le projet et tous les fichiers nécessaires manuellement, dans cet exemple, vous utilisez le référentiel GitHub de modèle pour les connecteurs Graph. L’avantage de l’utilisation du référentiel de modèles est qu’il crée un projet simple avec les fichiers et les dépendances nécessaires, ce qui vous fait gagner du temps.

Dans une ligne de commande :

Cloner le référentiel de modèles en exécutant git clone https://github.com/microsoft/learn-microsoft-graph-connectors-dotnet.git

Conseil

Si git n’est pas installé ou si vous n’avez pas de compte GitHub, vous pouvez télécharger le dépôt sous forme de fichier ZIP. Extrayez le fichier ZIP dans un dossier sur votre ordinateur pour poursuivre l’exercice.
Remplacez le répertoire de travail par le référentiel cloné.
Ouvrez le projet nouvellement créé dans votre éditeur de code.

Dans l’éditeur de code :

Ouvrez le fichier ConnectionConfiguration.cs . Dans l’objet retourné par le ExternalConnection getter :
1. Remplacez la valeur de la propriété Id par msgraphdocs.
2. Remplacez la valeur de la propriété Name par Microsoft Graph documentation.
3. Remplacez la valeur de la propriété Description par Documentation for Microsoft Graph API which explains what Microsoft Graph is and how to use it.
Enregistrez vos modifications.

Conseil

Le README.md fichier dans le projet généré contient plus d’informations sur les différents fichiers et dossiers du projet. Prenez un moment pour le lire et vous familiariser avec la structure du projet.

Inscrire une nouvelle inscription d’application Microsoft Entra

Le projet que vous avez créé contient un script d’installation qui crée et configure une inscription d’application Microsoft Entra. Le connecteur Graph utilise cette inscription d’application pour s’authentifier auprès de Microsoft 365.

Dans une ligne de commande :

Remplacez le répertoire de travail par le dossier du projet.
Exécutez le script d’installation : .\setup.ps1
Lorsque vous y êtes invité, connectez-vous à votre client Microsoft 365 avec votre compte professionnel.
Attendez que le script termine la création de l’inscription de l’application. Le script crée une inscription d’application Entra nommée documentation Microsoft Graph.
Une fois le script terminé, il stocke en toute sécurité les informations d’inscription de l’application dans les secrets utilisateur.

Le script d’installation utilise le Kit de développement logiciel (SDK) Microsoft Graph PowerShell pour créer une inscription d’application Microsoft Entra dans votre locataire. Il configure l’inscription de l’application avec Microsoft API Graph autorisations requises pour créer une connexion externe et ingérer du contenu. Il configure également l’inscription de l’application avec un secret pour permettre l’authentification sans interaction de l’utilisateur.

Conseil

Pour explorer la configuration de l’inscription d’application, dans un navigateur web :

Accédez au portail Azure à l’adresse https://portal.azure.com.
Dans le volet de navigation, sélectionnez Microsoft Entra ID.
Dans la navigation latérale, sélectionnez inscriptions d'applications.
Dans la liste des inscriptions d’applications, sélectionnez l’inscription d’application créée par le script d’installation.
Explorez les différentes propriétés, telles que les autorisations d’API, les certificats & secrets et l’authentification.

Définir la connexion externe et la configuration du schéma

L’étape suivante consiste à définir la connexion externe et le schéma que le connecteur Graph doit utiliser. Étant donné que le code du connecteur a besoin d’accéder à l’ID de la connexion externe à plusieurs endroits, stockez-le dans un emplacement central dans votre code.

Dans l’éditeur de code :

Ouvrez le fichier ConnectionConfiguration.cs .
À partir de l’objet retourné par la ExternalConnection propriété , supprimez les ActivitySettings propriétés et SearchSettings . Vous n’en avez pas besoin pour cet exercice.
Notez les propriétés de schéma retournées par la Schema propriété .

La première propriété est title, qui stocke le titre de l’élément externe importé dans Microsoft 365. Le titre de l’élément fait partie de l’index de recherche en texte intégral (IsSearchable = true). Les utilisateurs peuvent également interroger explicitement son contenu dans mot clé requêtes (IsQueryable = true). Le titre peut également être récupéré et affiché dans les résultats de la recherche (IsRetrievable = true). La title propriété représente le titre de l’élément, que vous indiquez à l’aide de l’étiquette Title sémantique.

Ensuite, il y a la url propriété , qui stocke l’URL d’origine de l’élément externe. Les utilisateurs utilisent cette URL pour accéder à l’élément externe à partir des résultats de recherche ou à Copilot à partir de Microsoft 365. URL est l’une des propriétés requises par Microsoft 365 Copilot, c’est pourquoi vous la mappez à l’aide de l’étiquette Url sémantique.

Enfin, il y a la iconUrl propriété qui stocke l’URL de l’icône pour chaque élément. Microsoft 365 Copilot requiert cette propriété et elle doit être mappée à l’aide de l’étiquette IconUrl sémantique.

Microsoft 365 Copilot nécessite que les connecteurs Graph définissent au moins ces trois propriétés et les désignent avec les étiquettes sémantiques appropriées.
Properties Au tableau, ajoutez une nouvelle propriété nommée description:
```
new Property
{
  Name = "description",
  Type = PropertyType.String,
  IsQueryable = true,
  IsSearchable = true,
  IsRetrievable = true
}
```
La description propriété stocke le résumé du contenu de l’élément externe. Sa définition est similaire au titre. Toutefois, il n’existe pas d’étiquette sémantique pour la description, c’est pourquoi vous ne la définissez pas.

Le code complet se présente comme suit :

using System.Text.Json;
using Microsoft.Graph.Models;
using Microsoft.Graph.Models.ExternalConnectors;

static class ConnectionConfiguration
{
  private static Dictionary<string, object>? _layout;
  private static Dictionary<string, object> Layout
  {
    get
    {
      if (_layout is null)
      {
        var adaptiveCard = File.ReadAllText("resultLayout.json");
        _layout = JsonSerializer.Deserialize<Dictionary<string, object>>(adaptiveCard);
      }

      return _layout!;
    }
  }

  public static ExternalConnection ExternalConnection
  {
    get
    {
      return 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."
      };
    }
  }

  public static Schema Schema
  {
    get
    {
      return 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 = "url",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.Url }
          },
          new Property
          {
            Name = "iconUrl",
            Type = PropertyType.String,
            IsRetrievable = true,
            Labels = new() { Label.IconUrl }
          },
          new Property
          {
            Name = "description",
            Type = PropertyType.String,
            IsQueryable = true,
            IsSearchable = true,
            IsRetrievable = true
          }
        }
      };
    }
  }
}

Save your changes

Passer en revue le code de création de connexion

Le générateur de projet de connecteur Graph crée du code qui crée la connexion externe et provisionne son schéma. Vous pouvez l’utiliser sans aucune modification. Avant de le faire, jetez un coup d’œil pour comprendre comment il fonctionne. Le code se trouve dans le fichier ConnectionService.cs .

Dans l’éditeur de code :

Ouvrez le fichier ConnectionService.cs .
Le fichier contient deux méthodes : CreateConnection et CreateSchema. La CreateConnection méthode crée la connexion externe et la CreateSchema méthode provisionne le schéma.

Si vous vous souvenez, le provisionnement du schéma de connexion externe est une opération de longue durée. Toutefois, le code de la CreateSchema méthode ne semble pas attendre que le schéma soit provisionné. Le client Microsoft Graph dans ce projet utilise un intergiciel personnalisé qui attend la fin de l’opération. Étant donné que ce middleware gère l’attente de la fin de l’opération, la CreateSchema fonction n’a pas besoin d’inclure d’autre code et doit uniquement attendre la demande d’API. Le middleware se trouve dans le fichier CompleteJobWithDelayHandler.cs .

Test du code

La dernière étape à gauche consiste à vérifier que le code fonctionne correctement. Le fichier Program.cs contient le point d’entrée de l’application. Il utilise le package System.CommandLine pour définir une commande que vous appelez en démarrant l’application à partir de la ligne de commande.

Dans une ligne de commande :

Ouvrez un terminal de console.
Remplacez le répertoire de travail par le dossier du projet.
Exécutez dotnet build pour générer le projet.
Démarrez l’application en exécutant dotnet run -- create-connection.
Attendez plusieurs minutes que la connexion et le schéma soient créés.

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

Créer un projet de connecteur Graph

Inscrire une nouvelle inscription d’application Microsoft Entra

Définir la connexion externe et la configuration du schéma

Passer en revue le code de création de connexion

Test du code

Commentaires