Hinzufügen einer benutzerdefinierten Vorschau, einer Öffnen-Funktion sowie von Aktionen zu Dateien mithilfe von Dateihandlern der Version 2.0

Artikel
04/08/2023

Dateihandler sind eine Art für Microsoft 365-Add-In, das benutzerdefinierte Dateitypen in den Dienst integriert und es Ihnen ermöglicht, reichhaltige Erfahrungen für jedes proprietäre Format bereitzustellen.

Über Dateihandler können Sie die folgenden Benutzerfunktionen in OneDrive for Business und SharePoint-Dokumentbibliotheken implementieren:

Benutzerdefinierte Dateisymbole (für proprietäre Dateierweiterungen)
Erstellen neuer Dateien im Browser (für proprietäre Dateierweiterungen)
Dateivorschau (für proprietäre Dateierweiterungen)
Erweiterte Ansichts- und Bearbeitungsfunktionen (alle Dateierweiterungen)
Benutzerdefinierte Aktionen, die in Ihrer App starten (alle Dateierweiterungen)
Unterstützung für Mehrfachauswahl sowie Aktionen für Ordner (nur benutzerdefinierte Aktionen)

Weitere Details finden Sie in den Beispiellösungen für Dateihandler.

Wichtig

Dateihandlerkonfigurationen werden für eine optimale Leistung im gesamten System aggressiv zwischengespeichert. Es kann 24–48 Stunden dauern, bis Konfigurationsänderungen wirksam werden. Informationen zum Konfigurieren von Dateihandlern finden Sie unter Registrieren.

Änderungen bei Dateihandler 2.0

Das Upgrade 2.0 für Dateihandler ermöglicht zusätzliche Szenarien für SharePoint Online und OneDrive for Business:

Verwenden der Microsoft Graph-API für stabileren Zugriff auf Dateien, einschließlich Dateimetadaten, Berechtigungen und Freigabe
Hinzufügen von Schaltflächen für benutzerdefinierte Aktionen, die Ihr Dateihandler-Add-In starten, einschließlich benutzerdefiniertem Text und benutzerdefinierter Symbole

Inhalt eines Dateihandlers

Ein Dateihandler besteht aus den folgenden Komponenten:

Dateihandlerendpunkt. Dieser Endpunkt kann optional Funktionen zur Erstellung sowie zur Bearbeitung aller Dateien bereitstellen, die in Ihrem Dateihandler registriert sind. Auch eine Dateivorschau kann bereitgestellt werden.
Dateihandlermanifest. Ein Satz von Metadaten, der die Interaktion zwischen Office 365 und Ihrem Dateihandlerendpunkt definiert.
Eine in Azure Active Directory registrierte Anwendung: Diese Anwendung wird verwendet, um den Zugriff auf ausgewählte Dateien über Microsoft Graph zu autorisieren. In ihr wird auch das Dateihandlermanifest registriert.

Dateihandler-Endpunkt

Der Dateihandlerendpunkt ist eine in der Cloud gehostete App, die die Funktionslogik zum Erstellen, Anzeigen, Öffnen und Speichern von Dateien des von ihr verarbeiteten Typs enthält. Es kann auf jedem Stapel gehostet werden, einschließlich Nicht-Microsoft-Stapeln. Dateihandler verwenden Azure Active Directory, um autorisierten Zugriff auf Office 365 Ressourcen zu erhalten, sodass Ihre Anwendung bei Azure AD registriert werden muss. Weitere Informationen zum Registrieren einer Anwendung bei Azure AD finden Sie unter Registrieren Ihrer App für Microsoft Graph.

Alle verfügbaren Beispiele für Dateihandler finden Sie in der Liste der verfügbaren Beispiele.

Dateihandlermanifest

Das Manifest definiert die Interaktion zwischen Office 365 und dem Dateihandler-Endpunkt. Es ist bei Azure Active Directory registriert, über die Sammlung addIns für ein Anwendungsobjekt im Verzeichnis. Informationen zur Registrierung eines Dateihandlermanifests sowie zur Registrierungsaktualisierung finden Sie im Artikel zum Thema Manuelles Registrieren eines Dateihandlers.

Hier ein Beispiel für ein Dateihandlermanifest:

{
    "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" }
    ]
}

Jedes Dateihandlermanifest enthält die folgenden Schlüssel-Wert-Paare im Array properties:

Eigenschaftenname	Typ	Beschreibung
version	String	Hier geben Sie die Version des Dateihandlers an. Dieser Wert muss auf `2` gesetzt werden. Erforderlich für Dateihandler der Version 2.0.
appIcon	String, encoded JSON	Eine Zusammenstellung von Symbol-URLs in verschiedenen Formaten, die zur Darstellung der Dateihandler-Anwendung verwendet werden. Optional.
fileTypeDisplayName	String	Die Beschreibung des Dateityps in der Sprache des Standardgebietsschemas. Optional.
fileTypeIcon	String, encoded JSON	Eine Zusammenstellung von Symbol-URLs in verschiedenen Formaten, die zur Darstellung von Dateitypen verwendet werden, die von diesem Dateihandler behandelt werden. Optional.
actionMenuDisplayName	Zeichenfolge	Optional. Eine Anzeigezeichenfolge im standardmäßigen Gebietsschema, das verwendet wird, wenn mit diesem Dateihandler verbundene Aktionen in einem Menü reduziert werden.
actions	String, encoded JSON	Eine Sammlung von Aktionen, die von der Dateihandlererweiterung implementiert werden. Weitere Informationen finden Sie im Artikel zum Thema Definieren von Aktionen. Erforderlich.

Dateihandler zur Laufzeit

Das Dateihandler-Add-In wird über die Endpunkt-URL aufgerufen, die im Dateihandlermanifest für die aufgerufene Aktion definiert ist. Betrachten wir zur Verdeutlichung ein Szenario, in dem ein Benutzer auf eine Datei klickt, um die Dateivorschau anzuzeigen. Wenn ein registrierter Dateihandler für den betreffenden Dateityp existiert, ruft Office 365 die Dateihandler-App auf, über eine POST-Anforderung an die für die Aktion preview definierte URL. In den Text der POST-Anforderung schreibt Office 365 die Aktivierungsparameter, die die ausgewählte Datei definieren. Die anderen Aktionen, einschließlich newFile, open und custom, werden ebenso aufgerufen.

Aktivierungsparameter

In den vorherigen Szenarien benötigt Ihre Dateihandler-App Details, die als Aktivierungsparameter bezeichnet werden, über die Datei, den Mandanten, Office 365 Client usw., um mit der ausgewählten Datei zu arbeiten. Office 365 enthält diese Details als Formulardaten, die in der POST-Anforderung an den Dateihandlerendpunkt gesendet werden, der der Aktion des Benutzers zugeordnet ist. Diese Parameter sind in der Anforderung mit dem MIME-Typ application/x-www-form-urlencoded enthalten und im Text der Anforderung URL-codiert.

Die folgenden Parameter werden als Aktivierungsparameter bereitgestellt:

Parametername	Typ	Beschreibung
cultureName	string	Die Gebietsschema-ID für die aktuelle Anzeigesprache des Benutzers
client	string	Die Office 365-Anwendung, über die der Dateihandler aufgerufen wurde, beispielsweise „SharePoint“ oder „OneDrive“
userId	string	Die UPN/Anmelde-E-Mail-Adresse des Benutzers, der den Dateihandler aufgerufen hat
domainHint	string	Eine Domänen-Hinweiszeichenfolge, die entweder `organizations` oder `consumers` angibt.
items	JSON string collection of URLs	Eine Sammlung von Microsoft Graph-URLs zu den ausgewählten Elementen

Diese Werte werden als Formularwerte in die POST-Anforderung geschrieben.

Hier eine Beispielanforderung an den Dateihandler-Endpunkt:

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

Hinweis: Die URLs, die in der Auflistung der Elemente zurückgegeben werden, können sehr lang sein (jedoch kürzer als die maximale URL-Länge von 2.048 Zeichen). Jede URL umfasst ein in die URL eingebettetes Token, mit dem die Dateinhandler-App auf die Inhalte zugreifen kann, ohne dass eine Berechtigung mit voller Vertrauenswürdigkeit erforderlich ist. Ihre Dateihandler-Endpunkt sollte jedoch sicherstellen, dass er lange URLs für die Rückgabe erwartet und sie korrekt behandelt.

ASP.NET-Entwickler können über die Sammlung Request.Form auf diese Werte zugreifen, beispielsweise wie folgt:

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

Die Aktivierungsparameter sollten zwischengespeichert werden, wenn die Anforderung eingeht, entweder in einem serverseitigen Cache oder in Cookies beim Senden der Antwort. Bei der ersten Dateihandleranforderung muss die Dateihandler-App den Benutzer wahrscheinlich zur Azure Active Directory-OAuth2-Oberfläche umleiten, damit er ein Zugriffstoken abrufen kann. Werden die Aktivierungsparameter vor dieser Umleitung nicht gespeichert, gehen sie verloren.

Ein Beispiel für die Verwendung eines Datenmodellobjekts und einer Handlermethode für die Zwischenspeicherung der Aktivierungsparameter in einem Cookie finden Sie in den unten in den Beispiellösungen verlinkten C#- oder TypeScript-Beispielen.

Beispiellösungen für Dateihandler

Nahtlose Authentifizierung mit Dateihandlern der Version 2.0

Wenn Ihr Dateihandler eine Anforderung mit Aktivierungsparametern empfängt, muss er ein Zugriffstoken abrufen, um API-Aufrufe an Microsoft Graph senden zu können. Die App muss den Azure Active Directory-Authentifizierungsendpunkt aufrufen, um ein Zugriffstoken für den angemeldeten Benutzer abzurufen. Um einmaliges Anmelden zu ermöglichen und zu vermeiden, dass der Benutzer ein Konto auswählen muss, können Sie den Parameter login_hint verwenden und den Wert des Aktivierungsparameters userId bereitstellen.

In einigen Fällen fordert der Dateihandler den Benutzer möglicherweise dazu auf, sich anzumelden. Wenn Ihr Dateihandler als preview-Aktion ausgeführt wird, können Sie innerhalb eines IFRAME nicht zur Anmeldung zurückkehren und Sie müssen die Anmeldung für Ihren Dateihandler per Popup-Meldung realisieren.

Dateihandler-Verfügbarkeit

In der folgenden Tabelle sind die Office 365-Dienste aufgeführt, die Dateihandler unterstützen:

Dienstname	Dateihandler Version 2.0	Dateihandler Version 1.0
SharePoint Online	Allgemein verfügbar	Allgemein verfügbar
OneDrive for Business	Allgemein verfügbar	Allgemein verfügbar
OneDrive Personal	Nicht verfügbar	Nicht verfügbar
Outlook Web App	Nicht verfügbar	Allgemein verfügbar

Freigeben über