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 Microsoft Graph et des modèles de lancement Office pris en charge par Microsoft 365.

Terminez d’abord le chargement, le téléchargement et la gestion des fichiers afin que votre application dispose de fichiers à lancer.

Lorsque vous stockez des fichiers Office dans un conteneur SharePoint Embedded, votre application est liée à une pile de collaboration complète sans en créer une. Les fichiers Word, Excel et PowerPoint prennent en charge la co-création en temps réel, l’enregistrement automatique, l’historique automatique des versions et le partage via des liens partageables et @mentions, avec des niveaux d’accès étendus. Vous n’avez pas besoin de créer un moteur de collaboration. La modification s’ouvre dans Office sur le Web (dans un nouvel onglet ou une nouvelle fenêtre de navigateur) ou dans les clients de bureau Office, afin que les utilisateurs quittent l’interface utilisateur de votre application pour modifier ; incorporez un aperçu en lecture seule lorsque vous avez besoin d’une visualisation intégrée dans l’application. Pour le contexte de la décision, voir Ajouter la co-édition Office sans le générer.

Comprendre les expériences Office

Les expériences de fichiers SharePoint Embedded Office fonctionnent de la même manière 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.
• Afficher et modifier des 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.
• Barres de navigation dans les clients Office qui associent un fichier à votre application.

Contrôler l’intégration à Office

L’intégration d’Office est activée par défaut pour les types de conteneurs SharePoint Embedded. Les utilisateurs autorisés peuvent ouvrir des fichiers pris en charge dans les clients Office sur le Web et Office pour ordinateur de bureau, notamment via l’expérience Office en dehors de l’interface utilisateur personnalisée de votre application. Si votre application nécessite un accès aux fichiers pour rester dans les expériences contrôlées par l’application, vous pouvez désactiver l’intégration d’Office pour le type de conteneur en définissant la isOfficeRestricted propriété sur fileStorageContainerTypeSettingstrue.

isOfficeRestricted est actuellement disponible uniquement via le point de terminaison Microsoft Graph bêta. Elle n’est pas encore disponible dans la version 1.0. Pour la définition de la propriété, consultez le type de ressource fileStorageContainerTypeSettings.

Défini settings.isOfficeRestricted avec l’API Microsoft Graph PATCH /storage/fileStorage/containerTypes/{containerTypeId} sur le point de terminaison bêta.

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

{
  "settings": {
    "isOfficeRestricted": true
  }
}

Lorsque l’intégration d’Office est désactivée, les utilisateurs ne peuvent pas lancer de fichiers à partir des conteneurs affectés dans les clients Office sur le Web ou Office pour ordinateur de bureau. Avant d’activer cette restriction, assurez-vous que votre application fournit ou dirige les utilisateurs vers une autre expérience appropriée pour afficher ou modifier des fichiers.

Configuration requise

Avant de lancer des fichiers Office, vérifiez les points suivants :

• 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 de nouvelle fenêtre.

Obtenir l’URL web du DriveItem

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

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

Une URL web Office prise en charge comporte 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 le DriveItem webUrl lorsque votre application doit ouvrir Office dans le navigateur.

1. Lire le DriveItem pour le 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. Préservez le contexte de l’application afin que les utilisateurs puissent revenir après la modification.
5. Traitez les erreurs d’accès refusé en vérifiant les autorisations de fichier et l’appartenance au conteneur.

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 le modèle suivant :

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 un affichage en lecture seule.
• action=edit pour la modification lorsque l’utilisateur dispose des autorisations de modification.
• action=default quand Office doit choisir le comportement par défaut.

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

Ouvrir des fichiers dans des clients de bureau Office

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

Le format est :

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

Les valeurs courantes sont les suivantes :

Exemples :

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

Créer une URL pour le client de bureau

Étant donné que webUrl ce point pointe vers les documents Office Online pour Office, créez l’URI de bureau en deux étapes :

1. Obtenir le webUrl dossier parent.
2. Ajoutez le nom du 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 les schémas, voir Schémas d’URI Office.

Configurer le comportement de redirection

Utilisez les paramètres de redirection pour renvoyer 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-le 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 aux utilisateurs 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 intégrée. Les autres types de fichiers sont redirigés vers le via urlTemplate lorsqu’il est configuré. S’il urlTemplate n’est pas configuré, Microsoft 365 dirige les utilisateurs vers 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 une 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 par URL et les remplace dans le modèle. Par exemple, les jetons pris en charge peuvent inclure {tenant-id}, , {folder-id}{drive-id}, {list-id}{item-id}{site-domain}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 les URL de développement uniquement pour le travail local ou d’évaluation.
• Alignez les URI de redirection de Microsoft Entra ID sur les itinéraires d’application.
• Vérifiez que les utilisateurs retournent au contexte d’application approprié après des actions Office.
• Évitez la réécriture d’URL qui supprime les paramètres de requête Office requis.
• Vérification 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

L’expérience Office inclut des fonctionnalités de collaboration.

Les utilisateurs peuvent partager des documents, créer des liens partageables, co-créer en temps réel, voir des indicateurs de présence, utiliser des commentaires et utiliser des mentions là où cela est possible.

Lorsqu’un utilisateur crée un lien de partage, il choisit les personnes auxquelles il accorde l’accès :

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 des erreurs et examiner les modifications des sessions de co-création.

Utiliser les propriétés de la barre de navigation

Les clients Office peuvent afficher des éléments de type fil d’Ariane qui associent des fichiers Office à votre application.

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

Utilisez le canal actuel de mise à jour pour Microsoft 365 Apps afin que les utilisateurs reçoivent le dernier comportement de la barre de navigation Office et les futures améliorations de l’application Office.

Pour plus d’informations sur le canal de mise à jour d’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. Lire le DriveItem et capturer webUrl.
3. Ouvrir 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. Confirmer les autorisations Bloquer 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

Étapes suivantes

Ajoutez des aperçus incorporés dans les fichiers de prévisualisation de votre application.