Ouvrir des fichiers Office à partir de votre application

S’applique à : Développeur

Ouvrez des fichiers Office à partir de votre application SharePoint Embedded à l’aide des métadonnées DriveItem de Microsoft Graph et des modèles de lancement Office pris en charge par Microsoft 365.

Commencez par charger, télécharger et gérer les fichiers afin que votre application dispose de fichiers à lancer.

Comprendre les expériences Office

Les expériences de fichiers Office SharePoint Embedded fonctionnent de la même façon que les expériences de fichiers Microsoft 365. Les expériences prises en charge sont les suivantes :

• Ouverture de documents Office dans Office sur le Web.
• Ouverture de documents Office dans les clients de bureau Office.
• Affichage et modification de fichiers.
• Enregistrement automatique pour les fichiers Word, Excel et PowerPoint.
• Historique des versions des documents Office.
• Co-écriture.
• Partage et liens partageables.
• Commentaires et mentions, avec des limitations documentées.
• Barre de navigation dans les clients Office qui associent un fichier à votre application.

Remarque

Les documents stockés dans un conteneur archivé ne peuvent pas être consultés ou accessibles. Votre application doit gérer l’état archivé en affichant une erreur appropriée et en guidant les utilisateurs sur les étapes suivantes, telles que la réactivation du conteneur.

Configuration requise

Avant de lancer les fichiers Office, assurez-vous que :

• Le fichier est stocké dans un conteneur SharePoint Embedded.
• L’application peut lire les métadonnées DriveItem pour le fichier.
• L’utilisateur est autorisé à afficher ou à modifier le fichier.
• Le type de fichier est pris en charge par le client Office cible.
• Votre application gère les redirections du navigateur ou le comportement d’une nouvelle fenêtre.

Obtenir l’URL web DriveItem

Lorsque votre application récupère un élément DriveItem à partir de Microsoft Graph, la réponse peut inclure webUrl.

Pour les types de fichiers Office pris en charge, webUrl pointe vers une URL qui ouvre le document dans Office sur le Web.

Une URL web Office prise en charge a la forme suivante :

https://host/:w:r/contentstorage/sitecollection/_layouts/15/doc2.aspx?sourcedoc=guid&file=filename.docx&action=default&mobileredirect=true

Pour plus d’informations sur la demande, consultez Obtenir une ressource DriveItem.

Lancer Office sur le Web

Utilisez l’élément DriveItem webUrl lorsque votre application doit ouvrir Office dans le navigateur.

1. Lisez l’élément DriveItem du fichier sélectionné.
2. Vérifiez que la réponse inclut webUrl.
3. Ouvrez l’URL dans un onglet de navigateur, une fenêtre ou une surface de navigation contrôlée par l’application.
4. Conservez le contexte de l’application afin que les utilisateurs puissent revenir après modification.
5. Gérez les erreurs d’accès refusé en vérifiant les autorisations de fichier et l’appartenance au conteneur.

Remarque

Les fichiers Office utilisent l’enregistrement automatique lorsque les utilisateurs modifient des fichiers Word, Excel et PowerPoint stockés dans SharePoint Embedded.

Configurer l’expérience de lancement par défaut

Par défaut, l’URL Office inclut action=default.

Pour forcer un mode, mettez à jour le paramètre de requête avec ce modèle :

System.UriBuilder builder = new System.UriBuilder(webUrl);
System.Collections.Specialized.NameValueCollection queryDictionary = System.Web.HttpUtility.ParseQueryString(builder.Query);
queryDictionary["action"] = "view";
builder.Query = queryDictionary.ToString();
string modifiedWebUrl = builder.ToString();

Utilisez :

• action=view pour l’affichage en lecture seule.
• action=edit pour la modification lorsque l’utilisateur dispose d’une autorisation de modification.
• action=default quand Office doit choisir le comportement par défaut.

Pour connaître les valeurs prises en charge action , consultez Actions de l’interface open platform de l’application web.

Ouvrir des fichiers dans les clients de bureau Office

Utilisez des schémas d’URI Office lorsque votre application doit ouvrir des clients de bureau directement.

Le format est :

<scheme-name>:<command-name>|<command-argument-descriptor>|<command-argument>

Les valeurs courantes sont les suivantes :

Segment	Valeur
Nom du schéma	ms-word, ms-excelou ms-powerpoint
Commande Ouvrir la vue de fichier	ofv
Ouvrir la commande Modifier le fichier	ofe
Descripteur d’URL	u

Exemples :

ms-word:ofv|u|https://contoso.com/document.docx
ms-powerpoint:ofe|u|https://contoso.com/presentation.pptx

Remarque

L’URI doit être ouvert dans une fenêtre vide ou un nouvel onglet.

Créer une URL de client de bureau

Étant donné que webUrl pointe vers les documents Office Online pour Office, générez l’URI de bureau en deux étapes :

1. Obtient le webUrl du dossier parent.
2. Ajoutez le nom de fichier.

Exemple de modèle :

ms-word:ofe|u|{folder.WebUrl}/{item.Name}

Forme résultante :

ms-word:ofe|u|https://contoso.sharepoint.com/contentstorage/CSP_1234765465/Document%20Library/MyDocument.docx

Pour plus d’informations sur le schéma, consultez Schémas d’URI Office.

Configurer le comportement de redirection

Utilisez les paramètres de redirection pour rediriger les utilisateurs vers votre application lorsque Microsoft 365 ne peut pas ouvrir un fichier dans une visionneuse prise en charge.

ApplicationRedirectUrl configure l’URL de redirection de l’application sur le type de conteneur. Utilisez-la pour l’itinéraire de l’application qui gère les scénarios de retour de fichiers pour votre charge de travail.

Le urlTemplate paramètre contrôle l’emplacement où Microsoft 365 envoie les utilisateurs pour les fichiers sans visionneuse prise en charge. Les fichiers de visionneuse web Office pris en charge, tels que Word, Excel et PowerPoint, s’ouvrent dans la visionneuse web Office. Les fichiers PDF s’ouvrent dans la visionneuse incorporée. Les autres types de fichiers effectuent une redirection lorsqu’il urlTemplate est configuré. Si urlTemplate n’est pas configuré, Microsoft 365 envoie les utilisateurs à une page d’aide Microsoft.

Définir settings.urlTemplate avec l’API Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} . Utilisez une URL absolue https:// valide qui ne se résout pas en adresse de bouclage.

PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
Content-Type: application/json

{
  "settings": {
    "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}"
  }
}

Microsoft 365 résout les jetons pris en charge, encode leurs valeurs url et les remplace dans le modèle. Les jetons courants incluent {tenant-id}, {drive-id}, {item-id}{folder-id}, {site-domain}, {list-id}, et {site-url}.

Lorsque votre application reçoit une urlTemplate redirection, authentifiez l’utilisateur, analysez les valeurs de jeton et utilisez Microsoft Graph pour récupérer le fichier. Si vous avez besoin de l’URL du fichier canonique, utilisez la propriété DriveItem webDavUrl au lieu de webUrl.

Lorsque vous concevez des redirections :

• Utilisez une URL de production stable pour votre application.
• Utilisez des URL de développement uniquement pour le travail local ou d’essai.
• Gardez Microsoft Entra ID URI de redirection alignés sur les itinéraires d’application.
• Vérifiez que les utilisateurs reviennent au bon contexte dans l’application après les actions Office.
• Évitez la réécriture d’URL qui supprime les paramètres de requête Office requis.
• Vérifiez urlTemplate après les mises à jour, car les valeurs non valides sont stockées en tant que null.

Prise en charge du partage et de la co-création

Les expériences Office incluent des fonctionnalités de collaboration.

Les utilisateurs peuvent partager des documents, créer des liens partageables, co-créer en temps réel, voir les indicateurs de présence, utiliser des commentaires et utiliser des mentions lorsqu’elles sont prises en charge.

Lorsqu’un utilisateur crée un lien de partage, il choisit à qui il accorde l’accès :

Étendue de partage	Qui peut utiliser le lien
Tout le monde	Toute personne qui reçoit le lien, y compris les personnes extérieures à votre organization, que vous l’envoyiez directement ou qu’il soit transféré.
Personnes de votre organisation	Toute personne de votre organization qui a le lien, qu’il soit envoyé directement ou transféré.
Personnes spécifiques	Uniquement les personnes que vous spécifiez. Si l’invitation est transférée, seules les personnes qui ont déjà accès peuvent utiliser le lien.
Utilisateurs ayant un accès existant	People qui ont déjà accès au fichier ou au dossier. Cette étendue ne modifie pas les autorisations existantes.

Remarque

Les mentions nécessitent l’attribution d’une licence Microsoft 365 aux utilisateurs cibles. Les mentions sont limitées aux personnes à l’intérieur de la organization du locataire consommateur et excluent les invités et les utilisateurs d’autres locataires dans les paramètres multilocataires.

Utiliser l’historique des versions

Le contrôle de version est automatiquement activé pour les fichiers Word, Excel et PowerPoint stockés dans les applications SharePoint Embedded.

Les utilisateurs peuvent voir les modifications, comparer les versions, restaurer les versions précédentes, récupérer après des erreurs et passer en revue les modifications des sessions de co-création.

Utiliser les propriétés de navigation

Les clients Office peuvent afficher des éléments de style navigation qui associent des fichiers Office à votre application.

Les modèles de navigation sont construits à partir des propriétés de conteneur configurées pour votre application.

Utilisez le canal actuel pour obtenir des modèles de navigation et des améliorations futures de l’application Office.

Pour plus d’informations sur le canal de mise à jour Office, voir Vue d’ensemble des canaux de mise à jour pour Microsoft 365 Apps.

Valider le lancement d’Office

Testez chaque chemin de lancement :

1. Charger un document Word dans un conteneur.
2. Lisez l’élément DriveItem et capturez webUrl.
3. Ouvrez webUrl avec action=default.
4. Modifiez la chaîne de requête en action=view.
5. Modifiez la chaîne de requête en action=edit.
6. Créez un schéma d’URI Office pour le lancement du bureau.
7. Vérifiez que les autorisations bloquent la modification le cas échéant.
8. Confirmez le comportement de l’enregistrement automatique et de l’historique des versions.
9. Vérifiez que l’utilisateur peut revenir à votre application.

Résoudre les problèmes de lancement d’Office

Symptôme	Vérifier
L’URL s’ouvre dans l’affichage au lieu de modifier	action autorisation de modification du paramètre et de l’utilisateur.
Le client de bureau ne s’ouvre pas	Schéma d’URI Office, stratégie de navigateur et comportement nouvel onglet.
L’utilisateur ne peut pas co-créer	Type de fichier, autorisations et prise en charge du client Office.
Les mentions ne trouvent pas d’utilisateur	Limitations de la licence Microsoft 365 et de l’appartenance au locataire.
La barre de navigation n’a pas l’air juste	Propriétés du conteneur et canal de mise à jour Office.
Rediriger vers un itinéraire incorrect	ApplicationRedirectUrl et gestion des itinéraires d’application.

Étapes suivantes

Ajoutez des aperçus incorporés dans les fichiers en préversion dans votre application.