Créer, mettre à jour et supprimer des connexions dans Microsoft Graph

La plateforme de connecteurs Microsoft Graph offre un moyen intuitif d’ajouter vos données externes dans Microsoft Graph. Une connexion est un conteneur logique pour vos données externes qu’un administrateur peut gérer comme une seule entité.

Une fois qu’une connexion a été créée, vous pouvez ajouter votre contenu à partir de n’importe quelle source de données externe, telle qu’une source de contenu locale ou un service SaaS externe. Vous pouvez uniquement afficher et gérer les connexions que vous avez créées ou que vous avez explicitement autorisées à gérer. Un administrateur de recherche peut afficher et gérer toutes les connexions du client à partir du Centre d’administration moderne.

Exemple de système de support personnalisé Structure du connecteur de tickets.

Vue d’administration des connexions, y compris le connecteur tickets personnalisés.

Vous pouvez modéliser une connexion comme vous le souhaitez, mais la création d’une connexion pour chaque instance de votre connecteur est le modèle le plus courant. Par exemple, chaque fois que vous configuré le connecteur partage de fichiers Microsoft Windows, une nouvelle connexion est créée. Vous pouvez également créer une connexion unique pour ajouter tous les éléments de votre source de données. Par exemple, vous pouvez créer une connexion unique pour ajouter tous les tickets et incidents entre plusieurs équipes à partir de votre système de support technique.

États et opérations

Votre connexion peut se trouver dans l’un des états suivants.

État	Description
Brouillon	Une connexion vide est configurée. Aucune source de données, schéma ou paramètres n’est configuré.
Prêt	La connexion est configurée à l’aide du schéma inscrit et est prête pour l’acquisition.
Obsolète	Ce problème se produit lorsqu’une fonctionnalité dépendante, telle qu’une API, a été déconseillée. La suppression de la connexion est la seule opération valide.
LimitExceeded	Si vous atteignez la limite maximale d’une seule connexion ou le quota au niveau du locataire sur toutes les connexions, vous ne pouvez pas ajouter d’éléments tant que vous n’avez pas quitté l’état.

Le tableau suivant indique les opérations disponibles dans chaque état.

Opération	Brouillon	Prêt	Obsolète	LimitExceeded
Créer une connexion	❌	✔️	❌	✔️
Lire la connexion	✔️	✔️	✔️	✔️
Mettre à jour une connexion	✔️	✔️	❌	✔️
Supprimer une connexion	✔️	✔️	✔️	✔️
Créer un schéma	✔️	❌	❌	❌
Lire un schéma	❌	✔️	✔️	✔️
Mettre à jour un schéma	❌	❌	❌	❌
Supprimer un schéma	❌	❌	❌	❌
Créer un élément	❌	✔️	❌	❌
Lire un élément	❌	✔️	✔️	✔️
Mettre à jour un élément	❌	✔️	❌	✔️
Supprimer un élément	❌	✔️	❌	✔️

Une connexion permet à votre application de définir un schéma pour les éléments qui seront indexés et fournit un point de terminaison pour votre service pour ajouter, mettre à jour ou supprimer des éléments dans l’index.

La première étape pour qu’une application ajoute des éléments à l’index de recherche consiste à créer une connexion.

Créer une connexion

Avant qu’une application puisse ajouter des éléments à l’index de recherche, elle doit créer et configurer une connexion :

1. Créez une connexion avec un ID unique, un nom complet et une description.
2. Enregistrez un schéma pour définir les champs à inclure dans l’index.

   Note: Pour plus d’informations sur la mise à jour du schéma pour une connexion existante, consultez Fonctionnalités de mise à jour de schéma.

Paramètres de connexion

Vous pouvez configurer les paramètres de connexion par défaut pour chaque expérience de contenu activée. Lorsqu’ils sont activés, ces paramètres affectent les expériences de contenu.

Paramètres de recherche

Vous pouvez définir la façon dont les résultats de la recherche sont affichés dans la page de résultats microsoft Recherche en fournissant les modèles d’affichage de recherche par défaut pour votre contenu dans searchSettings. Un ensemble de modèles d’affichage de recherche peut être utilisé pour afficher différents types de résultats de recherche différemment. Un modèle d’affichage de recherche a une disposition des résultats générée à l’aide de cartes adaptatives et de règles qui spécifient une ou plusieurs conditions. Lorsque ces conditions sont remplies, la disposition est appliquée au résultat de la recherche et affichée sur la page de résultats.

Paramètres d’activité

Dans les paramètres d’activité, vous pouvez fournir aux applications Microsoft 365 un moyen de détecter l’activité de partage, ce qui permet de recommander votre contenu aux utilisateurs qui interagissent le plus avec ce contenu. Pour ce faire, ajoutez un urlToItemResolver. Cela permet de résoudre une URL de la connexion détectée dans les applications Microsoft 365 à son ID d’élément respectif sur l’élément externalItem.

L’image suivante montre comment votre élément peut apparaître dans les expériences de recommandation dans Microsoft 365.

L’exemple suivant montre la charge utile activitySettings avec une section urlToItemResolvers complète. Par exemple, quand quelqu’un partage le lien https://contoso.com/items/39483948/, il représente un externalItem qui a été ingéré via une connexion Microsoft Graph. Dans cet exemple, le lien partagé représente un externalItem avec un itemId de id_39483948. Cette connexion spécifie comment mapper de l’URL à l’itemId de cet élément externe. Dans cet exemple, cette connexion a un ID de contosohr.

Mettez à jour les paramètres d’activité en envoyant une demande de correctif sur la connexion.

PATCH https://graph.microsoft.com/v1.0/external/connections/contosohr

La charge utile activitySettings suivante est envoyée avec la demande de correctif.

{
  "@odata.type": "#microsoft.graph.externalConnectors.activitySettings",
  "urlToItemResolvers": [
    {
        "@odata.type": "#microsoft.graph.externalConnectors.itemIdResolver",
          "itemId": "id_{myItemId}",  
          "priority": 1,
          "urlMatchInfo": {
            "@odata.type": "microsoft.graph.externalConnectors.urlMatchInfo",
            "baseUrls": [
              "https://contoso.com"
            ],
            "urlPattern": "/items/(?<myItemId>[0-9]+)"
          }
    }
  ]
}

Dans cet exemple, le champ itemId a spécifié comment former l’ID de l’élément externe représenté par l’URL. L’itemId est référencé dans urlPattern (qui se trouve dans urlMatchInfo) à extraire 39483948 en tant qu’ID de l’objet externalItem.

Vous pouvez fournir une liste de jusqu’à huit ressources itemIdResolver dans la ressource urlToItemResolvers pour la charge utile de vos paramètres d’activité. Pour chacune de ces ressources urlMatchInfo , spécifiez une valeur de #microsoft.graph.externalConnectors.itemIdResolver pour , @odata.typeun entier de un à huit pour la propriété de priorité et un objet urlMatchInfo qui contient une liste d’URL de base et une expression régulière.

Lorsqu’un lien est partagé, les objets urlMatchInfo qui appartiennent aux programmes de résolution sont appliqués dans l’ordre spécifié par les valeurs de priorité . Dans l’ordre de priorité croissant, l’URL est d’abord comparée aux URL de la liste baseUrls dans la propriété urlMatchInfo . Ensuite, si la base de l’URL de lien se trouve dans la liste baseUrls , l’expression régulière urlPattern est appliquée à l’URL. Si ce modèle correspond, aucun autre programme de résolution n’est appliqué. Si la base de l’URL de lien ne figure pas dans la liste baseUrls ou si urlPattern ne correspond pas, l’urlToItemResolver suivant est évalué jusqu’à ce qu’une correspondance soit trouvée ou qu’il n’y a plus de ressources urltoItemResolver à appliquer.

Pour en savoir plus sur les ressources urlMatchInfo , consultez type urlMatchInfo.

Mettre à jour une connexion

Pour modifier le nom d’affichage, la description ou les expériences de contenu activées pour une connexion existante, vous pouvez mettre à jour la connexion.

Supprimer une connexion

Pour supprimer tous les éléments indexés via une connexion, vous pouvez supprimer une connexion.

Étapes suivantes

• Inscrire le schéma de connexion
• Examiner la référence sur les API connecteurs Microsoft Graph
• Télécharger l’exemple de connecteur de recherche depuis GitHub