Öffnen von Office-Dateien aus Ihrer App

Gilt für: Entwickler

Öffnen Sie Office-Dateien aus Ihrer SharePoint Embedded-App mithilfe von Microsoft Graph DriveItem-Metadaten und Office-Startmustern, die von Microsoft 365 unterstützt werden.

Schließen Sie zuerst Hochladen, Herunterladen und Verwalten von Dateien ab, damit Ihre App Dateien zum Starten hat.

Grundlegendes zu Office-Erfahrungen

SharePoint Embedded Office-Dateierfahrungen funktionieren ähnlich wie Microsoft 365-Dateien. Folgende Funktionen werden unterstützt:

• Öffnen von Office-Dokumenten in Office für das Web.
• Öffnen von Office-Dokumenten in Office-Desktopclients.
• Anzeigen und Bearbeiten von Dateien.
• AutoSpeichern für Word-, Excel- und PowerPoint-Dateien.
• Versionsverlauf für Office-Dokumente.
• Kollaboration.
• Freigabe- und freigabefähige Links.
• Kommentare und Erwähnungen mit dokumentierten Einschränkungen.
• Breadcrumbs in Office-Clients, die Ihrer App eine Datei zuordnen.

Voraussetzungen

Stellen Sie vor dem Starten von Office-Dateien folgendes sicher:

• Die Datei wird in einem SharePoint Embedded-Container gespeichert.
• Die App kann DriveItem-Metadaten für die Datei lesen.
• Der Benutzer verfügt über die Berechtigung zum Anzeigen oder Bearbeiten der Datei.
• Der Dateityp wird vom Office-Zielclient unterstützt.
• Ihre App verarbeitet Browserumleitungen oder das Verhalten des neuen Fensters.

Abrufen der DriveItem-Web-URL

Wenn Ihre App ein DriveItem aus Microsoft Graph abruft, kann die Antwort enthalten webUrl.

Verweist bei unterstützten Office-Dateitypen auf eine URL, webUrl die das Dokument in Office für das Web öffnet.

Eine unterstützte Office-Web-URL hat folgende Form:

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

Details zur Anforderung finden Sie unter Abrufen einer DriveItem-Ressource.

Office für das Web starten

Verwenden Sie driveItem webUrl , wenn Ihre App Office im Browser öffnen soll.

1. Lesen Sie das DriveItem-Element für die ausgewählte Datei.
2. Vergewissern Sie sich, dass die Antwort enthält webUrl.
3. Öffnen Sie die URL auf einer Browserregisterkarte, einem Fenster oder einer von der App gesteuerten Navigationsoberfläche.
4. Behalten Sie den App-Kontext bei, damit Benutzer nach der Bearbeitung zurückkehren können.
5. Behandeln Sie Fehler vom Typ "Zugriff verweigert", indem Sie Dateiberechtigungen und Containermitgliedschaften überprüfen.

Konfigurieren der Standardstarterfahrung

Standardmäßig enthält action=defaultdie Office-URL .

Um einen Modus zu erzwingen, aktualisieren Sie den Abfrageparameter mit diesem Muster:

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();

Verwenden Sie den folgenden:

• action=view zur schreibgeschützten Anzeige.
• action=edit zum Bearbeiten, wenn der Benutzer über die Bearbeitungsberechtigung verfügt.
• action=default wenn Office das Standardverhalten auswählen soll.

Unterstützte action Werte finden Sie unter Web Application Open Platform Interface actions( Web Application Open Platform Interface actions).

Öffnen von Dateien in Office-Desktopclients

Verwenden Sie Office-URI-Schemas, wenn Ihre App Desktopclients direkt öffnen soll.

Das Format lautet wie folgt:

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

Häufige Werte sind:

Beispiele:

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

Erstellen einer Desktopclient-URL

Da webUrl auf Office Online für Office-Dokumente verweist, erstellen Sie den Desktop-URI in zwei Schritten:

1. Ruft die des webUrl übergeordneten Ordners ab.
2. Fügen Sie den Dateinamen an.

Beispielmuster:

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

Resultierende Form:

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

Details zum Schema finden Sie unter Office-URI-Schemas.

Konfigurieren des Umleitungsverhaltens

Verwenden Sie Umleitungseinstellungen, um Benutzer zurück an Ihre App weiterzuleiten, wenn Microsoft 365 eine Datei nicht in einem unterstützten Viewer öffnen kann.

ApplicationRedirectUrl konfiguriert die Anwendungsumleitungs-URL für den Containertyp. Verwenden Sie es für die App-Route, die Dateirückgabeszenarien für Ihre Workload verarbeitet.

Die urlTemplate Einstellung steuert, wohin Microsoft 365 Benutzer für Dateien ohne unterstützten Viewer sendet. Unterstützte Office Web Viewer-Dateien wie Word, Excel und PowerPoint werden im Office Web Viewer geöffnet. PDF-Dateien werden im eingebetteten Viewer geöffnet. Andere Dateitypen leiten durch urlTemplate um, wenn sie konfiguriert sind. Wenn urlTemplate nicht konfiguriert ist, sendet Microsoft 365 Benutzer an eine Microsoft-Hilfeseite.

Legen Sie mit der Microsoft Graph-API PATCH /storage/fileStorage/containerTypes/{containerTypeId} festsettings.urlTemplate. Verwenden Sie eine gültige absolute https:// URL, die nicht in eine Loopbackadresse aufgelöst wird.

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 löst unterstützte Token auf, codiert ihre Werte url-codiert und ersetzt sie in der Vorlage. Gängige Token sind {tenant-id}, {drive-id}, {folder-id}, {item-id}, {site-domain}{list-id}, und {site-url}.

Wenn Ihre App eine urlTemplate Umleitung empfängt, authentifizieren Sie den Benutzer, analysieren Sie die Tokenwerte, und verwenden Sie Microsoft Graph, um die Datei abzurufen. Wenn Sie die kanonische Datei-URL benötigen, verwenden Sie die DriveItem-Eigenschaft webDavUrl anstelle von webUrl.

Wenn Sie Umleitungen entwerfen:

• Verwenden Sie eine stabile Produktions-URL für Ihre App.
• Verwenden Sie Entwicklungs-URLs nur für lokale oder Testversionen.
• Behalten Sie Microsoft Entra ID Umleitungs-URIs bei, die an App-Routen ausgerichtet sind.
• Überprüfen Sie, ob Benutzer nach Office-Aktionen zum richtigen In-App-Kontext zurückkehren.
• Vermeiden Sie das Umschreiben von URLs, die erforderliche Office-Abfrageparameter entfernt.
• Überprüfen Sie urlTemplate nach Updates, da ungültige Werte als nullgespeichert werden.

Unterstützung der Freigabe und der gemeinsamen Dokumenterstellung

Office-Funktionen umfassen Funktionen für die Zusammenarbeit.

Benutzer können Dokumente freigeben, freigegebene Links erstellen, in Echtzeit mitverfassen, Anwesenheitsindikatoren anzeigen, Kommentare verwenden und Erwähnungen verwenden, sofern dies unterstützt wird.

Wenn ein Benutzer einen Freigabelink erstellt, wählt er aus, wem er Zugriff gewährt:

Verwenden des Versionsverlaufs

Die Versionsverwaltung wird automatisch für Word-, Excel- und PowerPoint-Dateien aktiviert, die in SharePoint Embedded-Apps gespeichert sind.

Benutzer können Änderungen anzeigen, Versionen vergleichen, frühere Versionen wiederherstellen, Nach Fehlern wiederherstellen und Änderungen aus Sitzungen zur gemeinsamen Dokumenterstellung überprüfen.

Verwenden von Breadcrumb-Eigenschaften

Office-Clients können Elemente im Breadcrumb-Stil anzeigen, die Ihrer Anwendung Office-Dateien zuordnen.

Breadcrumb-Muster werden aus Containereigenschaften erstellt, die für Ihre App konfiguriert sind.

Verwenden Sie den aktuellen Kanal, um Breadcrumb-Muster und zukünftige Office-App-Verbesserungen zu erhalten.

Informationen zum Office-Updatekanal finden Sie unter Übersicht über Updatekanäle für Microsoft 365 Apps.

Überprüfen des Office-Starts

Testen Sie die einzelnen Startpfade:

1. Laden Sie ein Word Dokument in einen Container hoch.
2. Lesen Sie das DriveItem-Element, und erfassen Sie webUrl.
3. Öffnen Sie webUrl mit action=default.
4. Ändern Sie die Abfragezeichenfolge in action=view.
5. Ändern Sie die Abfragezeichenfolge in action=edit.
6. Erstellen Sie ein Office-URI-Schema für den Desktopstart.
7. Bestätigen Sie ggf. die Bearbeitung von Berechtigungen blockieren.
8. Bestätigen Sie das Verhalten des AutoSpeicherns und des Versionsverlaufs.
9. Vergewissern Sie sich, dass der Benutzer zu Ihrer App zurückkehren kann.

Problembehandlung beim Office-Start

Nächste Schritte

Fügen Sie eingebettete Vorschauversionen in Vorschaudateien in Ihrer App hinzu.