Synchroniser Google Drive avec un index IA : l'API changes

Pour tenir un index d'IA aligné sur un Google Drive, l'interface de programmation (API) de Drive fournit un journal des changements : vous demandez un jeton de départ, puis, à chaque passage, la liste des fichiers changés depuis ce jeton. Les suppressions et les pertes d'accès y figurent. Cette page décrit la boucle complète d'après la documentation de Google lue le 15/11/2026, y compris l'export des Google Docs en Markdown.

Le principe

1. Jeton de départ : changes.getStartPageToken renvoie un jeton qui représente l'état actuel du compte. On le conserve.
2. Lecture des changements : changes.list avec ce jeton renvoie les changements dans l'ordre chronologique, les plus anciens d'abord.
3. Pagination : tant qu'un nextPageToken est présent, on l'utilise pour lire la page suivante. Sur la dernière page, la réponse porte un newStartPageToken, à conserver pour le prochain passage.

L'index lui-même se construit une première fois par une liste complète des fichiers ; le journal prend le relais ensuite.

La boucle, d'après l'exemple Python de Google

def synchroniser(service, jeton, index):
    while jeton is not None:
        reponse = service.changes().list(
            pageToken=jeton, spaces="drive", pageSize=1000,
            includeRemoved=True,
            supportsAllDrives=True, includeItemsFromAllDrives=True,
            fields="nextPageToken,newStartPageToken,changes(fileId,removed,file(name,mimeType,trashed,modifiedTime,md5Checksum))",
        ).execute()
        for c in reponse.get("changes", []):
            if c.get("removed") or c.get("file", {}).get("trashed"):
                index.retirer(c["fileId"])
            else:
                index.a_traiter(c["fileId"], c["file"])
        if "newStartPageToken" in reponse:
            return reponse["newStartPageToken"]
        jeton = reponse.get("nextPageToken")

Le premier jeton vient de service.changes().getStartPageToken().execute().

Les paramètres qui comptent

Retraits, corbeille et pertes d'accès

Dans la ressource Change, le champ removed indique que le fichier (ou le drive partagé) a été retiré de la liste, « par exemple par suppression ou perte d'accès ». Dans ce cas, file est absent : gardez le nom dans votre index si vous voulez l'afficher. Un fichier mis à la corbeille peut, lui, arriver comme un changement ordinaire : son champ trashed indique s'il a été mis à la corbeille, y compris quand c'est son dossier parent qui l'a été. Testez ce champ à chaque changement et retirez aussi ces fichiers de l'index.

La perte d'accès compte autant que la suppression : si le compte de service qui alimente l'index n'a plus accès à un dossier, ses documents doivent sortir des réponses. Côté utilisateur, ce que voit une application connectée à Drive est expliqué sur la page consacrée à la connexion de Google Drive à une IA.

Récupérer le contenu

Deux cas, selon le type de fichier :

• Fichiers binaires (PDF, Word, images) : files.get avec alt=media télécharge le contenu. L'empreinte md5Checksum (ou sha256Checksum) permet de savoir si le contenu a réellement changé avant de le retraiter.
• Documents Google (Docs, Sheets, Slides) : files.export avec le type voulu. Le contenu exporté est limité à 10 Mo, et ces documents n'ont pas d'empreinte md5Checksum. Comparez plutôt modifiedTime ou version.

Formats d'export utiles pour une IA, d'après la liste officielle :

Être prévenu plutôt que d'interroger

changes.watch permet de recevoir une notification quand de nouveaux changements existent. La documentation précise que la notification ne contient pas le détail : elle signale seulement qu'il faut relancer changes.list. Pour un index d'entreprise, un passage régulier (toutes les heures, par exemple) suffit souvent et reste plus simple à exploiter.

Droits d'accès de l'application

changes.list accepte notamment les autorisations drive.readonly et drive.metadata.readonly. Pour un index qui lit le contenu sans jamais rien modifier, une autorisation en lecture seule est le bon point de départ. La propagation des droits de chaque document jusqu'à la recherche est traitée sur la page consacrée aux droits d'accès dans une IA documentaire.

Exemple illustratif

Prenons un cabinet qui range ses modèles d'actes et ses notes internes dans un drive partagé. Un compte de service en lecture seule, un passage par heure avec driveId et includeRemoved, l'export des Docs en Markdown et un retrait immédiat des fichiers à la corbeille suffisent à garder l'index propre. Les métadonnées à conserver à chaque passage sont listées sur la page Métadonnées.