Créer, mettre à jour et supprimer des éléments dans une connexion Microsoft Graph
Les connecteurs Microsoft Graph offrent un moyen simple d’entrer des données externes dans Microsoft Graph. Les éléments que votre application ajoute à Microsoft service Search 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. La liste de contrôle d’accès est un tableau d’entrées de contrôle d’accès représentant un utilisateur ou un groupe Microsoft Entra. 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 incluent un autre groupe, Microsoft Entra utilisateurs et Microsoft Entra groupes. Si vous avez des utilisateurs non-Azure AD, vous devez les traduire en Microsoft Entra utilisateurs 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 ajoute 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, la reconnaissance optique de caractères peut extraire du texte pouvant faire l’objet d’une recherche à 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ésultat généré, qui est un aperçu généré dynamiquement 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’élément entier ou un ou plusieurs composants. Après avoir ajouté votre contenu à Microsoft Graph, vous pouvez le rechercher via l’expérience Recherche Microsoft après avoir configuré les secteurs verticaux de recherche et lestypes de résultats ou à l’aide de l’API Recherche Microsoft Graph.
Activités
Le composant activités est une propriété temporaire qui envoie des activités sur l’élément. Vous pouvez uniquement écrire dans cette propriété.
Une activité se compose d’un acteur (qui a effectué l’activité), d’une heure (quand l’activité a été effectuée) et d’un type d’activité (quel type d’activité a été effectué). Les types d’activité actuellement pris en charge se trouvent dans la section Description de la propriété type d’un externalActivity.
L’envoi d’activités sur l’élément alimente les expériences de recommandation intelligentes dans Microsoft 365. Les utilisateurs finaux peuvent recevoir du contenu adapté à eux en fonction des activités qui sont envoyées.
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
"properties": {
"title": "WiFi outage in Conference Room A",
"priority": 1,
"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.
Ajouter des activités à un élément
Pour ajouter des activités à un élément, vous appelez le point de terminaison addActivities , avec le même identificateur unique pour cet élément dans l’URL.
Par exemple, si une personne ayant Microsoft Entra ID 18948b93-d3ed-4307-9981-10fc36a08a52 a commenté le ticket de support technique avec le numéro SR00145 de ticket le 11 avril 2022 à 16h25, la demande d’envoi de cette activité peut se présenter comme suit.
POST /external/connections/contosohelpdesk/items/SR00145/addActivities
Content-Type: application/json
"activities": [
{
"type": "commented",
"startDateTime": "2022-04-11T16:25:34.3202005Z",
"performedBy": {
"id": "18948b93-d3ed-4307-9981-10fc36a08a52",
"type": "user"
}
}
]
Vous pouvez également ajouter une activité à un élément dans la même requête que celle qui crée l’élément. Ajoutez l’activité en tant qu’autre entité, comme acl et content. Si vous ajoutez une activité de cette façon, incluez le @odata.type pour l’activité, sinon la requête échoue. Les activités avec des horodatages de plus de sept jours ne sont pas exposées dans l’application Microsoft 365. Les utilisateurs finaux peuvent uniquement voir les activités dans l’application Microsoft 365 pour les éléments auxquels ils peuvent accéder et sur lesquels ils ont une activité (par exemple, partagés avec eux, créés et modifiés).
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
Maintenir vos données synchronisées
Tenez compte des informations suivantes lorsque vous choisissez comment maintenir vos données synchronisées :
Mécanisme d’analyse :
- Analyse incrémentielle : détecte et envoie (push) les ajouts dans les données sources ; moins gourmand en performances qu’une analyse complète.
- Analyse complète : Mises à jour l’ensemble de l’élément à partir des données sources (nouvelle analyse), en capturant tous les ajouts et suppressions, garantit une meilleure précision, mais est plus chronophage et gourmand en performances qu’une analyse incrémentielle.
Intervalle de synchronisation :
- Basé sur les événements : envoie (push) les mises à jour d’éléments sur la base d’un événement. Nous vous recommandons d’utiliser cet intervalle de synchronisation pour les données dynamiques ou sensibles telles que les status d’éléments.
- Planifié : envoie (push) les mises à jour des éléments à intervalles réguliers (toutes les N minutes). Nous vous recommandons d’utiliser cet intervalle de synchronisation pour les données riches en contenu ou non sensibles qui sont moins fréquemment mises à jour, telles que les wikis ou les pages web.
En fin de compte, le choix de la stratégie d’actualisation des données dépend de votre type de données et de vos capacités de calcul.