Instalar o suplemento

Instalar o ConnXL significa duas coisas: correr o agent num host que os teus utilizadores de Excel consigam alcançar, e levar o manifesto gerado até ao Excel. O agent serve o suplemento; o manifesto apenas diz ao Excel onde vive o agent.

Vais correr o agent em produção?

Esta página cobre o mínimo para pôr o agent a correr e levar o manifesto ao Excel. Para ficheiros de serviço, contentores, atualizações, regras de firewall e desativação, consulta Implementar e correr o agent.

Correr o agent

O agent é um único binário, connxl-agent, que corres na tua própria VM, contentor ou hardware dedicado — na tua própria cloud ou on-prem, dentro da tua rede. Ele lê a sua configuração ao vivo (funções, ligações, segredos por referência) apenas do backend — não há ficheiro de configuração YAML. Um pequeno conjunto de ficheiros fica, ainda assim, em disco ao lado dele: o par TLS cert.pem/key.pem e o diretório static/ da transferência (o shell do painel de tarefas e os logótipos neutros que o agent serve).

Transfere o agent configurado a partir da página do Agente do ambiente, no dashboard, separador Implementação (é a página inteira da primeira vez que este ambiente é implementado). Clica em Transferir agent configurado, escolhe a plataforma do teu host (Windows x64, Linux x64 ou Linux arm64) e obténs um binário com a identidade deste ambiente já incorporada — o URL do backend, o suplemento e o ambiente, e um token de inscrição de uso único novo, tudo gravado na transferência. Não há nada para configurar: coloca-o no teu host com o diretório static/ ao lado, adiciona o certificado TLS abaixo e executa-o. No primeiro arranque lê a sua própria identidade incorporada, inscreve-se para obter o seu certificado de cliente mTLS e começa a servir — sem qualquer variável de ambiente.

Uma transferência configurada é única — e revogável

Cada Transferir agent configurado grava o seu próprio token de inscrição novo, por isso cada transferência é única byte a byte (o SHA256SUMS de uma versão cobre os binários simples, nunca um gravado). Se um binário configurado for divulgado ou retirares um host, clica em Regenerar no mesmo painel: revoga todos os tokens de inscrição deste ambiente de uma vez — cada binário configurado transferido anteriormente e cada token copiado à mão — de modo que nenhum se possa voltar a inscrever. Os agents que já se inscreveram não são afetados: autenticam-se com o seu certificado mTLS, e só uma inscrição nova precisa de um token vivo. Volta a transferir para distribuir um substituto.

Fornecer um certificado TLS

Os suplementos de Office têm de ser servidos por HTTPS, por isso o agent não arranca sem um certificado e uma chave. Coloca cert.pem e key.pem ao lado do binário. Para um host público usa um certificado real; para testes locais, o mkcert emite um de confiança.

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

Alcançabilidade

Seja qual for o host que escolheres, tem de ser alcançável por HTTPS por cada cliente de Excel que vai usar o suplemento — o Excel obtém o painel de tarefas e executa as funções diretamente contra o agent. O agent só faz ligações de saída para este backend, por isso assenta confortavelmente atrás de NAT ou de uma firewall.

O token incorporado apenas arranca a inscrição

O token de uso único gravado num binário configurado faz exatamente uma coisa: permite que o agent obtenha o seu certificado de cliente mTLS no primeiro arranque. A partir daí é o certificado —não o token— que autentica cada pedido, para sempre. É por isso que Regenerar nunca perturba um agent que já se inscreveu, e por isso que regenerar contém um binário configurado divulgado: o token gasto já não consegue ganhar um certificado. Ver TLS mútuo para o ciclo de vida do certificado e a alternativa de atestação na cloud.

Implementar num host Linux (AWS ou onde quer que seja)

Num servidor real, corre o agent como um serviço para que reinicie no arranque e após uma falha. Um binário configurado leva a sua própria identidade, por isso a unidade não precisa de nenhuma variável CONNXL_* — apenas o diretório de trabalho:

/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 e static/ vivem todos em /opt/connxl-agent. Depois systemctl enable --now connxl-agent.

O agent só faz ligações de saída para este backend e para as tuas fontes de dados, por isso um host fechado não precisa de nenhuma porta de entrada aberta para a ligação com o backend. O que tem de ser alcançável é o endpoint HTTPS :3000 do agent — o Excel obtém o painel de tarefas e executa as funções diretamente contra ele, a partir de onde os teus utilizadores estiverem. Dá-lhe um certificado de confiança pública para o host exato do manifesto; na web e em máquinas que não geres, um certificado autoassinado será rejeitado. Padrões comuns:

Proxy inverso / balanceador de carga (nginx, Caddy, um AWS ALB com um certificado ACM) que termina TLS num nome DNS que possuis e reencaminha para o :3000 do agent.
Um túnel (por ex. Cloudflare Tunnel) que publica o agent num nome de host HTTPS de confiança sem abrir qualquer porta de entrada — útil para uma experiência rápida ou para um agent sem IP público.

Seja qual for a tua escolha, define esse URL HTTPS público como o host do agent do ambiente (abaixo) para que o manifesto gerado aponte o Excel para ele.

Avançado: configurar a identidade com variáveis de ambiente

A transferência configurada é a via fácil, mas o agent continua a ler a sua identidade das variáveis de ambiente CONNXL_* quando as defines — a opção certa para contentores, Kubernetes ou qualquer pipeline de IaC/automação onde uma transferência gravada não encaixa. As variáveis de ambiente ganham sempre: qualquer valor CONNXL_* que definas sobrepõe-se ao campo correspondente incorporado no binário, por isso podes partir de um binário cru (não configurado) —obténs um em Configuração avançada / manual no painel de Implementação— ou sobrepor campos concretos num configurado.

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	O host público deste backend — de onde o agent extrai a sua configuração e para onde envia a telemetria.
`CONNXL_ENROLL_TOKEN`Required	`string`	Um token de inscrição de uso único, revelado uma vez quando clicas em Regenerar para este ambiente. O agent troca-o pelo seu próprio certificado de cliente mTLS no primeiro arranque, e a partir daí autentica-se com esse certificado.
`CONNXL_MTLS_CERT`Required	`path`	Caminho onde o agent guarda o certificado de cliente que inscreve — tu escolhes o local, o agent cria o ficheiro. Não é o mesmo par que cert.pem/key.pem, acima.
`CONNXL_MTLS_KEY`Required	`path`	Caminho da chave privada correspondente. Ver TLS mútuo para o ciclo completo.

Sem token? Inscreve-te com a identidade cloud do agent

Na AWS, GCP ou Azure, o agent pode inscrever-se sem qualquer token usando a sua identidade de instância — define CONNXL_ENROLL_ATTESTATION (mais CONNXL_ADDIN_ID/CONNXL_ENV_ID) em vez de CONNXL_ENROLL_TOKEN. Ver TLS mútuo.

Apontar o Excel para o teu host do agent

Na página do teu suplemento, define o host do agent (substitui-o por ambiente nas definições do ambiente). O ConnXL dobra esse host em cada URL do manifesto gerado — o painel de tarefas, os metadados das funções e cada imagem — por isso o Excel fala sempre com o teu agent e nunca com o ConnXL.

Introduz apenas o domínio — addin.a-tua-empresa.com, com porta se for preciso. O https:// é fixo e aparece como prefixo do campo: o Office só carrega um suplemento por HTTPS, localhost incluído, por isso o esquema não se escolhe.

Transferir ou copiar o manifesto

A partir da mesma página, transfere o manifesto gerado. O ConnXL emite tanto o manifesto XML clássico como o manifesto JSON unificado — escolhe o que a tua versão de Office precisa. Também podes copiar o URL do manifesto, que é a fonte autoritativa para implementação centralizada.

É um manifesto, não um binário

Não há um binário de suplemento com um clique nem uma listagem na Office Store. A transferência é um pequeno ficheiro de manifesto que regista no Excel o teu suplemento alojado no agent.

Levá-lo até ao Excel

Há duas formas de instalar, dependendo de para quem é:

Sideload — para ti ou para uma equipa pequena durante a configuração. Regista o manifesto localmente e o suplemento aparece no friso. O guia de sideloading da Microsoft cobre cada plataforma.
Implementação centralizada no M365 — para distribuir a toda a tua organização. O teu administrador do Microsoft 365 implementa o suplemento a partir do centro de administração usando o URL do manifesto, e ele chega a cada utilizador atribuído.

Quando tens de reimplementar

A maioria das alterações aplica-se ao vivo — editar funções, ligações, o painel de tarefas ou templates flui para o agent pelo seu canal de configuração sem reimplementação. Só as alterações que modificam o próprio manifesto — o ícone do suplemento, adicionar/remover/reetiquetar um botão do friso, ou o nome do separador personalizado — exigem que os utilizadores reinstalem o manifesto.

Referência de variáveis de ambiente

Tudo o que o agent lê ao arrancar. Uma transferência configurada fornece a sua própria identidade, por isso nessa via não precisas de nenhuma destas; são a via manual / de automação, e qualquer valor que definas aqui sobrepõe-se ao campo correspondente incorporado num binário configurado. CONNXL_BACKEND_URL mais uma credencial de inscrição — CONNXL_ENROLL_TOKEN, ou CONNXL_ENROLL_ATTESTATION com CONNXL_ADDIN_ID/CONNXL_ENV_ID — mais CONNXL_MTLS_CERT/CONNXL_MTLS_KEY (onde o certificado emitido fica) é o mínimo para cablar a identidade à mão; o resto é opcional. O agent escuta na porta 3000 (HTTPS) e o seu certificado de serviço é sempre o par cert.pem / key.pem junto ao binário — nenhum dos dois é uma variável de ambiente.

Field	Type	Description
`CONNXL_BACKEND_URL`Required	`URL`	O host público deste backend — de onde o agent obtém a configuração e para onde envia a telemetria.
`CONNXL_MTLS_CERT`Required	`path`	Caminho onde o agent guarda o certificado de cliente que inscreve (tu escolhes o local — o agent cria o ficheiro). Ver TLS mútuo.
`CONNXL_MTLS_KEY`Required	`path`	Caminho da chave privada correspondente.
`CONNXL_ENROLL_TOKEN`Condicional	`string`	Token de inscrição de uso único que permite a um agent novo obter o seu certificado mTLS no primeiro arranque — o único mecanismo de autenticação do agent (já não existe uma chave de API estática). Obrigatório salvo inscrição via CONNXL_ENROLL_ATTESTATION. Ver TLS mútuo.
`CONNXL_ENROLL_ATTESTATION`Condicional	`aws \| gcp \| azure`	Usa o documento de identidade de instância da cloud como credencial de inscrição em vez de um token. Obrigatório salvo se CONNXL_ENROLL_TOKEN estiver definido.
`CONNXL_ADDIN_ID`Condicional	`id`	O suplemento alvo da inscrição. Obrigatório apenas se CONNXL_ENROLL_ATTESTATION estiver definido — não é lido na via por token.
`CONNXL_ENV_ID`Condicional	`id`	O ambiente alvo da inscrição. Obrigatório apenas se CONNXL_ENROLL_ATTESTATION estiver definido — não é lido na via por token.
`CONNXL_ZONE`Optional	`string`	Etiqueta livre de localização (um rack, um datacenter, uma zona de disponibilidade). Reportada com os instantâneos de saúde e mostrada na página de saúde do agent.
`CONNXL_REGION`Optional	`string`	Etiqueta livre de região, reportada junto com a zona.
`CONNXL_REPLICA_ID`Optional	`string`	Etiqueta opcional que identifica esta réplica nos heartbeats e nos logs agregados. Útil quando executa vários agentes atrás de um balanceador de carga e o hostname da máquina é opaco (um id de contentor ou pod). Por predefinição, usa o hostname da máquina.
`CONNXL_HEARTBEAT_SECONDS`Optional	`int`	Intervalo do heartbeat em segundos. Por omissão 30, limitado a um máximo de 60 — o backend marca um agent como offline após ~90 s de silêncio, pelo que um intervalo maior faria oscilar um agent saudável.
`CONNXL_STATE_DIR`Optional	`path`	Diretório onde o agent persiste o seu estado de execução entre reinícios. Por omissão um diretório state/ junto ao binário.
`CONNXL_SECRETS_TTL_SECONDS`Optional	`int`	Durante quanto tempo as referências a segredos resolvidas ficam em cache, em segundos. Por omissão 300; 0 ou negativo desativa a cache. Erros de resolução nunca são guardados em cache.
`CONNXL_SECRETS_AWS_REGION`Optional	`string`	Região por omissão para referências a segredos suportadas pela AWS. Um ?region= na própria referência tem prioridade; sem nenhum dos dois, aplica-se a cadeia por omissão do SDK da AWS.
`CONNXL_SECRETS_AWS_ENDPOINT`Optional	`URL https`	Endpoint personalizado para referências a segredos suportadas pela AWS (um VPC endpoint, um endpoint FIPS ou um emulador). Tem de ser https ou um endereço de loopback — qualquer outro valor é ignorado com um aviso, porque definir um endpoint ignora também a cadeia de credenciais e um endpoint em texto simples levaria nomes e valores de segredos em claro.
`CONNXL_SECRETS_GCP_ENDPOINT`Optional	`URL https`	Endpoint personalizado para referências do GCP Secret Manager (um Secret Manager privado ou emulado). Tem de ser https ou um endereço de loopback. Quando definido, as Application Default Credentials são ignoradas. Deixe sem definir para o serviço real.
`CONNXL_SECRETS_AZURE_ENDPOINT`Optional	`URL https`	Endpoint personalizado para referências do Azure Key Vault (um vault privado ou emulado). Tem de ser https ou um endereço de loopback. Quando definido, o DefaultAzureCredential é ignorado. Deixe sem definir para o serviço real.
`CONNXL_LOG_LEVEL`Optional	`debug \| info \| warn \| error`	Nível mínimo de severidade escrito nos logs. Predefinição info; debug acrescenta linhas detalhadas; warn mantém as falhas e os problemas repetíveis; error mantém apenas as falhas terminais — esconde também um heartbeat ou uma reinscrição falhados, por isso prefere warn para reduzir o ruído.
`CONNXL_LOG_FORMAT`Optional	`text \| json`	Formato das linhas de log em disco e stdout. Predefinição text (legível); json emite um objeto JSON por linha ({ts, level, category, msg}) para coletores de logs.

Ligações

Liga o agent às tuas fontes de dados antes de construíres funções.

Usar funções no Excel

O espaço de nomes, o painel de tarefas, as referências de célula, os derrames e as atualizações ao vivo.

Instalar o suplemento

Ligações

Usar funções no Excel

Nesta página