Créer, mettre à jour, et supprimer des éléments ajoutés par votre application via les connecteurs Microsoft Graph
Les connecteurs Microsoft Graph offrent un moyen simple d’entrer des données externes dans Microsoft Graph. Les éléments ajoutés par votre application au service de Recherche Microsoft sont représentés par la ressource externalItem dans Microsoft Graph.
Après avoir créé une connexion, vous pouvez ajouter votre contenu. Chaque élément de votre source de données doit être représenté sous la forme d’un externalItem dans Microsoft Graph avec un ID d’élément unique. Cet ID sert à créer, mettre à jour, ou supprimer l’élément dans Microsoft Graph. Vous pouvez utiliser la clé primaire de votre source de données en tant qu’ID d’élément ou l’obtenir à partir d’un ou plusieurs champs.
Composants clés
externalItem possède trois composants clés : liste de contrôle d’accès, propriétés et contenu.
Liste de contrôle d’accès
La liste de contrôle d’accès est utilisée pour spécifier si l’accès aux rôles donné a permis d’accorder ou de refuser l’affichage des éléments dans les expériences Microsoft. Il s’agit d’une tableau d’entrées de contrôle d’accès, chacune représentant un utilisateur ou un groupe Azure Active Directory (Azure AD). Il existe un troisième type d’entrée de contrôle d’accès Everyone qui représente tous les utilisateurs du client.
Exemple de liste de contrôle d’accès
La valeuraccessTypedeny a la priorité sur grant. Par exemple, dans l’élément ci-dessus, tandis que Everyone se voit accorder l’accès et qu’un utilisateur spécifique se voit refuser l’accès, l’autorisation effective pour cet utilisateur est deny.
Si votre source de données comporte des groupes non Azure AD, tels que des équipes au sein de votre système de support technique, utilisés pour définir des autorisations pour l’élément, vous pouvez créer des groupes externes dans Microsoft Graph à l’aide des API de synchronisation de groupe pour répliquer les autorisations allow ou deny. Évitez de développer l’adhésion de vos groupes externes directement dans les listes de contrôle d’accès des éléments individuels, car chaque adhésion de groupe peut entraîner d’importantes mises à jour d’éléments.
Les groupes externes peuvent se composer d’un autre groupe externe, d’utilisateurs Azure AD et de groupes Azure AD. Si vous avez des utilisateurs non Azure AD, vous devez les transformer en utilisateurs Azure AD dans votre liste de contrôle d’accès.
Propriétés
Le composant propriétés est utilisé pour ajouter des métadonnées d’élément utiles dans les expériences Microsoft Graph. Vous devez inscrire le schéma de la connexion avant d’y ajouter des éléments et convertir les datatypes en datatypes pris en charge.
Un exemple d’élément de propriété.
Contenu
Le composant de contenu est utilisé pour ajouter la majeure partie de l'élément qui doit être indexé en texte intégral. Les exemples incluent la description du ticket, le texte analysé à partir d’un corps de fichier ou un corps de page Wiki.
Le contenu est l’un des champs clés influençant pertinence dans les expériences de Microsoft. Les types de contenu text et html sont pris en charge. Si votre source de données a d’autres types de contenu, tels que des fichiers binaires, des vidéos ou des images, vous pouvez les analyser en texte avant de les ajouter à Microsoft Graph. Par exemple, vous pouvez utiliser la reconnaissance optique de caractères pour extraire du texte pouvant faire l’être à partir d’images.
Importante
La solution de conformité prend uniquement en charge text le type de contenu. Si vous activez la connexion pour la conformité en définissant la propriété enabledContentExperience sur compliance, vous devez ingérer du contenu au format texte brut et définir le type de contenu sur text.
Exemple de composant de contenu.
Le contenu ne peut pas être ajouté directement dans un modèle de résultat de recherche, mais vous pouvez utiliser un extrait de résultats générés qui est un aperçu généré de façon dynamique des sections pertinentes dans le contenu.
Un modèle de résultats de recherche.
Lorsque le contenu de votre source de données change, vous devez le synchroniser avec vos éléments de connexion. Vous pouvez mettre à jour l’intégralité de l’élément ou mettre à jour un ou plusieurs de ses composants. Une fois que votre contenu a été ajouté à Microsoft Graph, vous pouvez le rechercher à l’aide de Microsoft Search suite à la configuration de secteurs verticaux de recherche et de types de résultats ou à l’aide de l’API de recherche de Microsoft Graph.
Ajouter un élément
Pour ajouter un élément à l’index, vous créez un externalItem. Lorsque vous créez un élément, vous affectez un identificateur unique dans l’URL.
Par exemple, votre application peut indexer des tickets de support technique en utilisant les numéros de ticket. Si le numéro d’un ticket est SR00145, la demande devrait ressembler à ceci.
PUT /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json
{
"title": "WiFi outage in Conference Room A",
"status": "New",
"assignee": "meganb@contoso.com"
}
Remarque
Avant que des éléments indexés se trouvent dans l’interface utilisateur Recherche Microsoft, l’administrateur doit personnaliser la page des résultats de la recherche pour la connexion correspondante.
Mettre à jour un élément
Lors de la mise à jour d’un élément dans le service externe (un ticket de support est réattribué ou la description d’un produit est mise à jour), vous pouvez mettre à jour son entrée dans l’index en mettant à jour la ressource externalItem avec l’identificateur unique attribué à l’élément au moment de sa création.
PATCH /external/connections/contosohelpdesk/items/SR00145
Content-Type: application/json
{
"assignee": "alexw@contoso.com"
}
Supprimer un élément
Vous pouvez supprimer des éléments de l’index en supprimant la ressource externalItem avec l’identificateur unique attribué à l’élément au moment de sa création.
DELETE /external/connections/contosohelpdesk/items/SR00145