Synchroniser SharePoint avec un index IA : la requête delta

Pour qu'un index d'IA reste fidèle à une bibliothèque SharePoint, il faut savoir, à chaque passage, ce qui a été ajouté, modifié et supprimé depuis le précédent. Microsoft Graph fournit pour cela la requête delta sur les éléments d'un drive : un premier appel décrit tout, les suivants ne renvoient que les changements. Cette page détaille son fonctionnement d'après la documentation officielle, lue le 15/11/2026, et la façon de l'appliquer à un index.

Le principe en trois temps

1. Énumération initiale : GET /sites/{siteId}/drive/root/delta (ou /drives/{drive-id}/root/delta). Graph renvoie des pages d'éléments, chacune avec un @odata.nextLink. On suit ces liens jusqu'à la dernière page.
2. Fin de l'énumération : la dernière page porte un @odata.deltaLink au lieu du nextLink. On le conserve.
3. Passages suivants : on appelle le deltaLink conservé. Graph ne renvoie que les éléments changés depuis, puis un nouveau deltaLink.

La documentation insiste : pour tenir une représentation complète d'un dossier ou d'un drive, il faut utiliser delta pour l'énumération initiale. Parcourir les enfants dossier par dossier ne garantit pas de tout voir si des écritures ont lieu pendant le parcours.

Une boucle de synchronisation

import requests

def synchroniser(url, jeton_acces, index):
    entetes = {"Authorization": f"Bearer {jeton_acces}"}
    while True:
        page = requests.get(url, headers=entetes).json()
        for item in page["value"]:
            if "deleted" in item:
                index.retirer(item["id"])
            elif "file" in item:
                index.a_traiter(item["id"])
        if "@odata.nextLink" in page:
            url = page["@odata.nextLink"]
        else:
            return page["@odata.deltaLink"]   # à conserver pour le prochain passage

Ce squelette omet volontairement l'authentification, les nouvelles tentatives et l'erreur 410 traitée plus bas.

Les règles de la documentation à respecter

• Suivre par identifiant. La propriété parentReference ne contient pas le chemin, car renommer un dossier ne renvoie pas ses descendants. Votre index doit être indexé sur l'id de l'élément, pas sur son chemin.
• Un état, pas un historique. Le flux donne le dernier état de chaque élément : un fichier renommé deux fois n'apparaît qu'une fois, avec son dernier nom.
• Doublons dans le flux. Un même élément peut apparaître plusieurs fois : gardez la dernière occurrence.
• Suppressions. Les éléments supprimés portent la propriété deleted et doivent être retirés de l'état local. Un dossier ne se supprime localement que s'il est vide après application de tous les changements.
• Propriétés absentes. Sur OneDrive professionnel et SharePoint, delta ne renvoie pas ctag lors d'une création ou modification, ni ctag et name lors d'une suppression. Gardez le nom dans votre index pour pouvoir l'afficher après suppression.

Ne suivre que les changements à venir

Si l'index est déjà construit par un autre moyen, ?token=latest renvoie une réponse vide avec le deltaLink du moment. Sur OneDrive professionnel et SharePoint seulement, on peut aussi passer une date (encodée dans l'adresse) comme jeton, par exemple ?token=2026-11-01T00%3A00%3A00Z, quand aucun deltaLink n'a été conservé. La documentation recommande de préférer le deltaLink quand il existe.

L'erreur 410 : repartir de zéro proprement

Quand Graph ne peut plus fournir les changements depuis un jeton (jeton trop ancien, état du serveur modifié), il renvoie HTTP 410 Gone et un en-tête Location qui lance une nouvelle énumération complète. Après cette énumération, comparez avec votre index. Avec le code resyncChangesApplyDifferences, la documentation demande de remplacer les éléments locaux par la version du serveur, suppressions comprises ; avec resyncChangesUploadDifferences, elle demande de renvoyer au serveur ce qu'il ne connaît pas. Un index d'IA ne modifie jamais SharePoint : dans les deux cas, il s'aligne sur l'état renvoyé par le serveur.

Suivre aussi les changements de droits

C'est le point le plus souvent oublié : un document dont le partage a été retiré doit sortir des résultats des personnes concernées. Par défaut, delta renvoie des informations de partage pour tous les éléments changés. L'en-tête Prefer: hierarchicalsharing limite ces informations à la racine de chaque hiérarchie de droits et aux éléments dont le partage a changé. Pour isoler les changements de droits, Prefer: deltashowsharingchanges marque ces éléments d'une annotation @microsoft.graph.sharedChanged ; il doit être combiné avec deltashowremovedasdeleted et deltatraversepermissiongaps, et l'application doit alors demander la permission Sites.FullControl.All. Le filtrage côté recherche est traité sur la page consacrée aux droits d'accès dans une IA documentaire.

Permissions et contenu

• Permissions de delta : en délégué, Files.Read au minimum ; en application, Files.Read.All au minimum.
• Savoir si le contenu a vraiment changé : comparez l'empreinte quickXorHash du fichier, la seule garantie disponible selon la ressource hashes, à celle que vous avez indexée. Un renommage ne demande pas de recalculer les vecteurs.
• Convertir en PDF à la volée : GET /drive/items/{item-id}/content?format=pdf convertit Word, Excel, PowerPoint et d'autres formats, mais seulement pour les fichiers de 2 Mo au plus. La réponse est une redirection 302 vers une adresse de téléchargement valable quelques minutes.

Exemple illustratif

Prenons une PME dont les procédures vivent dans une bibliothèque SharePoint. Un passage de synchronisation toutes les heures, qui retire les éléments deleted, ne reconvertit que les fichiers dont l'empreinte a changé et relit les droits des éléments signalés, garde un index fidèle sans tout retraiter. Pour organiser la bibliothèque elle-même, voyez la page qui compare métadonnées et dossiers dans SharePoint.