Freigeben über

Abrufen und Festlegen von Add-In-Metadaten für ein Outlook-Add-In

  • Artikel

Verwalten Sie benutzerdefinierte Daten in Ihrem Outlook-Add-In mithilfe von Roamingeinstellungen, benutzerdefinierten Eigenschaften oder Sitzungsdaten. Diese Optionen bieten Zugriff auf benutzerdefinierte Daten, auf die nur Ihr Outlook-Add-In zugreifen kann, aber jede Methode speichert die Daten getrennt von der anderen. Das heißt, auf die über Roamingeinstellungen gespeicherten Daten kann von benutzerdefinierten Eigenschaften nicht zugegriffen werden und umgekehrt.

Die folgende Tabelle enthält eine Übersicht über die verfügbaren Optionen zum Verwalten von benutzerdefinierten Daten in Outlook-Add-Ins.

Benutzerdefinierte Datenoption Mindestanforderungssatz Gilt für Beschreibung
Roaming-Einstellungen 1.1 Postfach Verwaltet benutzerdefinierte Daten im Postfach eines Benutzers. Das Add-In, das die benutzerdefinierten Daten festlegt, kann von anderen unterstützten Geräten, auf denen das Postfach des Benutzers eingerichtet ist, darauf zugreifen. Auf gespeicherte Daten kann in nachfolgenden Outlook-Sitzungen zugegriffen werden.
Benutzerdefinierte Eigenschaften 1.1 E-Mail-Element Verwaltet benutzerdefinierte Daten für ein E-Mail-Element im Postfach eines Benutzers. Das Add-In, das die benutzerdefinierten Daten festlegt, kann über das E-Mail-Element auf unterstützten Geräten, auf denen das Postfach des Benutzers eingerichtet ist, darauf zugreifen. Auf gespeicherte Daten kann in nachfolgenden Outlook-Sitzungen zugegriffen werden.
Sitzungsdaten 1.11 E-Mail-Element Verwaltet benutzerdefinierte Daten für ein E-Mail-Element in der aktuellen Outlook-Sitzung des Benutzers. Das Add-In, das die benutzerdefinierten Daten festlegt, kann nur über das E-Mail-Element darauf zugreifen, während es zusammengestellt wird.

Hinweis

Informationen zu Anforderungssätzen und den unterstützten Clients finden Sie unter Outlook JavaScript-API-Anforderungssätze.

Um mehr über die einzelnen benutzerdefinierten Datenoptionen zu erfahren, wählen Sie die entsprechende Registerkarte aus.

Mithilfe des RoamingSettings-Objekts können Sie Daten angeben, die spezifisch für das Postfach eines Exchange-Benutzers sind. Beispiele solcher Daten sind die persönlichen Daten und Einstellungen des Benutzers. Ihr Mail-Add-In kann auf Roamingeinstellungen zugreifen, wenn das Roaming auf dem entsprechenden Gerät (Desktop, Tablet oder Smartphone) aktiviert ist.

Änderungen an diesen Daten werden in einer speicherinterne Kopie der Einstellungen für die aktuelle Outlook-Sitzung gespeichert. Sie sollten alle Roamingeinstellungen nach dem Aktualisieren explizit speichern, damit sie verfügbar sind, wenn der Benutzer Das Add-In das nächste Mal auf demselben oder einem anderen unterstützten Gerät öffnet.

Wichtig

Obwohl die Outlook-Add-In-API den Zugriff auf diese Einstellungen nur auf das Add-In beschränkt, das sie erstellt hat, sollten diese Einstellungen nicht als sicherer Speicher betrachtet werden. Auf sie kann von anderen Diensten wie Microsoft Graph zugegriffen werden. Sie sollten nicht zum Speichern vertraulicher Informationen wie Benutzeranmeldeinformationen oder Sicherheitstoken verwendet werden.

Format der Roamingeinstellungen

Die Daten in einem Objekt des Typs RoamingSettings werden als serialisierte JSON-Zeichenfolge (JavaScript Object Notation) gespeichert.

Im Folgenden finden Sie ein Beispiel für die -Struktur, vorausgesetzt, es gibt drei definierte Roamingeinstellungen mit den Namen add-in_setting_name_0, add-in_setting_name_1und add-in_setting_name_2.

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

Laden der Roamingeinstellungen

Ein E-Mail-Add-In lädt in der Regel Roamingeinstellungen im Office.onReady-Handler . Das folgende JavaScript-Codebeispiel zeigt, wie vorhandene Roamingeinstellungen geladen und die Werte der beiden Einstellungen customerName und customerBalance abgerufen werden.

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    _customerName = _settings.get("customerName");
    _customerBalance = _settings.get("customerBalance");
  }
});

Erstellen oder Zuweisen einer Roamingeinstellung

Die folgende JavaScript-Funktion , die mit dem vorherigen Beispiel fortsetzt, setAddInSettingzeigt, wie die RoamingSettings.set-Methode verwendet wird, um eine Einstellung mit dem Namen cookie mit dem heutigen Datum festzulegen. Anschließend werden die Daten mithilfe der RoamingSettings.saveAsync-Methode gespeichert, um alle Roamingeinstellungen im Postfach des Benutzers zu speichern.

Die set -Methode erstellt die Einstellung, wenn die Einstellung noch nicht vorhanden ist, und weist die Einstellung dem angegebenen Wert zu. Die saveAsync -Methode speichert Roamingeinstellungen asynchron. In diesem Codebeispiel wird die Rückruffunktion saveMyAddInSettingsCallbackan saveAsyncübergeben. Wenn der asynchrone Aufruf abgeschlossen ist, saveMyAddInSettingsCallback wird mit einem Parameter aufgerufen, asyncResult. Dieser Parameter ist ein AsyncResult-Objekt, das das Ergebnis und die Details zu dem asynchronen Aufruf enthält. Sie können den optionalen userContext-Parameter verwenden, um jegliche Zustandsinformationen von dem asynchronen Aufruf an die Rückruffunktion zu übergeben.

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

Entfernen einer Roamingeinstellung

Die folgende JavaScript-Funktion , die das vorherige Beispiel noch erweitert, removeAddInSettingzeigt, wie die RoamingSettings.remove-Methode verwendet wird, um die cookie Einstellung zu entfernen und alle Roamingeinstellungen im Postfach zu speichern.

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next Outlook session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

Probieren Sie das Codebeispiel in Script Lab

Um zu erfahren, wie Sie ein RoamingSettings-Objekt erstellen und verwalten, rufen Sie das Script Lab für Outlook-Add-In ab, und probieren Sie das Beispiel "Add-In-Einstellungen verwenden" aus. Weitere Informationen zum Script Lab finden Sie unter Erkunden der Office JavaScript-API mithilfe von Script Lab.

Siehe auch