Freigeben über

Aktivieren von Szenarien für freigegebene Ordner und freigegebene Postfächer in einem Outlook-Add-In

  • Artikel

In diesem Artikel wird beschrieben, wie Sie szenarien für freigegebene Ordner (auch als Stellvertretungszugriff bezeichnet) und freigegebene Postfächer in Ihrem Outlook-Add-In aktivieren, einschließlich der von der Office JavaScript-API unterstützten Berechtigungen.

Hinweis

Die Unterstützung freigegebener Ordner wurde in Anforderungssatz 1.8 eingeführt, während die Unterstützung für freigegebene Postfächer in Anforderungssatz 1.13 eingeführt wurde. Informationen zur Clientunterstützung für diese Features finden Sie unter Unterstützte Clients und Plattformen.

Unterstützte Clients und Plattformen

In der folgenden Tabelle sind unterstützte Client-Server-Kombinationen für dieses Feature aufgeführt, einschließlich des erforderlichen kumulativen Updates, sofern zutreffend. Ausgeschlossene Kombinationen werden nicht unterstützt.

Client Exchange Online: Exchange 2019 lokal
(Kumulatives Update 1 oder höher)		 Exchange 2016 lokal
(Kumulatives Update 6 oder höher)
Webbrowser (moderne Outlook-Benutzeroberfläche) Unterstützt – Nicht zutreffend
Webbrowser (klassische Outlook-Benutzeroberfläche) Nicht zutreffend Nicht zutreffend Nicht zutreffend
neues Outlook unter Windows (Vorschau) Unterstützt – Nicht zutreffend
Windows (klassisch)
Freigegebene Ordner: Version 1910 (Build 12130.20272) oder höher

Freigegebene Postfächer: Version 2304 (Build 16327.20248) oder höher		 Unterstützt Unterstützt* Unterstützt*
Mac
Version 16.47 oder höher		 Unterstützt Unterstützt Unterstützt

Hinweis

* Unterstützung für dieses Feature in einer lokalen Exchange-Umgebung ist ab Outlook unter Windows Version 2206 (Build 15330.20000) für den aktuellen Kanal und Version 2207 (Build 15427.20000) für den monatlichen Enterprise-Kanal verfügbar.

Unterstützte Setups

In den folgenden Abschnitten werden unterstützte Konfigurationen für freigegebene Postfächer und freigegebene Ordner beschrieben. Die Feature-APIs funktionieren in anderen Konfigurationen möglicherweise nicht wie erwartet. Wählen Sie die Plattform aus, die Sie konfigurieren möchten.

Freigegebene Ordner

Der Postfachbesitzer muss zunächst mithilfe einer der folgenden Optionen Zugriff auf einen Delegaten gewähren.

Sobald der Zugriff gewährt wurde, muss die Stellvertretung die Anweisungen befolgen, die im Abschnitt "Hinzufügen des Postfachs einer anderen Person zu Ihrem Profil" des Artikels Verwalten der E-Mails und Kalenderelemente einer anderen Person beschrieben sind.

Freigegebene Postfächer

Exchange-Serveradministratoren können freigegebene Postfächer erstellen und verwalten, auf die Gruppen von Benutzern zugreifen können. Exchange Online und lokale Exchange-Umgebungen werden unterstützt.

Ein Exchange Server-Feature, das als "automapping" bezeichnet wird, ist standardmäßig aktiviert. Dies bedeutet, dass das freigegebene Postfach automatisch in der Outlook-App eines Benutzers angezeigt werden sollte, nachdem Outlook geschlossen und erneut geöffnet wurde. Wenn ein Administrator die automatische Zuordnung jedoch deaktiviert hat, muss der Benutzer die im Abschnitt "Hinzufügen eines freigegebenen Postfachs zu Outlook" des Artikels Öffnen und Verwenden eines freigegebenen Postfachs in Outlook beschriebenen manuellen Schritte ausführen.

Warnung

Melden Sie sich NICHT mit einem Kennwort beim freigegebenen Postfach an. Die Feature-APIs funktionieren in diesem Fall nicht.

Weitere Informationen dazu, wo Add-Ins im Allgemeinen funktionieren und wo sie nicht aktiviert werden, finden Sie auf der Übersichtsseite für Outlook-Add-Ins im Abschnitt Für Add-Ins verfügbare Postfachelemente .

Unterstützte Berechtigungen

In der folgenden Tabelle werden die Berechtigungen beschrieben, die die Office JavaScript-API für Stellvertretungen und Freigegebene Postfachbenutzer unterstützt.

Berechtigung Wert Beschreibung
Lesen 1 (000001) Kann Elemente lesen.
Schreiben 2 (000010) Kann Elemente erstellen.
DeleteOwn 4 (000100) Kann nur die elemente löschen, die sie erstellt haben.
DeleteAll 8 (001000) Kann beliebige Elemente löschen.
BearbeitenOwn 16 (010000) Kann nur die elemente bearbeiten, die sie erstellt haben.
BearbeitenAlle 32 (100000) Kann beliebige Elemente bearbeiten.

Hinweis

Derzeit unterstützt die API das Abrufen vorhandener Berechtigungen, aber nicht das Festlegen von Berechtigungen.

Das DelegatePermissions-Objekt wird mithilfe einer Bitmaske implementiert, um die Berechtigungen anzugeben. Jede Position in der Bitmaske stellt eine bestimmte Berechtigung dar, und wenn sie auf festgelegt ist, verfügt der Benutzer über 1 die entsprechende Berechtigung. Wenn z. B. das zweite Bit von rechts ist 1, verfügt der Benutzer über die Berechtigung Schreiben . Ein Beispiel für die Überprüfung auf eine bestimmte Berechtigung finden Sie weiter unten in diesem Artikel im Abschnitt Ausführen eines Vorgangs als Delegaten oder freigegebenen Postfachbenutzer .

Synchronisierung zwischen Clients mit freigegebenen Ordnern

Die Aktualisierungen eines Delegaten für das Postfach des Besitzers werden in der Regel sofort postfachübergreifend synchronisiert.

Wenn jedoch REST- oder EWS-Vorgänge (Exchange Web Services) verwendet wurden, um eine erweiterte Eigenschaft für ein Element festzulegen, kann die Synchronisierung solcher Änderungen einige Stunden dauern. Es wird empfohlen, stattdessen das CustomProperties-Objekt und zugehörige APIs zu verwenden, um eine solche Verzögerung zu vermeiden. Weitere Informationen finden Sie im Abschnitt "Benutzerdefinierte Eigenschaften " des Artikels "Abrufen und Festlegen von Metadaten in einem Outlook-Add-In".

Wichtig

In einem Delegatszenario können Sie EWS nicht mit den Token verwenden, die derzeit von office.js API bereitgestellt werden.

Konfigurieren des Manifests

Um szenarien für freigegebene Ordner und freigegebene Postfächer in Ihrem Add-In zu aktivieren, müssen Sie die erforderlichen Berechtigungen im Manifest aktivieren.

Um REST-Aufrufe von einem Delegaten zu unterstützen, muss das Add-In zunächst die Lese-/Schreibberechtigung für das Postfach anfordern. Das Markup variiert je nach Art des Manifests.

  • XML-Manifest: Legen Sie das <Permissions-Element> auf ReadWriteMailbox fest.
  • Einheitliches Manifest für Microsoft 365: Legen Sie die Eigenschaft "name" eines Objekts im Array "authorization.permissions.resourceSpecific" auf "Mailbox.ReadWrite.User" fest.

Aktivieren Sie anschließend die Unterstützung für freigegebene Ordner. Das Markup variiert je nach Art des Manifests.

Fügen Sie dem Array "authorization.permissions.resourceSpecific" ein zusätzliches Objekt hinzu, und legen Sie dessen Eigenschaft "name" auf "Mailbox.SharedFolder" fest.

"authorization": {
  "permissions": {
    "resourceSpecific": [
      ...
      {
        "name": "Mailbox.SharedFolder",
        "type": "Delegated"
      },
    ]
  }
},

Ausführen eines Vorgangs als Stellvertretung oder freigegebener Postfachbenutzer

Sie können die freigegebenen Eigenschaften eines Elements im Verfassen- oder Lesemodus abrufen, indem Sie die item.getSharedPropertiesAsync-Methode aufrufen. Dadurch wird ein SharedProperties-Objekt zurückgegeben, das derzeit die Berechtigungen des Benutzers, die E-Mail-Adresse des Besitzers, die Basis-URL der REST-API und das Zielpostfach bereitstellt.

Im folgenden Beispiel wird gezeigt, wie Sie die freigegebenen Eigenschaften einer Nachricht oder eines Termins abrufen, überprüfen, ob der Delegat oder der Benutzer des freigegebenen Postfachs über die Schreibberechtigung verfügt, und einen REST-Aufruf durchführen.

function performOperation() {
  Office.context.mailbox.getCallbackTokenAsync({
      isRest: true
    },
    function (asyncResult) {
      if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value !== "") {
        Office.context.mailbox.item.getSharedPropertiesAsync({
            // Pass auth token along.
            asyncContext: asyncResult.value
          },
          function (asyncResult1) {
            let sharedProperties = asyncResult1.value;
            let delegatePermissions = sharedProperties.delegatePermissions;

            // Determine if user can do the expected operation.
            // E.g., do they have Write permission?
            if ((delegatePermissions & Office.MailboxEnums.DelegatePermissions.Write) != 0) {
              // Construct REST URL for your operation.
              // Update <version> placeholder with actual Outlook REST API version e.g. "v2.0".
              // Update <operation> placeholder with actual operation.
              let rest_url = sharedProperties.targetRestUrl + "/<version>/users/" + sharedProperties.targetMailbox + "/<operation>";
  
              $.ajax({
                  url: rest_url,
                  dataType: 'json',
                  headers:
                  {
                    "Authorization": "Bearer " + asyncResult1.asyncContext
                  }
                }
              ).done(
                function (response) {
                  console.log("success");
                }
              ).fail(
                function (error) {
                  console.log("error message");
                }
              );
            }
          }
        );
      }
    }
  );
}

Tipp

Als Stellvertretung können Sie REST verwenden, um den Inhalt einer Outlook-Nachricht abzurufen, die an ein Outlook-Element oder einen Gruppenbeitrag angefügt ist.

Behandeln des Aufrufens von REST für freigegebene und nicht freigegebene Elemente

Wenn Sie einen REST-Vorgang für ein Element aufrufen möchten, unabhängig davon, ob das Element freigegeben ist oder nicht, können Sie die getSharedPropertiesAsync API verwenden, um zu bestimmen, ob das Element freigegeben ist. Anschließend können Sie die REST-URL für den Vorgang mithilfe des entsprechenden -Objekts erstellen.

if (item.getSharedPropertiesAsync) {
  // In Windows, Mac, and the web client, this indicates a shared item so use SharedProperties properties to construct the REST URL.
  // Add-ins don't activate on shared items in mobile so no need to handle.

  // Perform operation for shared item.
} else {
  // In general, this isn't a shared item, so construct the REST URL using info from the Call REST APIs article:
  // https://learn.microsoft.com/office/dev/add-ins/outlook/use-rest-api

  // Perform operation for non-shared item.
}

Begrenzungen

Abhängig von den Szenarien Ihres Add-Ins gibt es einige Einschränkungen, die Sie beim Behandeln von Situationen mit freigegebenen Ordnern oder freigegebenen Postfächern berücksichtigen sollten.

Nachrichtenerstellungsmodus

Im Nachrichtenerstellungsmodus wird getSharedPropertiesAsync in Outlook im Web oder unter Windows nur unterstützt, wenn die folgenden Bedingungen erfüllt sind.

a. Delegieren des Zugriffs/Freigegebene Ordner

  1. Der Postfachbesitzer startet eine Nachricht. Dies kann eine neue Nachricht, eine Antwort oder eine Weiterleitung sein.
  2. Sie speichern die Nachricht und verschieben sie dann aus ihrem eigenen Ordner Entwürfe in einen Ordner, der für den Delegaten freigegeben ist.
  3. Der Delegat öffnet den Entwurf aus dem freigegebenen Ordner und setzt dann das Verfassen fort.

b. Freigegebenes Postfach (gilt nur für Outlook unter Windows)

  1. Ein Freigegebener Postfachbenutzer startet eine Nachricht. Dies kann eine neue Nachricht, eine Antwort oder eine Weiterleitung sein.
  2. Sie speichern die Nachricht und verschieben sie dann aus ihrem eigenen Ordner Entwürfe in einen Ordner im freigegebenen Postfach.
  3. Ein anderer Benutzer des freigegebenen Postfachs öffnet den Entwurf aus dem freigegebenen Postfach und setzt dann das Verfassen fort.

Die Nachricht befindet sich jetzt in einem freigegebenen Kontext, und Add-Ins, die diese freigegebenen Szenarien unterstützen, können die freigegebenen Eigenschaften des Elements abrufen. Nachdem die Nachricht gesendet wurde, befindet sie sich in der Regel im Ordner Gesendete Elemente des Absenders.

REST und EWS

Ihr Add-In kann REST verwenden. Um rest-Zugriff auf das Postfach des Besitzers oder auf das freigegebene Postfach zu ermöglichen, muss das Add-In die Lese-/Schreibberechtigung für das Postfach im Manifest anfordern. Das Markup variiert je nach Art des Manifests.

  • XML-Manifest: Legen Sie das <Permissions-Element> auf ReadWriteMailbox fest.
  • Einheitliches Manifest für Microsoft 365: Legen Sie die Eigenschaft "name" eines Objekts im Array "authorization.permissions.resourceSpecific" auf "Mailbox.ReadWrite.User" fest.

EWS wird nicht unterstützt.

Benutzer oder freigegebenes Postfach, das in einer Adressliste ausgeblendet ist

Wenn ein Administrator einen Benutzer oder eine freigegebene Postfachadresse aus einer Adressliste wie der globalen Adressliste (GAL) ausgeblendet hat, werden die im Postfachbericht Office.context.mailbox.item geöffneten betroffenen E-Mail-Elemente als NULL angezeigt. Wenn der Benutzer beispielsweise ein E-Mail-Element in einem freigegebenen Postfach öffnet, das in der GAL ausgeblendet ist, Office.context.mailbox.item ist dieses E-Mail-Element NULL.

Siehe auch