Sources de documents
Ce que ça fait — et ce que ça ne fait pas
Une « source de documents » branche un stockage externe sur un projet, pour que son contenu serve de contexte. Le périmètre est volontairement étroit, et ce sont les limites qui comptent.
- C'est un proxy live, pas une synchronisation. Rien n'est copié, indexé ni stocké dans Vaks PM : à chaque demande, le fichier est lu chez le fournisseur puis le texte extrait est renvoyé. Supprimez un fichier chez vous, il disparaît immédiatement du contexte.
- C'est en lecture seule, toujours. Aucun provider n'écrit, ne renomme ni ne supprime quoi que ce soit. Le connecteur Google Drive ne demande que le scope
drive.readonly. - Ça ne remplace pas les pièces jointes ni l'espace documents du projet. Ce sont des fichiers chez vous, exposés en lecture ; les pièces jointes et l'espace documents restent stockés par Vaks PM.
- La portée est l'organisation, l'activation est le projet. Un connecteur se configure une fois pour l'org ; chaque projet décide ensuite s'il expose ce contexte.
- Le texte seul est renvoyé. Les binaires non extractibles sont refusés proprement plutôt que renvoyés bruts, et les fichiers trop gros sont bornés.
Les deux sources
Les deux implémentent le même contrat interne, mais leur mise en place n'a rien à voir : SharePoint hérite d'une identité déjà configurée, Google Drive est un connecteur autonome.
| Microsoft SharePoint | Google Drive | |
|---|---|---|
| Identité | Réutilise l'identité Graph du provisioning Microsoft Teams — aucun secret à saisir ici. | Connecteur autonome : compte de service Google, avec sa propre configuration. |
| Prérequis | Une équipe Teams provisionnée pour le projet (c'est son site/drive qui est lu). | Un dossier Drive ou un Shared Drive, et un compte de service qui peut le lire. |
| Ce qui est lu | Le drive du site SharePoint de l'équipe du projet. | Le Drive partagé du projet s'il a été provisionné ; sinon le dossier racine que vous désignez, et son arborescence. |
| Portée | Par projet (chaque projet a l'équipe qui lui est propre). | Par projet si vous activez le provisionnement d'un Drive partagé ; sinon par organisation (un dossier racine commun), activée projet par projet. |
| Configuration | Modèle d'identité seulement. | Mode d'auth, dossier racine, compte de service. |
Les deux se configurent au même endroit : Admin → Intégrations → Collaboration spaces, dans le bloc des sources de documents en bas de la section.
Qui lit, et comment
Deux publics, deux chemins, deux règles d'accès — c'est la distinction importante :
- Les agents IA lisent via les outils MCP
vaks_list_context_filesetvaks_get_context_file, rattachés à une tâche. Le projet doit avoir les agents activés. - Les membres du projet parcourent la même source depuis l'interface du projet. Là, c'est l'appartenance au projet qui autorise, pas le drapeau agents.
Dans les deux cas, la lecture d'un fichier est tracée dans le journal d'audit (action filesource.document.read) : vous savez toujours quel document a été ouvert, par qui, et sur quelle tâche.
Ce qui autorise la lecture
Chaque demande traverse une série de conditions ; la première qui manque produit un refus explicite, jamais un contenu partiel.
| Condition | Où elle se règle |
|---|---|
| Licence active | Admin → Organisation → Licence |
| Source configurée et activée | Admin → Intégrations → Collaboration spaces |
| Contexte documentaire activé pour le projet | Onglet du projet — interrupteur par projet |
| Agents activés pour le projet (lecture par un agent uniquement) | Onglet IA du projet |
| Appartenance au projet (lecture humaine uniquement) | Membres du projet |
| Accès effectif chez le fournisseur | Le grant SharePoint, ou le partage du dossier Drive |
SharePoint — identité & accès
SharePoint n'a aucun secret propre : il emprunte l'identité Graph déjà configurée pour le provisioning Microsoft Teams. Il faut donc que Teams soit configuré, et que le projet ait une équipe provisionnée — c'est le site de cette équipe qui est lu.
Le seul choix est le modèle d'identité :
| Modèle | Ce que ça implique |
|---|---|
read_all | L'application de provisioning lit elle-même les sites. Le plus simple, mais la permission est large : elle porte sur l'ensemble des sites du tenant. |
selected_granter | Une application « lecteur » distincte reçoit un droit de lecture site par site, posé automatiquement sur le seul site de l'équipe concernée. Nettement plus restreint — le choix recommandé quand votre sécurité regarde de près. |
L'accès est vérifié, pas supposé : à la provision d'une équipe, Vaks PM résout son site et son drive et enregistre si le droit est en place. S'il ne l'est pas, le panneau du projet propose de re-vérifier. La mise en place détaillée, côté Entra, vit dans le guide Espaces de collaboration.
Google Drive — étape 1, côté Google
Contrairement à SharePoint, Google Drive ne dépend d'aucun provisioning : il lui faut un compte de service et un dossier que ce compte peut lire.
- Activer l'API Drive. Dans un projet Google Cloud, APIs & Services → Library → Google Drive API → activer.
- Créer un compte de service. IAM & Admin → Service Accounts. Notez son email
…@….iam.gserviceaccount.com. - Donner accès au dossier — deux façons, au choix :
- Partage direct (le plus simple) : dans Drive, partagez le dossier (ou le Shared Drive) avec l'email du compte de service, en Lecteur. Aucune délégation nécessaire.
- Délégation domain-wide : autorisez le Client ID du compte de service sur le scope
https://www.googleapis.com/auth/drive.readonlydans admin.google.com → Sécurité → Contrôle des API → Délégation au niveau du domaine, puis désignez un utilisateur à impersoner. Utile quand le dossier ne peut pas être partagé explicitement.
- Relever l'ID du dossier racine. Ouvrez le dossier dans Drive : l'ID est la partie de l'URL après
/folders/.
iam.disableServiceAccountKeyCreation, vous ne pourrez pas télécharger de clé JSON. Le connecteur Drive accepte alors le mode Workload Identity Federation, exactement comme Google Chat : rien n'est téléchargé, Vaks génère sa propre clé de signature et vous collez le JWKS public dans un pool WIF. La marche à suivre côté Google Cloud est identique — voir la section WIF du guide Espaces de collaboration. En mode WIF, l'impersonation est obligatoire.
Google Drive — étape 2, dans Vaks PM
Ouvrez Admin → Intégrations → Collaboration spaces, descendez au bloc des sources de documents, ajoutez Google Drive et renseignez :
| Champ | Quoi renseigner |
|---|---|
| Mode d'authentification | Clé de compte de service (défaut) ou Workload Identity Federation (sans clé). Le reste du formulaire s'adapte à votre choix. |
| ID du dossier racine (repli organisation) | L'ID relevé à l'étape 1. Tout ce qui est lisible l'est à partir de ce dossier, jamais au-dessus. Ignoré pour les projets qui ont leur propre Drive partagé provisionné — laissez-le vide si tous vos projets en ont un. |
| Clé du compte de service (mode clé) | Le fichier JSON de la clé, collé entier. Stocké chiffré, jamais réaffiché. |
| Email du compte de service (mode WIF) | Le compte de service impersoné via la fédération — aucune clé détenue. |
| Audience du pool WIF (mode WIF) | Le nom de ressource complet du provider WIF, en //iam.googleapis.com/projects/…/providers/…. |
| Utilisateur impersonné | Requis en mode WIF. En mode clé, à laisser vide si le dossier est partagé directement avec le compte de service. |
Cliquez sur Tester : le connecteur obtient un jeton et liste le dossier racine, ce qui valide l'authentification et l'accès réel au dossier avant que quiconque en dépende. Puis activez le connecteur.
Fichiers Google natifs
Un Google Docs, Sheets ou Slides n'a pas de fichier binaire téléchargeable — le demander directement échoue. Le connecteur les exporte donc automatiquement en texte exploitable : Docs et Slides en texte brut, Sheets en CSV. C'est transparent : un agent qui demande un Google Docs reçoit son contenu, sans avoir à connaître cette subtilité.
Les autres formats (PDF, Office, texte…) suivent le chemin normal d'extraction de texte. Un format dont on ne sait rien tirer est refusé explicitement plutôt que renvoyé en binaire.
API & outils IA
| Route | Rôle |
|---|---|
GET /api/v1/tasks/{taskId}/context-files | Lister un dossier de la source rattachée au projet de la tâche (paginé). Atteignable par un jeton d'agent. |
GET /api/v1/tasks/{taskId}/context-files/{source}/{itemId} | Texte extrait d'un fichier. Tracé en audit. |
GET /api/v1/projects/{id}/context-files | Équivalent côté projet pour la navigation humaine dans l'interface. |
GET /api/v1/projects/{id}/context-files/availability | Indique si une source est disponible pour ce projet, et sinon pourquoi. |
Côté connecteur IA, deux outils suffisent : vaks_list_context_files pour parcourir, vaks_get_context_file pour lire. Un agent commence toujours par lister afin d'obtenir l'identifiant d'un item.
Dépannage
Les refus portent un code machine, repris tel quel ci-dessous — il dit précisément quelle condition a manqué.
| Code | Cause & correctif |
|---|---|
FS_DISABLED | Une bascule manque : licence, source désactivée en admin, contexte documentaire coupé sur le projet, ou agents non activés sur le projet (pour une lecture par agent). Le message précise laquelle. |
FS_FORBIDDEN | L'appelant n'a pas accès à ce projet. Pour un humain, c'est l'appartenance au projet ; pour un agent, le périmètre de sa tâche. |
FS_SOURCE_UNAVAILABLE | La source n'est pas résolue pour ce projet — typiquement SharePoint sans équipe provisionnée, donc sans drive à lire. |
FS_GRANT_PENDING | SharePoint : le droit de lecture n'est pas (encore) posé sur le site. Utilisez la re-vérification d'accès depuis le panneau du projet. |
FS_AUTH_FAILED | Le fournisseur a refusé l'authentification : clé de compte de service invalide ou illisible, délégation absente, ou — en mode WIF — pool/audience mal configuré. |
FS_ITEM_NOT_FOUND | L'item n'existe plus, ou n'est pas sous le dossier racine autorisé. Rappel : rien au-dessus de la racine n'est atteignable, c'est voulu. |
FS_FILE_TOO_LARGE | Le fichier dépasse la borne de lecture. Extrayez la partie utile dans un document plus petit. |
FS_UNSUPPORTED_FORMAT | Aucun texte ne peut être tiré de ce format (image, archive, binaire propriétaire). Refusé volontairement plutôt que renvoyé brut. |
FS_THROTTLED | Le fournisseur limite le débit. La lecture est réessayable ; espacez les demandes. |
À lire aussi : Espaces de collaboration pour le provisioning Teams dont SharePoint hérite son identité · connecteur IA pour les agents qui consomment ce contexte · toutes les intégrations.