Installer le complément

Installer ConnXL, c'est deux choses : exécuter l'agent sur un hôte que vos utilisateurs Excel peuvent atteindre, et faire entrer le manifeste généré dans Excel. L'agent sert le complément ; le manifeste indique simplement à Excel où se trouve l'agent.

Vous exécutez l'agent en production ?

Cette page couvre le minimum pour démarrer l'agent et charger le manifeste dans Excel. Pour les fichiers de service, les conteneurs, les mises à niveau, les règles de pare-feu et la mise hors service, voir Déployer et exécuter l'agent.

Exécuter l'agent

L'agent est un binaire unique, connxl-agent, que vous exécutez sur votre propre VM, conteneur ou machine physique — dans votre propre cloud ou sur site, à l'intérieur de votre réseau. Il lit sa configuration en direct (fonctions, connexions, secrets par référence) uniquement depuis le backend — il n'y a pas de fichier de configuration YAML. Un petit ensemble de fichiers se trouve tout de même sur le disque à côté de lui : la paire TLS cert.pem/key.pem, et le répertoire static/ issu du téléchargement (le squelette du volet Office et les logos neutres que l'agent sert).

Téléchargez l'agent configuré depuis la page Agent de l'environnement, dans le tableau de bord, onglet Déploiement (c'est toute la page la première fois que cet environnement se déploie). Cliquez sur Télécharger l'agent configuré, choisissez la plateforme de votre hôte (Windows x64, Linux x64 ou Linux arm64), et vous obtenez un binaire avec l'identité de cet environnement déjà intégrée — l'URL du backend, le complément et l'environnement, et un jeton d'enrôlement à usage unique neuf, le tout gravé dans le téléchargement. Il n'y a rien à configurer : déposez-le sur votre hôte avec le répertoire static/ à côté, ajoutez le certificat TLS ci-dessous, et exécutez-le. Au premier démarrage, il lit sa propre identité intégrée, s'enrôle pour obtenir son certificat client mTLS et commence à servir — sans aucune variable d'environnement.

Un téléchargement configuré est unique — et révocable

Chaque Télécharger l'agent configuré grave son propre jeton d'enrôlement neuf, de sorte que chaque téléchargement est unique octet par octet (le SHA256SUMS d'une version couvre les binaires simples, jamais un binaire gravé). Si un binaire configuré fuit ou qu'un hôte est retiré, cliquez sur Régénérer dans le même panneau : cela révoque tous les jetons d'enrôlement de cet environnement d'un coup — chaque binaire configuré téléchargé précédemment et chaque jeton copié à la main — de sorte qu'aucun ne peut plus s'enrôler. Les agents déjà enrôlés ne sont pas affectés : ils s'authentifient avec leur certificat mTLS, et seul un nouvel enrôlement a besoin d'un jeton actif. Retéléchargez pour distribuer un remplacement.

Fournir un certificat TLS

Les compléments Office doivent être servis en HTTPS, l'agent ne démarrera donc pas sans un certificat et une clé. Placez cert.pem et key.pem à côté du binaire. Pour un hôte public, utilisez un vrai certificat ; pour les tests locaux, mkcert en émet un de confiance.

terminalsh

# working directory holds: connxl-agent, cert.pem, key.pem, static/

./connxl-agent # a configured binary needs no env vars; listens on https://<host>:3000

Accessibilité

Quel que soit l'hôte que vous choisissez, il doit être accessible en HTTPS par chaque client Excel qui utilisera le complément — Excel récupère le volet Office et exécute les fonctions directement sur l'agent. L'agent n'établit que des connexions sortantes vers ce backend, il se place donc confortablement derrière un NAT ou un pare-feu.

Le jeton intégré ne fait qu'amorcer l'enrôlement

Le jeton à usage unique gravé dans un binaire configuré fait exactement une chose : il permet à l'agent d'obtenir son certificat client mTLS au premier démarrage. Ensuite, c'est le certificat — et non le jeton — qui authentifie chaque requête, pour toujours. C'est pourquoi Régénérer ne perturbe jamais un agent déjà enrôlé, et pourquoi régénérer contient un binaire configuré ayant fuité : le jeton dépensé ne peut plus gagner de certificat. Voir TLS mutuel pour le cycle de vie du certificat et l'alternative par attestation cloud.

Déployer sur un hôte Linux (AWS ou ailleurs)

Sur un vrai serveur, exécutez l'agent comme un service afin qu'il redémarre au démarrage et après un plantage. Un binaire configuré porte sa propre identité, l'unité n'a donc besoin d'aucune variable CONNXL_* — juste le répertoire de travail :

/etc/systemd/system/connxl-agent.serviceini

[Unit]
Description=connxl-agent
After=network-online.target

[Service]
WorkingDirectory=/opt/connxl-agent
ExecStart=/opt/connxl-agent/connxl-agent
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

connxl-agent, cert.pem, key.pem et static/ vivent tous dans /opt/connxl-agent. Puis systemctl enable --now connxl-agent.

L'agent n'établit que des connexions sortantes vers ce backend et vers vos sources de données, un hôte verrouillé n'a donc besoin d'aucun port entrant ouvert pour la liaison avec le backend. Ce qui doit être accessible, c'est l'endpoint HTTPS :3000 de l'agent — Excel récupère le volet Office et exécute les fonctions directement sur lui, d'où que soient vos utilisateurs. Donnez-lui un certificat de confiance publique pour l'hôte exact figurant dans le manifeste ; sur le web et sur des machines que vous ne gérez pas, un certificat auto-signé sera rejeté. Schémas courants :

Reverse proxy / répartiteur de charge (nginx, Caddy, un AWS ALB avec un certificat ACM) terminant TLS sur un nom DNS que vous possédez et transférant vers le :3000 de l'agent.
Un tunnel (par ex. Cloudflare Tunnel) qui publie l'agent sur un nom d'hôte HTTPS de confiance sans ouvrir le moindre port entrant — pratique pour un essai rapide ou un agent sans IP publique.

Quel que soit votre choix, définissez cette URL HTTPS publique comme l'hôte d'agent de l'environnement (ci-dessous) afin que le manifeste généré y dirige Excel.

Avancé : configurer l'identité avec des variables d'environnement

Le téléchargement configuré est la voie facile, mais l'agent lit toujours son identité dans les variables d'environnement CONNXL_* lorsque vous les définissez — le bon choix pour les conteneurs, Kubernetes, ou tout pipeline IaC/automatisation où un téléchargement gravé ne convient pas. Les variables d'environnement l'emportent toujours : toute valeur CONNXL_* que vous définissez remplace le champ correspondant intégré dans le binaire, vous pouvez donc partir d'un binaire brut (non configuré) — récupérez-en un sous Configuration avancée / manuelle dans le panneau de Déploiement — ou remplacer des champs individuels sur un binaire configuré.

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	L'hôte public de ce backend — l'endroit où l'agent récupère sa configuration et pousse sa télémétrie.
`CONNXL_ENROLL_TOKEN`Required	`string`	Un jeton d'enrôlement à usage unique, révélé une fois lorsque vous cliquez sur Régénérer pour cet environnement. L'agent l'échange contre son propre certificat client mTLS au premier démarrage, puis s'authentifie avec ce certificat par la suite.
`CONNXL_MTLS_CERT`Required	`path`	Chemin où l'agent stocke le certificat client qu'il enrôle — vous choisissez l'emplacement, l'agent crée le fichier. Ce n'est pas la même paire que cert.pem/key.pem ci-dessus.
`CONNXL_MTLS_KEY`Required	`path`	Chemin de la clé privée correspondante. Voir TLS mutuel pour le cycle complet.

Pas de jeton ? Enrôlez avec l'identité cloud de l'agent

Sur AWS, GCP ou Azure, l'agent peut s'enrôler sans aucun jeton en utilisant son identité d'instance — définissez CONNXL_ENROLL_ATTESTATION (plus CONNXL_ADDIN_ID/CONNXL_ENV_ID) à la place de CONNXL_ENROLL_TOKEN. Voir TLS mutuel.

Diriger Excel vers votre hôte d'agent

Sur la page de votre complément, définissez l'hôte de l'agent (remplacez-le par environnement dans les paramètres de l'environnement). ConnXL intègre cet hôte dans chaque URL du manifeste généré — le volet Office, les métadonnées des fonctions et chaque image — de sorte qu'Excel parle toujours à votre agent et jamais à ConnXL.

Saisissez uniquement le domaine — addin.votre-entreprise.com, avec un port si nécessaire. Le https:// est fixe et affiché en préfixe du champ : Office ne charge un complément qu'en HTTPS, localhost compris, le schéma ne se choisit donc pas.

Télécharger ou copier le manifeste

Depuis la même page, téléchargez le manifeste généré. ConnXL émet à la fois le manifeste XML classique et le manifeste JSON unifié — choisissez celui dont votre version d'Office a besoin. Vous pouvez aussi copier l'URL du manifeste, qui est la source faisant autorité pour un déploiement centralisé.

C'est un manifeste, pas un binaire

Il n'y a pas de binaire de complément en un clic ni de fiche sur l'Office Store. Le téléchargement est un petit fichier manifeste qui enregistre dans Excel votre complément hébergé par l'agent.

Le faire entrer dans Excel

Il y a deux façons d'installer, selon à qui c'est destiné :

Chargement indépendant — pour vous-même ou une petite équipe pendant la configuration. Enregistrez le manifeste localement et le complément apparaît sur le ruban. Le guide de chargement indépendant de Microsoft couvre chaque plateforme.
Déploiement M365 centralisé — pour un déploiement à l'échelle de toute votre organisation. Votre administrateur Microsoft 365 déploie le complément depuis le centre d'administration à l'aide de l'URL du manifeste, et il arrive chez chaque utilisateur assigné.

Quand vous devez redéployer

La plupart des modifications s'appliquent en direct — modifier des fonctions, des connexions, le volet Office ou des modèles se propage à l'agent via son canal de configuration sans redéploiement. Seules les modifications qui altèrent le manifeste lui-même — l'icône du complément, l'ajout/la suppression/le renommage d'un bouton de ruban, ou le nom de l'onglet personnalisé — obligent les utilisateurs à réinstaller le manifeste.

Référence des variables d'environnement

Tout ce que l'agent lit au démarrage. Un téléchargement configuré fournit sa propre identité, vous n'avez donc besoin d'aucune de ces variables sur cette voie ; ce sont la voie manuelle / d'automatisation, et toute valeur que vous définissez ici remplace le champ correspondant intégré dans un binaire configuré. CONNXL_BACKEND_URL plus un identifiant d'enrôlement — CONNXL_ENROLL_TOKEN, ou CONNXL_ENROLL_ATTESTATION avec CONNXL_ADDIN_ID/CONNXL_ENV_ID — plus CONNXL_MTLS_CERT/CONNXL_MTLS_KEY (où atterrit le certificat émis) constituent le minimum pour câbler l'identité à la main ; le reste est facultatif. L'agent écoute sur le port 3000 (HTTPS) et son certificat de service est toujours la paire cert.pem / key.pem à côté du binaire — ni l'un ni l'autre n'est une variable d'environnement.

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	L'hôte public de ce backend — d'où l'agent tire sa configuration et où il envoie la télémétrie.
`CONNXL_MTLS_CERT`Required	`path`	Chemin où l'agent stocke le certificat client qu'il enrôle (vous choisissez l'emplacement — l'agent crée le fichier). Voir TLS mutuel.
`CONNXL_MTLS_KEY`Required	`path`	Chemin de la clé privée correspondante.
`CONNXL_ENROLL_TOKEN`Conditionnel	`string`	Jeton d'enrôlement à usage unique qui permet à un agent neuf d'obtenir son certificat mTLS au premier démarrage — le seul mécanisme d'authentification d'agent (il n'y a plus de clé d'API statique). Requis sauf enrôlement via CONNXL_ENROLL_ATTESTATION. Voir TLS mutuel.
`CONNXL_ENROLL_ATTESTATION`Conditionnel	`aws \| gcp \| azure`	Utilise le document d'identité d'instance cloud comme identifiant d'enrôlement à la place d'un jeton. Requis sauf si CONNXL_ENROLL_TOKEN est défini.
`CONNXL_ADDIN_ID`Conditionnel	`id`	Le complément ciblé par l'enrôlement de cet agent. Requis uniquement si CONNXL_ENROLL_ATTESTATION est défini — non lu sur la voie par jeton.
`CONNXL_ENV_ID`Conditionnel	`id`	L'environnement ciblé par l'enrôlement de cet agent. Requis uniquement si CONNXL_ENROLL_ATTESTATION est défini — non lu sur la voie par jeton.
`CONNXL_ZONE`Optional	`string`	Étiquette libre d'emplacement (un rack, un datacenter, une zone de disponibilité). Rapportée avec les instantanés de santé et affichée sur la page de santé de l'agent.
`CONNXL_REGION`Optional	`string`	Étiquette libre de région, rapportée avec la zone.
`CONNXL_REPLICA_ID`Optional	`string`	Étiquette facultative identifiant cette réplique dans les heartbeats et les logs agrégés. Utile lorsque vous exécutez plusieurs agents derrière un équilibreur de charge et que le hostname de la machine est opaque (un id de conteneur ou de pod). Par défaut, le hostname de la machine.
`CONNXL_HEARTBEAT_SECONDS`Optional	`int`	Intervalle du heartbeat en secondes. 30 par défaut, plafonné à 60 — le backend marque un agent hors ligne après ~90 s de silence, un intervalle plus long ferait donc clignoter un agent sain.
`CONNXL_STATE_DIR`Optional	`path`	Répertoire où l'agent persiste son état d'exécution entre les redémarrages. Par défaut un répertoire state/ à côté du binaire.
`CONNXL_SECRETS_TTL_SECONDS`Optional	`int`	Durée de mise en cache des références de secrets résolues, en secondes. 300 par défaut ; 0 ou négatif désactive le cache. Les erreurs de résolution ne sont jamais mises en cache.
`CONNXL_SECRETS_AWS_REGION`Optional	`string`	Région par défaut pour les références de secrets adossées à AWS. Un ?region= sur la référence elle-même l'emporte ; sans l'un ni l'autre, la chaîne par défaut du SDK AWS s'applique.
`CONNXL_SECRETS_AWS_ENDPOINT`Optional	`URL https`	Endpoint personnalisé pour les références de secrets adossées à AWS (un endpoint VPC, un endpoint FIPS ou un émulateur). Doit être en https ou pointer vers une adresse de bouclage — toute autre valeur est ignorée avec un avertissement, car définir un endpoint contourne aussi la chaîne d'identifiants et un endpoint en clair transporterait noms et valeurs de secrets en clair.
`CONNXL_SECRETS_GCP_ENDPOINT`Optional	`URL https`	Endpoint personnalisé pour les références GCP Secret Manager (un Secret Manager privé ou émulé). Doit être en https ou pointer vers une adresse de bouclage. Lorsqu'il est défini, les Application Default Credentials sont ignorées. Laissez-le vide pour le service réel.
`CONNXL_SECRETS_AZURE_ENDPOINT`Optional	`URL https`	Endpoint personnalisé pour les références Azure Key Vault (un coffre privé ou émulé). Doit être en https ou pointer vers une adresse de bouclage. Lorsqu'il est défini, DefaultAzureCredential est ignoré. Laissez-le vide pour le service réel.
`CONNXL_LOG_LEVEL`Optional	`debug \| info \| warn \| error`	Niveau de sévérité minimum écrit dans les logs. Par défaut info ; debug ajoute des lignes détaillées ; warn conserve les échecs et les problèmes réessayables ; error ne conserve que les échecs terminaux — il masque aussi un heartbeat ou un ré-enrôlement échoué, préférez donc warn pour réduire le bruit.
`CONNXL_LOG_FORMAT`Optional	`text \| json`	Format des lignes de log sur disque et stdout. Par défaut text (lisible) ; json émet un objet JSON par ligne ({ts, level, category, msg}) pour les collecteurs de logs.

Connexions

Reliez l'agent à vos sources de données avant de construire des fonctions.

Utiliser les fonctions dans Excel

L'espace de noms, le volet Office, les références de cellules, les répandements et les mises à jour en direct.

Installer le complément

Connexions

Utiliser les fonctions dans Excel

Sur cette page