Ö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 zunächst Dateien ab, laden Sie sie herunter und verwalten Sie sie, damit Ihre App über Dateien zum Starten verfügt.

Wenn Sie Office-Dateien in einem SharePoint Embedded-Container speichern, wird Ihre App mit einem Stapel für die vollständige Zusammenarbeit verknüpft, ohne einen erstellen zu müssen. Word-, Excel- und PowerPoint-Dateien unterstützen die gemeinsame Dokumenterstellung in Echtzeit, AutoSpeichern, den automatischen Versionsverlauf und die Freigabe über teilbare Links und @mentions, mit eingegrenzten Zugriffsebenen. Sie müssen kein Modul für die Zusammenarbeit erstellen. Die Bearbeitung wird in Office für das Web (in einer neuen Browserregisterkarte oder einem neuen Fenster) oder in Office-Desktopclients geöffnet, sodass Benutzer die Benutzeroberfläche Ihrer App zum Bearbeiten verlassen. Betten Sie eine schreibgeschützte Vorschau ein, wenn Sie eine Inline-In-App-Anzeige benötigen. Den Entscheidungskontext finden Sie unter Hinzufügen von Office für die gemeinsame Dokumenterstellung ohne es zu erstellen.

Hinweis

@mentions Nur Empfänger benachrichtigen, die über eine Microsoft 365-Lizenz verfügen. Bei der eingebetteten SharePoint-Freigabe werden keine E-Mail-Einladungen gesendet.

Grundlegendes zu Office-Erfahrungen

SharePoint Embedded Office-Dateierfahrungen funktionieren ähnlich wie Microsoft 365 Dateierfahrungen. Folgende Erfahrungen 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.
• Automatisches Speichern für Word-, Excel- und PowerPoint-Dateien.
• Versionsverlauf für Office-Dokumente.
• Kollaboration.
• Freigabe- und teilbare Links.
• Kommentare und Erwähnungen mit dokumentierten Einschränkungen.
• Breadcrumbs in Office-Clients, die Ihrer App eine Datei zuordnen.

Hinweis

In einem archivierten Container gespeicherte Dokumente können nicht angezeigt oder aufgerufen werden. Ihre App muss den archivierten Zustand behandeln, indem sie einen entsprechenden Fehler anzeigt und Benutzer zu den nächsten Schritten führt, z. B. zur Reaktivierung des Containers.

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 Zielclient Office unterstützt.
• Ihre App verarbeitet Browserumleitungen oder das Verhalten neuer Fenster.

Abrufen der DriveItem-Web-URL

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

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

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

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

Anforderungsdetails finden Sie unter Abrufen einer DriveItem-Ressource.

Starten von Office für das Web

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

1. Lesen des DriveItem für die ausgewählte Datei.
2. Vergewissern Sie sich, dass die Antwort enthält webUrl.
3. Öffnen Sie die URL über eine Browserregisterkarte, ein Fenster oder eine App-gesteuerte Navigationsoberfläche.
4. Bewahren Sie den App-Kontext bei, damit Benutzer nach der Bearbeitung zurückkehren können.
5. Behandeln Sie Fehler im Zusammenhang mit verweigertem Zugriff, indem Sie Dateiberechtigungen und Containermitgliedschaft überprüfen.

Hinweis

Office-Dateien verwenden AutoSpeichern, wenn Benutzer Word-, Excel- und PowerPoint-Dateien bearbeiten, die in SharePoint Embedded gespeichert sind.

Konfigurieren der Standardstartumgebung

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 für die schreibgeschützte Anzeige.
• action=edit zur Bearbeitung, wenn der Benutzer über Bearbeitungsberechtigung verfügt.
• action=default wann Office das Standardverhalten auswählen soll.

Unterstützte action Werte finden Sie unter Web Application Open Platform Interface-Aktionen.

Ö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>

Zu den gängigen Werten gehören:

Segment	Wert
Schemaname	ms-word, ms-excel oder ms-powerpoint
Befehl "Dateiansicht öffnen"	ofv
Befehl "Datei öffnen"	ofe
URL-Deskriptor	u

Beispiele:

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

Hinweis

Öffnen Sie den URI in einem leeren Fenster oder auf einer neuen Registerkarte.

Erstellen einer Desktopclient-URL

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

1. Rufen Sie die webUrl des ü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

Einzelheiten zum Schema finden Sie unter Office URI-Schemata.

Umleitungsverhalten konfigurieren

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

ApplicationRedirectUrl Konfiguriert die Anwendungsumleitungs-URL für den Containertyp. Verwenden Sie sie 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 werden bei der Konfiguration umgeleitet urlTemplate . Wenn urlTemplate Microsoft 365 nicht konfiguriert ist, werden die Benutzer an eine Microsoft-Hilfeseite weitergeleitet.

Mit der Microsoft Graph-API PATCH /storage/fileStorage/containerTypes/{containerTypeId} festlegensettings.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 per URL und ersetzt sie in der Vorlage. Unterstützte Token können {tenant-id}beispielsweise , {drive-id}, {folder-id}, {item-id}, {site-domain}{list-id}, und {site-url}sein.

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 Testarbeiten.
• Sorgen Sie dafür, dass Microsoft Entra ID-Umleitungs-URIs an App-Routen ausgerichtet sind.
• Überprüfen, ob Benutzer nach Office-Aktionen zum richtigen In-App-Kontext zurückkehren.
• Vermeiden Sie das Umschreiben von URLs, bei dem erforderliche Office-Abfrageparameter entfernt werden.
• Nach Updates überprüfenurlTemplate, da ungültige Werte gespeichert sind als null

Unterstützung von Freigabe und gemeinsamer Dokumenterstellung

Office-Oberflächen enthalten Features für die Zusammenarbeit.

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

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

Freigabebereich	Wer darf den Link verwenden
Jeder	Jeder, der den Link erhält, einschließlich Personen außerhalb Ihrer organization, unabhängig davon, ob Sie ihn direkt senden oder weitergeleitet werden.
Personen in Ihrer Organisation	Jeder in Ihrer organization, der über den Link verfügt, egal ob direkt gesendet oder weitergeleitet.
Bestimmte Personen	Nur die von Ihnen angegebenen Personen. Wenn die Einladung weitergeleitet wird, können nur Personen, die bereits Zugriff haben, den Link verwenden.
Personen mit vorhandenem Zugriff	People, die bereits Zugriff auf die Datei oder den Ordner haben. Dieser Bereich ändert keine bestehenden Berechtigungen.

Hinweis

Für Erwähnungen muss den Zielbenutzern eine Microsoft 365-Lizenz zugewiesen sein. Erwähnungen sind auf Personen innerhalb der organization des konsumierenden Mandanten beschränkt und schließen Gäste und Benutzer aus anderen Mandanten in mehrinstanzenfähigen Einstellungen aus.

Verwenden des Versionsverlaufs

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

Benutzer können Änderungen anzeigen, Versionen vergleichen, frühere Versionen wiederherstellen, Fehler beheben und Änderungen aus gemeinsamen Dokumenterstellungssitzungen überprüfen.

Verwenden von Breadcrumb-Eigenschaften

Office-Clients können breadcrumb-artige Elemente anzeigen, die Ihrer Anwendung Office-Dateien zuordnen.

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

Verwenden Sie den Updatekanal des aktuellen Kanals für Microsoft 365 Apps, damit Benutzer das neueste Office-Breadcrumb-Verhalten und zukünftige Office-App-Verbesserungen erhalten.

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

Überprüfen des Office-Starts

Testen Sie jeden Startpfad:

1. Hochladen eines Word-Dokuments in einen Container.
2. Read the DriveItem and capture webUrl.
3. Open webUrl with action=default.
4. Ändern Sie die Abfragezeichenfolge in action=view.
5. Ändern Sie die Abfragezeichenfolge in action=edit.
6. Erstellen eines Office-URI-Schemas für den Desktopstart.
7. Bestätigen Sie die Berechtigungen, die Bearbeitung gegebenenfalls zu blockieren.
8. Bestätigen Sie das Verhalten von AutoSpeichern und Versionsverlauf.
9. Vergewissern Sie sich, dass der Benutzer zu Ihrer App zurückkehren kann.

Problembehandlung beim Starten von Office

Problembeschreibung	Prüfen
URL wird in der Anzeige geöffnet, anstatt sie zu bearbeiten.	action Parameter und Benutzerberechtigung zum Bearbeiten.
Desktopclient wird nicht geöffnet	Office-URI-Schema, Browserrichtlinie und Verhalten neuer Registerkarten.
Benutzer kann nicht gemeinsam Dokumente erstellen	Dateityp, Berechtigungen und Office-Clientunterstützung.
Bei Erwähnungen wird kein Benutzer gefunden	Microsoft 365-Lizenz- und Mandantenmitgliedschaftsbeschränkungen.
Breadcrumb sieht nicht richtig aus	Containereigenschaften und Office Update-Kanal.
Umleiten kehrt auf falsche Route zurück	ApplicationRedirectUrl und App-Routenbehandlung.

Nächste Schritte

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