Como funciona a partilha de ficheiros (ContentDocumentLink)

Se alguma vez se interrogou porque é que um ficheiro aparece onde aparece no Salesforce — ou teve de consultar ficheiros em Apex ou num relatório — precisa de conhecer o modelo de dados subjacente. Os Salesforce Files modernos são três objetos relacionados, e dois campos na ligação decidem quem vê o quê. Este é o companheiro para administradores/programadores do artigo quem pode ver um ficheiro no Salesforce.

Os três objetos

Objeto	O que é	Quantos
ContentDocument	O ficheiro em si	Um por ficheiro
ContentVersion	Uma versão específica do conteúdo do ficheiro	Uma por carregamento/revisão
ContentDocumentLink	Uma ligação que associa o ficheiro a um registo, utilizador ou grupo	Vários por ficheiro

Quando carrega um ficheiro cria uma ContentVersion, que o Salesforce envolve num ContentDocument. Quando anexa esse ficheiro a um registo ou o partilha com alguém, cria um ContentDocumentLink.

O ficheiro é o ContentDocument. Onde reside e quem o pode ver está inteiramente nos seus ContentDocumentLinks.

ContentDocumentLink: o campo que mais importa

Uma linha de ContentDocumentLink diz “este ficheiro está ligado àquela coisa, com este nível de acesso, para este público.” Os seus campos-chave:

LinkedEntityId — aquilo a que o ficheiro está anexado

O ID daquilo a que o ficheiro está ligado:

Um registo (Account, Opportunity, Case, objeto personalizado…) → o ficheiro está “anexado a” esse registo.
Um User ou Group → o ficheiro é partilhado diretamente com essa pessoa ou grupo.

Um único ficheiro pode ter vários links em simultâneo — anexado a dois registos e partilhado com um utilizador ao mesmo tempo. Cada ligação é um caminho independente para ver o ficheiro.

ShareType — o nível de acesso

Valor	Nível	Pode fazer
`V`	Viewer	Abrir e transferir
`C`	Collaborator	Ver, editar, carregar novas versões, alterar a partilha
`I`	Inferred	Nível de acesso herdado do acesso ao registo associado

Inferred (I) é o importante para ficheiros anexados a registos: o acesso de um utilizador ao ficheiro é derivado do seu acesso ao registo a que está ligado. É esse o mecanismo por detrás de “quem pode ver o registo pode ver os seus ficheiros.”

Visibility — qual o público

Valor	Público
`AllUsers`	Utilizadores internos e externos (de comunidade)
`InternalUsers`	Apenas utilizadores internos
`SharedUsers`	Apenas os utilizadores com quem o ficheiro é explicitamente partilhado

Este é o campo que silenciosamente estraga o acesso no Experience Cloud: um ficheiro anexado a um registo com Visibility = InternalUsers não será mostrado aos utilizadores de comunidade, mesmo que estes consigam ver o registo. (Mais sobre isto em ficheiros e utilizadores convidados / do Experience Cloud.)

Como o acesso é realmente resolvido

Juntando tudo, um utilizador pode ver um ficheiro se algum dos seus ContentDocumentLinks lho conceder:

Uma ligação a um registo a que tem acesso (ShareType I) — acesso herdado da partilha do registo.
Uma ligação diretamente a ele ou ao seu grupo (ShareType V/C).
A pertença a uma biblioteca, ou uma ligação pública (mecanismos distintos).

…e a Visibility da ligação tem de incluir o público a que pertence. A maioria dos tickets de “ficheiro não visível” resume-se a uma ligação em falta ou a uma Visibility demasiado restritiva.

Como consultar

Como é tudo dados, pode inspecioná-los diretamente — por exemplo, encontrar todos os locais onde um ficheiro é partilhado:

SELECT ContentDocumentId, LinkedEntityId, ShareType, Visibility
FROM ContentDocumentLink
WHERE ContentDocumentId = '069...'

Cada linha é um público que consegue alcançar o ficheiro. Para enumerar as pessoas, expande depois o público de partilha completo de cada registo de LinkedEntityId — e é aí que isto cresce depressa.

Das linhas a uma resposta em linguagem simples

Um ficheiro anexado a vários registos herda todo o público de cada registo — hierarquia de funções, regras de partilha, equipas e tudo o resto — multiplicado por cada ContentDocumentLink. Reconstruir isto manualmente a partir de linhas em bruto é exatamente o trabalho que esconde exposições acidentais. O AgentForceAccess percorre os ContentDocumentLinks e a partilha do registo por detrás de cada um, e responde a “quem pode ver este ficheiro, e porquê” em linguagem simples.

Perguntas frequentes

Qual é a diferença entre ContentDocument, ContentVersion e ContentDocumentLink?

ContentDocument é o ficheiro em si (um por ficheiro). ContentVersion é uma versão específica desse ficheiro (uma por carregamento/revisão). ContentDocumentLink associa um ContentDocument a outra coisa — um registo, utilizador ou grupo — e transporta o nível de acesso e a visibilidade dessa ligação.

Para que aponta o LinkedEntityId?

É o ID daquilo a que o ficheiro está ligado. Para um ficheiro anexado a um registo é o ID do registo (Account, Opportunity, Case, etc.); para um ficheiro partilhado diretamente com uma pessoa ou grupo é um ID de User ou Group. Um único ficheiro pode ter vários ContentDocumentLinks em simultâneo.

Quais são os valores V, C e I do ShareType?

V = Viewer (abrir e transferir), C = Collaborator (ver, editar, carregar versões, alterar a partilha), I = Inferred (o nível de acesso que um utilizador obtém indiretamente a partir do acesso ao registo associado). Inferred é como o acesso ao registo se propaga a um ficheiro.

O que faz o campo Visibility?

Visibility define a quem a ligação é exposta: AllUsers (utilizadores internos e externos/de comunidade), InternalUsers (apenas internos), ou SharedUsers (apenas os utilizadores com quem o ficheiro é explicitamente partilhado). Os utilizadores de comunidade/Experience Cloud normalmente precisam de AllUsers para ver um ficheiro anexado a um registo.