Explorateur de fichiers intégrable

  • Type non défini

Ce document est la référence fonctionnelle et technique de l’Explorer de fichiers de RestFrontage. Il s’adresse aux utilisateurs, aux administrateurs Immersive et aux intégrateurs.

L’Explorer permet de parcourir des dossiers et d’accéder à des fichiers provenant :

  • de la base de données Immersive (Media.Content) ;
  • d’un fichier géré par le serveur (Media.Handle) ;
  • d’un conteneur Azure Blob monté sur un dossier Immersive (Folder.VirtualFolderPath).

1. Accéder à l’Explorer

La page est disponible à partir du serveur RestFrontage :

/Business/Resources/Explorer

1.1 Mode multi-racines par défaut

Sans RootFolderIdentifier, l’Explorer présente sous une racine synthétique tous les dossiers Immersive dont ParentIdentifier est nul :

https://mon-serveur/Business/Resources/Explorer

Ces dossiers apparaissent dans la zone de contenu et dans le panneau Dossiers. L’entrée Racine du fil d’Ariane permet de revenir à cette vue d’ensemble.

Un RootFolderIdentifier absent, nul ou négatif active ce mode multi-racines.

1.2 Limiter l’Explorer à une arborescence

Pour n’exposer qu’un dossier et ses descendants :

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=131

Le serveur refuse la navigation vers un dossier qui ne descend pas de cette racine.

1.3 Affichage Kiosk

Le mode Kiosk masque l’habillage habituel de RestFrontage :

https://mon-serveur/Business/Resources/Explorer?Render=Kiosk&RootFolderIdentifier=131

La valeur Kiosk n’est pas sensible à la casse. Toute autre valeur conserve la mise en page habituelle.

2. Comprendre et utiliser l’interface

L’interface comporte cinq zones :

  1. Barre de commandes : création, modification, suppression et actualisation selon la configuration et les droits de l’utilisateur.
  2. Dossiers : arborescence Immersive et Blob située à gauche sur les grands écrans.
  3. Fil d’Ariane : chemin du dossier courant et bouton flèche permettant de remonter au parent.
  4. Contenu : cartes des sous-dossiers et fichiers.
  5. État : chargement, erreur éventuelle et bouton permettant de réessayer.

Pour naviguer :

  • sélectionner un dossier dans l’arborescence ;
  • sélectionner une carte de dossier ;
  • sélectionner une étape du fil d’Ariane ;
  • utiliser le bouton flèche Remonter pour atteindre le parent ;
  • utiliser Racine pour revenir à la vue multi-racines lorsqu’aucune racine n’est imposée.

La page standard configure DownloadOnClick: true : un clic sur un fichier appelle le callback de sélection puis ouvre ou télécharge le fichier. Les images reconnues sont affichées sous forme de miniature.

Sur un écran de 720 px ou moins, le panneau de gauche est replié. Le bouton Dossiers l’ouvre ou le referme. La barre de commandes reste sur une seule ligne et peut défiler horizontalement. À 480 px ou moins, les commandes disposant d’une icône deviennent plus compactes. La grille et les cartes s’adaptent également à la largeur disponible.

3. Référence exhaustive des paramètres d’URL

Paramètre Type Obligatoire Valeur par défaut Description
RootFolderIdentifier entier positif Non aucune Limite l’Explorer à un dossier Immersive et à ses descendants. Sans valeur valide, active le mode multi-racines.
AllowedExtensions chaîne répétable Non toutes Filtre les fichiers affichés selon leur extension.
RelativePath chaîne Non aucune Chemin initial à résoudre dans l’arborescence Immersive puis, éventuellement, dans un Blob.
Render chaîne Non mise en page normale La valeur Kiosk active la mise en page Kiosk.
Token chaîne Selon le contexte session courante Jeton utilisé lorsque l’appelant ne possède pas déjà une session Immersive valide.

Une URL contient un seul ?. Tous les paramètres suivants sont séparés par &.

3.1 Filtrer les extensions

Le paramètre peut être répété :

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=131&AllowedExtensions=.jpg&AllowedExtensions=.png&AllowedExtensions=.pdf

Il peut également contenir une liste séparée par des virgules :

AllowedExtensions=.jpg,.png,.pdf

Règles :

  • la casse est ignorée ;
  • le point initial est facultatif ;
  • les valeurs vides sont ignorées ;
  • si le paramètre est absent ou vide, toutes les extensions sont affichées ;
  • le filtre porte sur le nom du fichier ;
  • ce filtre est une règle d’affichage, pas une autorisation de sécurité.

3.2 Résolution complète de RelativePath

RelativePath peut traverser successivement :

  1. des dossiers Immersive, identifiés par leur propriété Name ;
  2. le chemin interne d’un Blob, à partir du premier dossier possédant un VirtualFolderPath.

Les segments sont séparés par /.

Avec RootFolderIdentifier

Le chemin commence sous le dossier ciblé. Le nom de la racine ne doit pas être répété.

Arborescence :

Projets (Identifier=10)
└── Chantier A
    └── MNM Blob (VirtualFolderPath configuré)
        └── 06 PLANS VITRINES
            └── SC01

URL :

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=10&RelativePath=Chantier%20A%2FMNM%20Blob%2F06%20PLANS%20VITRINES%2FSC01

Chantier A et MNM Blob sont résolus dans Immersive. 06 PLANS VITRINES/SC01 est ensuite résolu dans le Blob.

Si la racine ciblée est elle-même le dossier Blob, le chemin ne contient que les segments Blob :

https://mon-serveur/Business/Resources/Explorer?RootFolderIdentifier=15&RelativePath=06%20PLANS%20VITRINES%2FSC01

Sans RootFolderIdentifier

Le premier segment doit être le nom d’un dossier Immersive sans parent. Ce dossier devient la racine de départ de la résolution.

https://mon-serveur/Business/Resources/Explorer?RelativePath=MNM%20Blob%2F06%20PLANS%20VITRINES%2FSC01

Dans cet exemple, MNM Blob doit être un dossier Immersive sans parent. Les segments restants sont résolus dans son Blob.

Si plusieurs dossiers racine portent le même nom, le dossier ayant le plus petit Identifier est utilisé. Il est donc recommandé de donner des noms uniques aux dossiers racine utilisés dans une URL.

Règles de chemin

  • utiliser / comme séparateur ;
  • ne pas fournir d’URL absolue ;
  • ne pas utiliser les segments . ou .. ;
  • encoder les espaces et caractères spéciaux dans l’URL ;
  • les noms des dossiers Immersive sont comparés sans tenir compte de la casse ;
  • les noms et préfixes Blob conservent les règles de casse d’Azure Blob Storage ;
  • chaque segment d'un Folder Immersive doit correspondre à un enfant direct du segment précédent ;
  • dès qu’un dossier virtuel est rencontré, tous les segments restants appartiennent au Blob.

Il est recommandé de construire l’URL avec URL et URLSearchParams :

const url = new URL("/Business/Resources/Explorer", window.location.origin);
url.searchParams.set("Render", "Kiosk");
url.searchParams.set("RootFolderIdentifier", "10");
url.searchParams.append("AllowedExtensions", ".pdf");
url.searchParams.append("AllowedExtensions", ".ifc");
url.searchParams.set(
    "RelativePath",
    "Chantier A/MNM Blob/06 PLANS VITRINES/SC01"
);

3.3 Exemple d’URL complet

https://mon-serveur/Business/Resources/Explorer?Render=Kiosk&Token=<JETON>&RootFolderIdentifier=15&AllowedExtensions=.jpg&AllowedExtensions=.png&AllowedExtensions=.pdf&AllowedExtensions=.ifc&AllowedExtensions=.riv&RelativePath=sous-repertoire%2Fsous-repertoire-2

4. Authentification et sécurité

La page et les API de l’Explorer sont protégées par la sécurité globale d’Immersive.

Deux contextes sont pris en charge :

  • une session Immersive est déjà active ;
  • un jeton est transmis avec Token=<JETON>, notamment en mode Kiosk.

Le composant transmet automatiquement le jeton présent dans l’URL de la page :

  • dans l’en-tête Authorization: Bearer de ses appels JSON ;
  • dans les URL de médias appartenant au même serveur.

Bonnes pratiques :

  • utiliser HTTPS ;
  • produire les URL contenant un jeton côté serveur ;
  • limiter la durée et les droits du jeton ;
  • ne jamais placer un vrai jeton dans un dépôt, une documentation, une capture d’écran ou un journal accessible ;
  • ne pas utiliser AllowedExtensions comme contrôle d’accès.

4.1 Droits de gestion des dossiers

L’édition repose sur les permissions de l’objet sécurisé Folder :

Permission Valeur du Flag Usage dans l’Explorer
See 1 Voir le dossier.
Read 3 Lire son contenu.
Modify 5 Modifier son nom et sa description.
Write 11 Créer un sous-dossier et, dans une évolution ultérieure, ajouter des médias.
FullControl 15 Supprimer un dossier et administrer tous ses droits.

Les droits par défaut sont appliqués à chaque dossier Immersive : lecture pour le groupe Users de l’organisation et contrôle total pour ses Administrators, les administrateurs globaux du serveur, les administrateurs du domaine et Cerebrate. Les dossiers existant avant cette évolution peuvent être régularisés depuis l’audit des droits par défaut de RestFrontage.

EnableEditing ne constitue jamais une autorisation. Le serveur recalcule les capacités renvoyées au composant, contrôle l’ouverture de chaque modale, puis contrôle de nouveau la requête d’enregistrement.

Les dossiers Blob restent en lecture seule. La suppression d’un dossier Immersive est refusée tant qu’il contient au moins un sous-dossier ou un média.

5. Monter un conteneur Azure Blob

Un dossier virtuel est un Folder Immersive dont VirtualFolderPath contient l’URL racine du conteneur :

https://monstockage.blob.core.windows.net/mon-conteneur

Les préfixes séparés par / sont présentés comme des sous-dossiers :

06 PLANS VITRINES/SC01/plan-01.pdf
06 PLANS VITRINES/SC01/plan-02.pdf
06 PLANS VITRINES/SC02/plan-03.pdf

Conditions de la version actuelle :

  • le serveur RestFrontage doit pouvoir joindre Azure ;
  • la lecture et l’énumération du conteneur doivent être accessibles anonymement ;
  • VirtualFolderPath doit cibler la racine du conteneur, pas un fichier ;
  • les paramètres après ?, notamment un SAS, ne sont pas conservés pendant l’énumération ;
  • la pagination Azure par marqueur n’est pas encore gérée : un très grand conteneur peut nécessiter une évolution complémentaire.

6. Intégration dans une iframe

<iframe
    src="https://mon-serveur/Business/Resources/Explorer?Render=Kiosk&amp;RootFolderIdentifier=15&amp;AllowedExtensions=.pdf"
    title="Documents du projet"
    loading="lazy"
    allow="fullscreen">
</iframe>

Si sandbox est utilisé, autoriser selon le besoin :

  • allow-scripts pour exécuter l’Explorer ;
  • allow-same-origin pour le contexte d’authentification ;
  • allow-downloads pour les téléchargements ;
  • allow-popups pour l’ouverture des fichiers dans un nouvel onglet.

La CSP de RestFrontage et celle de la page parente doivent autoriser l’intégration.

7. Référence exhaustive de l’intégration JavaScript

7.1 Construction

L’Explorer est distribué sous forme de deux fichiers autonomes dont les chemins relatifs au serveur Rest courant sont :

/css/media-explorer.css
/js/media-explorer.js

Pour la consultation seule, ils ne dépendent ni de css/site.css, ni de js/common.js, ni de jQuery ou Bootstrap. La feuille de style doit être chargée dans la page et le script doit être chargé avant le code qui construit l’Explorer.

Par contre Le mode édition utilise les modales de RestFrontage et les fonctions ShowModal, UpdateData, ShowProcessingModal, HideProcessingModal et showToast de js/common.js. Une intégration externe qui active EnableEditing doit donc aussi reprendre le layout de modales, Bootstrap et common.js, ou fournir des fonctions compatibles.

const explorer = new MediaExplorer(hostElement, options);
await explorer.initialize();

hostElement doit être un élément HTML existant. Le constructeur prépare l’état ; initialize() génère l’interface puis charge les données.

Exemple complet :

<link rel="stylesheet" href="/css/site.css">
<link rel="stylesheet" href="/css/media-explorer.css">

<div id="MediaExplorerHost"></div>

<script src="/js/commons.js"></script>
<script src="/js/media-explorer.js"></script>
<script>
    const explorer = new MediaExplorer(
        document.getElementById("MediaExplorerHost"),
        {
            RootFolderIdentifier: 15,
            CurrentFolderIdentifier: 15,
            RelativePath: "06 PLANS VITRINES/SC01",
            AllowedExtensions: [".pdf", ".ifc"],
            ApiBaseUrl: "/api/Explorer",
            DefaultFileIconUrl: "/Content/Common/file.svg",
            DefaultFolderIconUrl: "/Content/Common/folder.svg",
            DownloadOnClick: true,
            EnableEditing: true,
            ExtensionIconUrlBuilder: (extension, media) =>
                extension ? `/Content/Common/${extension.substring(1)}.svg` : null,
            MimeTypeIconUrlBuilder: (mimeType, media) =>
                mimeType ? `/Content/Common/${mimeType.replace("/", "-")}.svg` : null,
            Labels: {
                Up: "Niveau supérieur"
            },
            OnFolderChanged: folder => console.log("Dossier", folder),
            OnMediaClicked: media => console.log("Fichier", media),
            OnMediaDoubleClicked: media => console.log("Double-clic", media),
            OnError: error => console.error(error)
        }
    );

    await explorer.initialize();
</script>

Pour la consultation seule, les deux fichiers peuvent être servis directement par RestFrontage ou copiés dans les assets de l’application cliente. Si l’application cliente et l’API RestFrontage n’ont pas la même origine, ApiBaseUrl doit être une URL absolue et RestFrontage doit autoriser cette origine dans sa configuration CORS.

7.2 Toutes les options

Option Type Défaut Description
RootFolderIdentifier number | null null Racine imposée. null active le mode multi-racines.
CurrentFolderIdentifier number | null null Dossier ouvert initialement en l’absence de RelativePath. Il doit appartenir à la racine imposée.
RelativePath string | null null Chemin initial mixte Immersive/Blob. Il est résolu une fois au chargement initial.
AllowedExtensions string[] [] Extensions visibles. Un tableau vide autorise tout.
ApiBaseUrl string "/api/Explorer" Préfixe des routes API.
DefaultFileIconUrl string "/Content/Common/file.svg" Icône générique utilisée pour un fichier non prévisualisable ou en repli.
DefaultFolderIconUrl string "/Content/Common/folder.svg" Icône des dossiers et de l’arborescence.
ExtensionIconUrlBuilder function | null null Construit une icône à partir de (extension, media). Retourner une URL ou null.
MimeTypeIconUrlBuilder function | null null Construit une icône à partir de (mimeType, media). Retourner une URL ou null.
DownloadOnClick boolean false Si true, un clic ouvre le fichier. Sinon, l’ouverture par défaut se fait au double-clic.
EnableEditing boolean false Demande l’affichage des commandes de dossier autorisées par le serveur. Ne confère aucun droit.
Labels object voir ci-dessous Surcharge partielle des textes de l’interface.
OnFolderChanged function | null null Reçoit le dossier après une navigation réussie.
OnMediaClicked function | null null Reçoit le média après un clic simple.
OnMediaDoubleClicked function | null null Reçoit le média au double-clic lorsque DownloadOnClick vaut false.
OnError function | null null Reçoit l’objet Error après affichage de l’erreur dans l’interface.

La page intégée au RestFrontage surcharge les valeurs par défaut suivantes :

  • DownloadOnClick: true ;
  • EnableEditing: true ;
  • ExtensionIconUrlBuilder vers /Content/Common/{extension}.svg ;
  • MimeTypeIconUrlBuilder vers /Content/Common/{mime-type}.svg.

7.3 Tous les libellés (Labels)

Labels est une surcharge partielle : seules les clés fournies sont remplacées.

Clé Valeur par défaut Emplacement ou situation
Folders "Dossiers" Titre du panneau gauche et texte du bouton mobile ouvrant ce panneau.
Root "Racine" Nom de la racine synthétique du mode multi-racines.
Up "Remonter" Libellé accessible et infobulle du bouton flèche parent. Pour le remplacer, utiliser par exemple Up: "Niveau supérieur".
Loading "Chargement…" Barre d’état pendant une requête.
EmptyFolder "Ce dossier est vide." Zone de contenu sans enfant ni média.
Folder "Dossier" Métadonnée affichée sous une carte de dossier. Cette clé ne contrôle pas le titre Dossiers.
VirtualFolder "Dossier virtuel" Métadonnée affichée sous une carte de dossier Blob.
Virtual "Virtuel" Métadonnée ajoutée sous un fichier provenant d’un Blob.
CreateFolder "Nouveau dossier" Bouton de création dans le dossier courant.
EditFolder "Modifier" Bouton de modification du dossier courant.
DeleteFolder "Supprimer" Bouton de suppression du dossier courant.
Refresh "Rafraîchir" Bouton de rechargement de l’arborescence et du dossier courant.
EditingUnavailable "Les outils d’édition de l’Explorer ne sont pas disponibles sur cette page." Erreur lorsque EnableEditing est actif sans infrastructure de modales compatible.
Retry "Réessayer" Bouton affiché après une erreur récupérable.
TreeLoadError "Impossible de charger l’arborescence." Erreur réseau ou générique pendant le chargement de l’arbre.
FolderLoadError "Impossible de charger le contenu du dossier." Erreur réseau ou générique pendant le chargement d’un dossier.
UnauthorizedError "Votre session a expiré ou le jeton est invalide." Réponse HTTP 401.
ForbiddenError "Vous n’avez pas accès à cette ressource." Réponse HTTP 403.
NotFoundError "La ressource demandée est introuvable." Réponse HTTP 404.
UnexpectedError "Une erreur inattendue est survenue." Erreur sans message exploitable.

Exemple avec toutes les clés :

Labels: {
    Folders: "Documents",
    Root: "Tous les espaces",
    Up: "Niveau supérieur",
    Loading: "Chargement en cours…",
    EmptyFolder: "Aucun document disponible.",
    Folder: "Répertoire",
    VirtualFolder: "Répertoire distant",
    Virtual: "Distant",
    CreateFolder: "Créer un répertoire",
    EditFolder: "Renommer",
    DeleteFolder: "Effacer",
    Refresh: "Actualiser",
    EditingUnavailable: "L’édition n’est pas disponible dans cette intégration.",
    Retry: "Recharger",
    TreeLoadError: "L’arborescence ne peut pas être chargée.",
    FolderLoadError: "Le contenu ne peut pas être chargé.",
    UnauthorizedError: "Authentification requise.",
    ForbiddenError: "Accès refusé.",
    NotFoundError: "Élément introuvable.",
    UnexpectedError: "Une erreur est survenue."
}

Les symboles graphiques de navigation ainsi que les unités de taille ne sont pas configurables par Labels dans la version actuelle. La clé Up configure néanmoins le nom accessible et l’infobulle de la flèche parent.

7.4 Résolution des icônes

Pour un média, l’ordre de résolution est :

  1. miniature réelle si media.IsImage et media.PreviewUrl sont renseignés ;
  2. résultat de ExtensionIconUrlBuilder(extension, media) ;
  3. résultat de MimeTypeIconUrlBuilder(media.ContentType, media) ;
  4. DefaultFileIconUrl.

Si l’image choisie ne charge pas, DefaultFileIconUrl est essayé. Si le repli échoue aussi, l’image est masquée. Les dossiers utilisent DefaultFolderIconUrl puis masquent l’image si cette URL échoue.

L’extension fournie au builder est normalisée en minuscules et commence par un point, par exemple .pdf.

7.5 Comportement des clics

Configuration Clic simple Double-clic
DownloadOnClick: true Sélectionne, appelle OnMediaClicked, puis ouvre DownloadUrl. Aucun traitement supplémentaire.
DownloadOnClick: false Sélectionne et appelle OnMediaClicked. Appelle OnMediaDoubleClicked s’il existe ; sinon ouvre DownloadUrl.

Les fichiers sont ouverts dans un nouvel onglet. Une iframe avec sandbox doit donc autoriser les téléchargements ou fenêtres nécessaires.

7.6 Tous les callbacks

OnFolderChanged(folder)

Appelé après navigateToFolder() et après un retour à la racine synthétique. Il n’est pas appelé par le tout premier initialize().

OnMediaClicked(media)

Appelé après chaque clic simple, avant l’ouverture automatique éventuelle.

OnMediaDoubleClicked(media)

Appelé uniquement au double-clic lorsque DownloadOnClick vaut false. Sa présence remplace l’ouverture automatique au double-clic.

OnError(error)

Appelé après l’affichage de l’erreur. Pour une réponse HTTP, error.status contient notamment 401, 403 ou 404. Pour une erreur réseau, status peut être absent.

7.7 Toutes les méthodes publiques supportées

Méthode Retour Description
initialize() Promise<void> Construit l’interface et effectue le chargement initial. À appeler une fois après le constructeur.
load() Promise<void> Recharge l’arbre et le dossier courant. Résout également le RelativePath initial s’il n’a pas encore été consommé.
navigateToFolder(folder) Promise<void> Ouvre un dossier à partir d’un identifiant ou d’un objet dossier.
setAllowedExtensions(extensions) Promise<void> Remplace le filtre et recharge la vue courante. [] autorise tout.
setRootFolder(rootFolderIdentifier) Promise<void> Change la racine, réinitialise la navigation et recharge. null, 0 ou une valeur négative réactive le mode multi-racines.
setSidebarOpen(isOpen) void Ouvre ou ferme le panneau responsive.
refreshFolder(folderIdentifier) Promise<void> Recharge l’arbre et ouvre le dossier demandé après une mutation. null revient à la racine disponible. Normalement déclenchée par le partial de rafraîchissement.
destroy() void Vide le contenu HTML de l’hôte. L’instance ne doit plus être utilisée sans nouvelle initialisation.

Exemples :

await explorer.load();
await explorer.navigateToFolder(58);
await explorer.navigateToFolder({
    Identifier: 15,
    Path: "06 PLANS VITRINES/SC01",
    IsVirtual: true
});
await explorer.setAllowedExtensions([".jpg", ".png"]);
await explorer.setAllowedExtensions([]);
await explorer.setRootFolder(42);
await explorer.setRootFolder(null);
explorer.setSidebarOpen(true);
explorer.setSidebarOpen(false);
await explorer.refreshFolder(42);
explorer.destroy();

8. Structure des objets transmis aux callbacks

8.1 Objet dossier

Propriété Type Description
Identifier number | null Identifiant de l'objet Folder. null uniquement pour la racine synthétique.
Key string Clé stable d’affichage : Folder:{id}, Virtual:{path} ou ExplorerRoot.
Name string Nom affiché.
Description string | null Description éventuelle.
ParentIdentifier number | null Identifiant du parent Folder.
Path string | null Chemin Blob relatif pour un dossier virtuel.
IsVirtual boolean Indique un dossier Blob.
IsExplorerRoot boolean | undefined Vaut true uniquement pour la racine synthétique cliente.
CreationDate date JSON ou absente Date de création du dossier.
LastModificationDate date JSON, null ou absente Dernière modification connue.
HasChildren boolean Indique la présence possible de sous-dossiers.
HasMedia boolean Indique la présence possible de médias.

8.2 Objet média

Propriété Type Description
Identifier number Identifiant du Media ; vaut 0 pour un fichier virtuel.
Key string Media:{id} ou VirtualMedia:{path}.
Name string Nom du fichier.
Description string | null Description éventuelle.
ContentType string | null Type MIME connu.
Handle string | null Chemin serveur éventuel ; ne doit pas être utilisé directement par le client.
ParentFolderIdentifier number Identifier du Dossier (Folder) propriétaire ou dossier de montage.
Size number | null Taille en octets.
CreationDate date JSON Date de création connue.
LastModificationDate date JSON ou null Dernière modification connue.
Extension string Extension normalisée, par exemple .pdf.
Path string | null Chemin Blob relatif pour un fichier virtuel.
IsVirtual boolean Indique un fichier Blob.
IsImage boolean Indique un format d’image reconnu.
CanPreview boolean Indique qu’une prévisualisation est disponible.
PreviewUrl string | null URL de miniature ou de contenu image.
DownloadUrl string | null URL d’ouverture ou de téléchargement.

9. Référence exhaustive des API HTTP

Toutes les routes sont des GET sous /api/Explorer et nécessitent le même contexte d’authentification que la page.

9.1 GET /api/Explorer/GetTree

Charge l’arborescence Immersive.

Query string Type Obligatoire Description
RootFolderIdentifier entier Non Racine imposée. Sans valeur, charge toutes les arborescences partant d’un dossier sans parent.

Réponse JSON :

{
  "RootFolderIdentifier": 0,
  "Folders": [
    {
      "Identifier": 15,
      "Name": "MNM Blob",
      "ParentIdentifier": null,
      "HasChildren": true
    }
  ]
}

RootFolderIdentifier vaut 0 dans la réponse du mode multi-racines.

9.2 GET /api/Explorer/GetFolderContent

Charge le dossier courant, son parent, ses enfants, ses médias et son fil d’Ariane.

Query string Type Obligatoire Description
RootFolderIdentifier entier Non Racine de sécurité/navigation.
FolderIdentifier entier Conditionnel Dossier courant. Peut être omis si RelativePath est fourni ou si une racine est fournie.
AllowedExtensions chaîne CSV Non Extensions visibles. Une valeur vide autorise tout.
Path chaîne Non Chemin interne à un dossier Blob déjà identifié par FolderIdentifier. Utilisé pour la navigation courante.
RelativePath chaîne Non Chemin initial mixte Immersive/Blob résolu depuis la racine explicite ou les racines globales.

Path et RelativePath ont des rôles différents : un intégrateur doit utiliser RelativePath pour une ouverture initiale et laisser le composant gérer Path pendant la navigation Blob.

Principales propriétés de réponse :

Propriété Description
RootFolderIdentifier Racine demandée ou 0 en mode multi-racines.
IsVirtual Indique que le contenu courant provient d’un Blob.
Path Chemin courant dans le Blob.
VirtualFolderPath URL de montage du dossier virtuel.
CurrentFolder Dossier courant.
ParentFolder Parent navigable ou null.
Children Sous-dossiers directs.
Media Fichiers directs après filtrage.
Breadcrumb Étapes du fil d’Ariane Immersive puis Blob.
Capabilities.CanCreateFolder Autorise l’affichage de la création lorsque EnableEditing est actif.
Capabilities.CanEditFolder Autorise l’affichage de la modification lorsque EnableEditing est actif.
Capabilities.CanDeleteFolder Autorise l’affichage de la suppression lorsque EnableEditing est actif.
RootCapabilities.CanCreateFolder Autorise la création dans la racine synthétique pour l’organisation courante.

9.3 GET /api/Explorer/GetBreadcrumb

Route conservée pour compatibilité. Le composant actuel n’en a plus besoin, car GetFolderContent renvoie déjà Breadcrumb.

Query string Type Obligatoire Description
RootFolderIdentifier entier Non Racine imposée.
FolderIdentifier entier Oui Dossier courant.
Path chaîne Non Chemin Blob courant.

La réponse contient { "Items": [...] }.

9.4 GET /api/Explorer/GetContent/{mediaIdentifier}

Diffuse un média ou un fichier référencé par Handle.

Paramètre de route Type Description
mediaIdentifier entier Identifiant du média Immersive.

Le contenu est lu en flux séquentiel. Un fichier physique prend en charge les requêtes de plage HTTP.

9.5 GET /api/Explorer/GetVirtualContent

Diffuse un fichier appartenant à un dossier virtuel.

Query string Type Obligatoire Défaut Description
FolderIdentifier entier Oui — Identifiant du dossier portant VirtualFolderPath.
Path chaîne Oui — Chemin du fichier dans le Blob.
Download booléen Non false Ajoute une disposition attachment lorsque la valeur vaut true.

Le serveur relaie le contenu Blob en streaming.

9.8 Codes HTTP utiles

Code Signification habituelle
200 Requête réussie.
400 Paramètre manquant, chemin absolu ou présence de . / ...
401 Session absente, jeton expiré ou invalide.
403 Identité authentifiée mais non autorisée.
404 Racine, dossier, chemin ou fichier introuvable ; dossier extérieur à la racine imposée.

10. Résolution des problèmes

Session expirée ou jeton invalide

  • vérifier l’expiration du jeton ;
  • vérifier que l’URL contient un seul ? ;
  • vérifier que Token n’a pas été tronqué ou doublement encodé.

Accès refusé

Le compte ou le jeton ne possède pas les droits nécessaires. Contacter un administrateur Immersive.

Ressource introuvable

  • vérifier RootFolderIdentifier ;
  • retirer la racine pour contrôler la présence du dossier en mode multi-racines ;
  • vérifier chaque nom de dossier Immersive de RelativePath ;
  • avec une racine imposée, ne pas répéter son nom dans RelativePath ;
  • sans racine imposée, vérifier que le premier segment est le nom d’un dossier sans parent ;
  • vérifier la casse des segments Blob ;
  • vérifier que le fichier ou le conteneur existe.

Dossier Blob vide ou sous-dossiers absents

  • vérifier VirtualFolderPath ;
  • vérifier que l’URL cible la racine du conteneur ;
  • vérifier l’accès anonyme en lecture et en énumération ;
  • vérifier que RestFrontage peut joindre Azure ;
  • vérifier que les noms Blob utilisent / ;
  • vérifier que le résultat Azure ne nécessite pas une page suivante non encore gérée.

Certains fichiers n’apparaissent pas

  • vérifier AllowedExtensions ;
  • retirer complètement ce paramètre pour tout afficher ;
  • vérifier que le fichier possède bien l’extension attendue.

Le téléchargement ne démarre pas dans une iframe

Vérifier sandbox, allow-downloads, allow-popups, la CSP et le blocage des fenêtres surgissantes du navigateur.

11. Checklist d’intégration

  • Le mode multi-racines ou la racine imposée correspond au besoin de sécurité et de navigation.
  • Les noms utilisés dans RelativePath correspondent à une chaîne parent/enfant réelle.
  • Le premier segment de RelativePath désigne une racine d'un dossier Immersive lorsque RootFolderIdentifier est absent.
  • Les segments Blob respectent la casse Azure.
  • Les extensions sont précisées, ou le filtre est omis pour tout afficher.
  • Le compte ou le jeton possède les droits nécessaires.
  • L’URL utilise un seul ?, puis des &.
  • Le chemin est relatif et correctement encodé.
  • Le conteneur Blob est joignable, lisible et énumérable.
  • L’iframe autorise les scripts, ouvertures et téléchargements nécessaires.
  • Aucun vrai jeton n’est conservé dans le code source ou la documentation.
  • Le comportement est vérifié sur ordinateur et sur mobile.

Développeur