Übung: Erstellen eines Office-Add-Ins für Excel, das einmaliges Anmelden implementiert
In dieser Übung erstellen Sie ein Excel-Add-In, das eine Liste der zuletzt vom aktuell angemeldeten Benutzer mit Microsoft Graph empfangenen E-Mails in einem Arbeitsblatt hinzufügt. Bei diesem Prozess wird das SSO (Single Sign-On)-Authentifizierungsschema verwendet.
Voraussetzungen
Für die Entwicklung von Office-Add-Ins für Microsoft Excel sind der Webclient oder die folgenden Desktopclients erforderlich:
- Windows v16.0.12215.20006 (oder höher)
- macOS v16.32.19102902 (oder höher)
Sie werden Node.js verwenden, um das benutzerdefinierte Excel-Add-In in diesem Modul zu erstellen. Bei den Übungen in diesem Modul wird vorausgesetzt, dass die folgenden Tools auf Ihrer Entwicklerarbeitsstation installiert sind:
Wichtig
In den meisten Fällen ist die Installation der neuesten Versionen folgender Tools die beste Option. Die hier aufgeführten Versionen wurden verwendet, als dieses Modul veröffentlicht und zuletzt getestet wurde.
- Node.js (die aktuellste LTS-Version).
- NPM (mit Node.js installiert), v6.x (oder höher)
- Yeoman, v3.x (oder höher)
- Yeoman-Generator für Microsoft Office – v1.8.8
- Visual Studio Code
Sie müssen die erforderlichen Mindestversionen dieser Voraussetzungen auf Ihrer Arbeitsstation installiert haben.
Wichtig
Diese Übung wurde für die Arbeit mit dem Yeoman-Generator für Microsoft Office v1.8.8 geschrieben. Stellen Sie sicher, dass Sie diese Version verwenden, indem Sie eine bestimmte Version mit dem Befehl npm install generator-office@1.8.8 --global installieren. In späteren Versionen des Generators wurde das SSO-Projektgerüst entfernt und dann geändert, das nicht mit den Schritten in diesem Lab übereinstimmt.
Wichtig
Das Beispiel in dieser Übung soll nur als Lernressource verwendet werden und ist nicht für die Verwendung in einem Produktionsszenario vorgesehen, da es das OAuth-Token zum Senden von Anforderungen an Microsoft Graph zurück an den Client übergibt, um den Aufruf direkt durchzuführen.
Als bewährte Sicherheitsmethode sollten Sie immer den serverseitigen Code verwenden, um Microsoft Graph-Aufrufe oder andere Aufrufe auszuführen, welche die Übergabe eines Zugriffstokens erfordern. Geben Sie niemals das OBO-Token an den Client zurück, damit der Client direkte Aufrufe an Microsoft Graph durchführen kann. Dadurch wird verhindert, dass der Token abgefangen oder weitergegeben werden kann. Weitere Informationen zum richtigen Protokollfluss finden Sie im OAuth 2.0-Protokolldiagramm.
Erstellen eines Add-In-Projekts
Führen Sie den folgenden Befehl aus, um ein Add-In-Projekt mit dem Yeoman-Generator zu erstellen:
yo office
Hinweis
Wenn Sie den yo office-Befehl ausführen, werden möglicherweise Eingabeaufforderungen zu den Richtlinien für die Datensammlung von Yeoman und den CLI-Tools des Office-Add-In angezeigt. Verwenden Sie die bereitgestellten Informationen, um auf die angezeigten Eingabeaufforderungen entsprechend zu reagieren.
Wenn Sie dazu aufgefordert werden, geben Sie die folgenden Informationen an, um das Add-In-Projekt zu erstellen:
- Projekttyp auswählen: Aufgabenbereichsprojekt für Office-Add-In, das einmaliges Anmelden unterstützt
- Skripttyp auswählen: JavaScript
- Wie soll Ihr Add-In heißen? MyExcelSsoAddin
- Welche Office-Clientanwendung soll unterstützt werden? Excel
Nachdem Sie die Aufforderungen erledigt haben, erstellt der Generator das Projekt und installiert unterstützende Node-Komponenten.
Registrieren der Microsoft Entra-App
Registrieren Sie als Nächstes die Microsoft Entra-Anwendung, und aktualisieren Sie das Projekt für die Verwendung der Microsoft Entra-Anwendung.
Tipp
Ausführliche Informationen zum manuellen Registrieren der Microsoft Entra-Anwendung finden Sie unter Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet: Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt.
Stellen Sie mithilfe der Eingabeaufforderung sicher, dass Sie sich aktuell im Stammverzeichnis des Projekts befinden. Führen Sie anschließend den folgenden Befehl aus:
npm run configure-sso
Der Befehl startet einen Browser und fordert Sie auf, sich bei Microsoft Entra ID anzumelden. Stellen Sie sicher, dass Sie sich als Benutzer anmelden, der über Berechtigungen zum Registrieren einer Microsoft Entra-Anwendung verfügt, z. B. als Benutzer, der der Rolle "Globaler Administrator " zugewiesen ist.
Nach der Authentifizierung werden durch das Skript die folgenden Aufgaben ausgeführt:
- Registrieren der Microsoft Entra-Anwendung
- Konfigurieren der Benutzergruppe und der Berechtigungseinstellungen für die Anwendung
- Erstellen eines neuen geheimen Clientschlüssels und Speichern dieses Schlüssels im Geheimnisspeicher Ihrer Entwicklerarbeitsstation
- Aktualisieren des Projekts mit der Client-ID der Microsoft Entra-Anwendung
Warnung
Der Befehl configure-sso schlägt fehl, wenn Ihr Microsoft Entra-Mandant für die mehrstufige Authentifizierung (Multi-Factor Authentication, MFA)/zweistufige Authentifizierung konfiguriert ist. In diesem Fall müssen Sie die Microsoft Entra-App-Registrierung manuell erstellen, wie im Artikel Erstellen eines Node.js Office-Add-Ins, das einmaliges Anmelden verwendet: Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt beschrieben wird.
Erstellen und Testen der Anwendung
Führen Sie den folgenden Befehl in einer Eingabeaufforderung aus, um zu transpilieren und das Debuggen zu starten:
npm start
Testen des Add-Ins im Excel-Desktopclient
Nach einem kurzen Moment wird Excel mit der Schaltfläche des Add-Ins im Menüband geladen und in den Aufgabenbereich geladen.
Um das Add-In zu testen, wählen Sie die Schaltfläche Meine Benutzerprofilinformationen abrufen aus.
Wenn Sie noch nicht mit Ihrem Office-Client angemeldet sind, werden Sie nun dazu aufgefordert.
Nach der Anmeldung ruft das Add-In Ihre grundlegenden Profilinformationen aus Microsoft Graph ab und fügt sie dem Dokument hinzu.
Aktualisieren der App, um die neuesten E-Mails anzuzeigen.
Aktualisieren wir nun die Aufgabenbereich-App, um eine Liste der letzten E-Mails hinzuzufügen, die der aktuell mit Microsoft Graph angemeldete Benutzer erhalten hat.
Aktualisieren der Berechtigungen der Microsoft Entra-App
Der registrierten Microsoft Entra-App müssen zuerst Berechtigungen für die App erteilt werden.
Öffnen Sie einen Browser, und navigieren Sie zum Microsoft Entra Admin Center (https://aad.portal.azure.com). Melden Sie sich mit einem Geschäfts-, Schul- oder Uni-Konto an, das über globale Administratorrechte für den Mandanten verfügt.
Wählen Sie im Navigationsbereich ganz links Verwalten von >API-Berechtigungen aus.
Fügen Sie eine neue Berechtigung hinzu, indem Sie eine Berechtigung hinzufügen auswählen.
Wählen Sie im Bildschirm API auswählen die Option Microsoft Graph und dann Delegierte Berechtigungen aus. Suchen und wählen Sie die Berechtigung Mail.Read und wählen Sie Berechtigungen hinzufügen.
Wählen Sie als Nächstes die Option Contoso die Zustimmung des Administrators gewähren. In der nun folgenden Bestätigungsaufforderung wählen Sie Ja.
Aktualisieren des Add-Ins für den Excel-Aufgabenbereich
Der nächste Schritt ist es, den Code im Add-In zu aktualisieren.
Aktualisieren des Aufgabenbereichs
Suchen und öffnen Sie die Datei ./src/taskpane/taskpane.html.
Suchen Sie das folgende HTML-Element im Aufgabenbereich:
<div class="ms-firstrun-instructionstep__welcome-body">
Suchen Sie das erste Aufzählungszeichen im HTML-Code und ändern Sie den Inhalt des span Elementes in:
<span class="ms-ListItem-primaryText">Click the <b>Get my last 10 emails</b> button.</span>
Suchen Sie das letzte Aufzählungszeichen im HTML-Code und ändern Sie den Inhalt des span Elementes in:
<span class="ms-ListItem-primaryText">Your last 10 emails will be displayed in the document.</span>
Suchen Sie die Schaltfläche und ändern Sie den Text in: Get last 10 emails.
Aktualisieren des Codes des Aufgabenbereichs
Aktualisieren Sie jetzt den Code, mit dessen Hilfe die letzten zehn E-Mails des Benutzers abgerufen werden.
Suchen und öffnen Sie die Datei ./src/helpers/ssoauthhelper.js.
Suchen Sie die folgende Zeile in der Methode getGraphData():
const response = await sso.makeGraphApiCall(exchangeResponse.access_token);
Suchen Sie diese Zeile, und ersetzen Sie diese durch den folgenden Code. Dieser Code verwendet eine andere Methode im SSO-Hilfsprogramm, um eine bestimmte Anforderung an Microsoft Graph zu senden:
const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);
Als Nächstes suchen und öffnen Sie die Datei ./src/helpers/documentHelper.js.
Suchen Sie die Methode writeDataToExcel(). Sie ersetzen den größten Teil des Codes in dieser Methode, möchten jedoch die Grundstruktur beibehalten. Löschen Sie den Inhalt der Methode und ersetzen Sie ihn durch den folgenden Code:
return Excel.run(function(context) {
const sheet = context.workbook.worksheets.getActiveWorksheet();
// TODO
return context.sync();
});
Ersetzen Sie zuerst den // TODO mit dem folgenden Code, um einige Spaltenüberschriften im Blatt zu erstellen:
const rangeHeading = sheet.getRange("A1:D1");
rangeHeading.values = [["Received Date/Time", "Subject", "Read?", "ID"]];
Fügen Sie als Nächstes den folgenden Code nach dem zuvor hinzugefügten Code hinzu. Dadurch werden die Ergebnisse aus der Microsoft Graph-Anforderung übernommen und in eine mehrdimensionale Matrix konvertiert, um sie in das Arbeitsblatt zu schreiben.
Anschließend werden die Ergebnisse in das Arbeitsblatt geschrieben und die Spalten so formatiert, dass alle Daten sichtbar sind:
// convert data to a list
const mailResults = result.value;
for (let i = 0; i < mailResults.length; i++) {
if (mailResults[i] !== null) {
let innerArray = [];
innerArray.push(mailResults[i].receivedDateTime);
innerArray.push(mailResults[i].subject);
innerArray.push(mailResults[i].isRead);
innerArray.push(mailResults[i].id);
let data = [];
data.push(innerArray);
let rangeData = sheet.getRange(`A${i+2}:D${i+2}`);
rangeData.values = data;
}
}
rangeHeading.format.autofitColumns();
Erstellen und Testen der Anwendung
Führen Sie den folgenden Befehl in einer Eingabeaufforderung aus, um zu transpilieren und das Debuggen zu starten:
npm start
Testen des Add-Ins in Excel
Nach einem kurzen Moment wird Excel mit der Schaltfläche des Add-Ins im Menüband geladen und in den Aufgabenbereich geladen. Lassen Sie uns dies im Excel-Webclient testen.
Öffnen Sie dazu einen Browser, und navigieren Sie zu OneDrive (https://onedrive.com). Melden Sie sich mit einem Geschäfts-, Schul- oder Unikonto an.
Fügen Sie eine neue Excel-Arbeitsmappe hinzu, indem Sie auf die Schaltfläche Neu und dann auf Excel-Arbeitsmappe klicken.
Installieren Sie das Excel-Add-In, indem Sie es zusätzlich laden. Wählen Sie im Menüband Einfügen von>Add-Ins aus.
Wählen Sie im Dialogfeld Office-Add-InsMein Add-In hochladen aus.
Wählen Sie die Datei manifest.xml im Stammverzeichnis des Projekts aus, und wählen Sie dann Hochladen.
Microsoft Word wird das Add-In querladen und die Schaltfläche Aufgabenbereich anzeigen im Menüband anzeigen, genau wie der Desktopclient.
Wählen Sie Schaltfläche Aufgabenbereich anzeigen und dann die Schaltfläche Letzte 10 E-Mails abrufen aus.
Da Sie bereits angemeldet sind, werden nach einem Moment die letzten E-Mails im Arbeitsblatt angezeigt, ohne dass Sie sich anmelden müssen.
