Ajout de l’aperçu personnalisé, de l’ouverture et d’actions aux fichiers avec les gestionnaires de fichiers 2.0

Article
04/08/2023

Les gestionnaires de fichiers sont un type de complément Microsoft 365 qui intègre des types de fichiers personnalisés au service, ce qui vous permet de fournir des expériences enrichies pour n’importe quel format propriétaire.

Les gestionnaires de fichiers vous permettent d’activer les expériences utilisateur suivantes dans les bibliothèques de documents OneDrive Entreprise et SharePoint :

Icônes de fichiers personnalisées (pour les extensions de fichiers propriétaires)
Création de fichiers dans le navigateur (pour les extensions de fichiers propriétaires)
Aperçu de fichiers (pour les extensions de fichiers propriétaires)
Fonction enrichie d’affichage/de modification (toutes les extensions de fichiers)
Actions personnalisées qui s’ouvrent dans votre application (toutes les extensions de fichiers)
Prise en charge de la sélection multiple et des actions dans les dossiers (actions personnalisées uniquement)

Pour plus d’informations, consultez les exemples de solutions de gestionnaire de fichiers .

Importante

Les configurations de gestionnaire de fichiers sont mises en cache de façon agressive dans le système pour optimiser les performances. La prise en compte des modifications de configuration peut prendre 24-48 heures. Pour plus d’informations sur la configuration des gestionnaires de fichiers, consultez Enregistrement .

Nouveautés des gestionnaires de fichiers 2.0

La mise à niveau 2.0 des gestionnaires de fichiers permet l’ajout de scénarios pour SharePoint Online et OneDrive Entreprise.

Utilisez l’API Microsoft Graph pour accéder en toute sécurité aux fichiers, y compris aux métadonnées de fichier, aux autorisations et au partage.
Ajoutez des boutons d’action personnalisés qui lancent le complément de votre gestionnaire de fichiers, avec un texte et des icônes personnalisés.

Composants du gestionnaire de fichiers

Un gestionnaire de fichiers comprend les éléments suivants :

Point de terminaison du gestionnaire de fichiers. Application hébergée par un fournisseur qui permet de tirer parti de votre gestionnaire de fichier. Ce point de terminaison peut éventuellement permettre la création, la prévisualisation et la modification des fichiers qui sont enregistrés avec votre gestionnaire de fichiers.
Manifeste du gestionnaire de fichiers. Ensemble de métadonnées qui définit l’interaction entre Office 365 et le point de terminaison de votre gestionnaire de fichiers.
Application enregistrée dans Azure Active Directory. Cette application est utilisée pour autoriser l’accès aux fichiers sélectionnés via Microsoft Graph et se trouve à l’endroit où le manifeste du gestionnaire de fichiers est enregistré.

Point de terminaison du gestionnaire de fichiers

Le point de terminaison du gestionnaire de fichiers est une application hébergée dans le cloud qui contient la logique fonctionnelle permettant de créer, d’afficher un aperçu, d’ouvrir et d’enregistrer des fichiers du type qu’elle gère. Il peut être hébergé sur n’importe quelle pile, y compris les piles non-Microsoft. Les gestionnaires de fichiers utilisent Azure Active Directory pour obtenir un accès autorisé aux ressources Office 365, de sorte que votre application doit être inscrite auprès d’Azure AD. Pour plus d’informations sur l’inscription d’une application auprès d’Azure AD, consultez Inscription de votre application pour Microsoft Graph.

Pour obtenir un exemple complet de gestionnaire de fichier, consultez la liste des exemples disponibles.

Manifeste du gestionnaire de fichiers

Le manifeste définit l’interaction entre Office 365 et le point de terminaison du gestionnaire de fichiers. Le manifeste est enregistré auprès d’Azure Active Directory à l’aide de la collection addIns pour un objet d’application dans le répertoire. Pour enregistrer ou mettre à jour l’enregistrement du manifeste de votre gestionnaire de fichiers, consultez la rubrique Procédure : Enregistrer un gestionnaire de fichiers manuellement.

Exemple de manifeste de gestionnaire de fichiers :

{
    "id": "guid",
    "type": "FileHandler",
    "properties": [
        { "key": "version", "value": "2" },
        { "key": "appIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "fileTypeDisplayName", "value": "Contoso Document File" },
        { "key": "fileTypeIcon", "value": "{\"svg\":\"https://example.org/icon.svg\",\"png1x\":\"https://example.org/icon@1x.png\",\"png1.5x\":\"https://example.org/icon@1.5x.png\",\"png2x\":\"https://example.org/icon@2x.png\"}" },
        { "key": "actionMenuDisplayName", "value": "Contoso Actions" },
        { "key": "actions", "value": "json" }
    ]
}

Chaque manifeste de gestionnaire de fichiers inclut les paires clé-valeur suivantes comme partie intégrante du tableau properties :

Nom de la propriété	Type	Description
version	String	Spécifiez la version du gestionnaire de fichiers. Cette valeur doit être définie sur `2`. Obligatoire pour les gestionnaires de fichiers 2.0.
appIcon	Chaîne codée au format JSON	Collection d’URL d’icône dans différents formats, utilisés pour représenter l’application de gestionnaire de fichiers. Facultatif.
fileTypeDisplayName	String	Description des paramètres régionaux par défaut pour le type de fichier. Facultatif.
fileTypeIcon	Chaîne codée au format JSON	Collection d’URL d’icône dans différents formats, utilisés pour représenter des types de fichier gérés par le gestionnaire de ce fichier. Facultatif.
actionMenuDisplayName	String	Facultatif. Chaîne d’affichage dans les paramètres régionaux par défaut utilisée quand les actions associées à ce gestionnaire de fichiers sont réduites dans un menu.
actions	Chaîne codée au format JSON	Ensemble d’actions implémentées par l’extension de ce gestionnaire de fichiers. Consultez la rubrique Spécification d’actions pour plus d’informations. Obligatoire.

Gestionnaires de fichiers en cours d’exécution

Le complément du gestionnaire de fichiers est appelé via l’URL du point de terminaison spécifiée dans le manifeste du gestionnaire de fichiers pour l’action appelée. Pour mieux comprendre ce qui se produit, examinons un scénario où un utilisateur clique pour afficher l’aperçu d’un fichier. S’il existe un gestionnaire de fichiers enregistré pour ce type de fichier, Office 365 appelle l’application du gestionnaire de fichiers en soumettant une requête POST à l’URL spécifiée pour l’action de prévisualisation. Dans le corps de la requête POST, Office 365 inclut les paramètres d’activation qui indiquent le fichier qui a été sélectionné. Les autres actions, y compris newFile, open et custom sont appelées de la même façon.

Paramètres d’activation

Dans les scénarios précédents, votre application de gestionnaire de fichiers nécessite des détails, appelés paramètres d’activation, sur le fichier, le locataire Office 365 client, etc., pour travailler avec le fichier sélectionné. Office 365 inclut ces détails sous forme de données de formulaire envoyées dans la requête POST au point de terminaison du gestionnaire de fichiers associé à l’action de l’utilisateur. Ces paramètres sont inclus dans la requête avec le type application/x-www-form-urlencoded MIME et sont encodés dans l’URL dans le corps de la requête.

Les paramètres suivants sont fournis dans les paramètres d’activation :

Nom de paramètre	Type	Description
cultureName	chaîne	Identificateur des paramètres régionaux pour la langue d’affichage en cours de l’utilisateur.
client	chaîne	Application Office 365 à partir de laquelle le gestionnaire de fichiers a été appelé. Par exemple « SharePoint » ou « OneDrive ».
userId	string	UPN/e-mail de connexion de l’utilisateur qui a appelé le gestionnaire de fichiers.
domainHint	string	Chaîne d’indicateur de domaine qui indique soit `organizations` ou `consumers`.
items	Ensemble de chaînes JSON d’URL	Ensemble d’URL Microsoft Graph permettant d’accéder aux éléments sélectionnés.

Ces valeurs sont codées dans la requête POST comme valeurs de formulaire.

Voici un exemple de demande qui sera envoyée au point de terminaison du gestionnaire de fichiers :

POST https://contoso.com/_api/filehandlers/preview
Content-Type: application/x-www-form-urlencoded

cultureName=en-us&client=OneDrive&userId=rgregg%40contoso.com&items=%5B%22https%3A%2F%2Fgraph.microsoft.com%2Fv1.0%2Fme%2Fdrive%2Fitems%2F4D679BEA-6F9B-4106-AB11-101DDE52B06E%22%5D

Remarque : les URL renvoyées dans la collection d’éléments peuvent être très longues (mais pas plus que la taille maximale des URL, qui est de 2 048 caractères). Chaque URL contient un jeton incorporé dans l’URL qui permet à l’application de gestionnaire de fichiers d’accéder au contenu sans avoir une étendue d’autorisation de confiance totale. En revanche, vérifiez bien que le point de terminaison de votre gestionnaire de fichiers peut renvoyer de longues URL et les gérer correctement.

Pour les développeurs ASP.NET, vous pouvez accéder à ces valeurs à l’aide de la collection Request.Form, par exemple :

var itemsJson = Request.Form["items"];
var itemUrls = JsonConvert.DecodeObject<string[]>(items);

Les paramètres d’activation doivent être mis en cache à l’arrivée de la demande, à l’aide d’un cache côté serveur ou via des cookies sur la réponse. Pour la demande initiale du gestionnaire de fichiers, l’application du gestionnaire de fichiers devra probablement rediriger l’utilisateur pour récupérer un jeton d’accès via OAuth2 Azure Active Directory. Les paramètres d’activation seront perdus s’ils ne sont pas conservés avant cette redirection.

Vous pouvez voir un exemple d’utilisation d’un objet de modèle de données et d’une méthode de gestionnaire de mise en cache les paramètres d’activation dans un cookie, soit dans les exemples C# ou TypeScript liées ci-dessous dans les exemples de solutions.

Exemples de solutions de gestionnaire de fichiers

Authentification transparente avec des gestionnaires de fichiers 2.0

Une fois que votre gestionnaire de fichiers a reçu une demande avec les paramètres de l’activation, il doit récupérer un jeton d’accès pour effectuer des appels d’API vers Microsoft Graph. Votre application devra appeler le point de terminaison d’authentification Azure Active Directory pour récupérer un jeton d’accès pour l’utilisateur connecté. Pour activer l’authentification unique et éviter d’inviter l’utilisateur à sélectionner un compte, vous pouvez utiliser le login_hint paramètre et indiquer la valeur du paramètre d’activation userId.

Dans certains scénarios, votre gestionnaire de fichiers peut inviter l’utilisateur à se connecter. Si votre gestionnaire de fichiers s’exécute comme une action preview, vous devez faire apparaître l’interface de connexion car vous ne pouvez pas rediriger l’utilisateur vers l’interface de connexion à l’intérieur d’un IFRAME.

Disponibilité du gestionnaire de fichiers

Le tableau suivant répertorie les services Office 365 qui prennent en charge les gestionnaires de fichiers.

Nom de service	Gestionnaires de fichiers 2.0	Gestionnaires de fichiers 1.0
SharePoint Online	Généralement disponible	Disponible
OneDrive Entreprise	Disponible	Disponible
OneDrive Personnel	Non disponible	Non disponible
Outlook Web App	Non disponible	Généralement disponible

Partager via