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

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

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.

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.

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 .

Konfigurieren des Manifests

Um freigegebene Ordner und Szenarien für freigegebene Postfächer in Ihrem Add-In zu implementieren, müssen Sie zunächst die Unterstützung für das Feature in Ihrem Manifest konfigurieren. Das Markup variiert je nach Art des Manifests, das ihr Add-In verwendet.

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

...
<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    ...
    <Hosts>
      <Host xsi:type="MailHost">
        <DesktopFormFactor>
          <SupportsSharedFolders>true</SupportsSharedFolders>
          <FunctionFile resid="residDesktopFuncUrl" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <!-- Configure the extension point. -->
          </ExtensionPoint>
          ...
        </DesktopFormFactor>
      </Host>
    </Hosts>
    ...
  </VersionOverrides>
</VersionOverrides>
...

Ermitteln, ob ein Ordner oder Postfach freigegeben ist

Bevor Sie Vorgänge in einem freigegebenen Ordner oder freigegebenen Postfach ausführen können, müssen Sie zunächst ermitteln, ob der aktuelle Ordner oder das aktuelle Postfach freigegeben ist. Um dies zu ermitteln, rufen Sie Office.context.mailbox.item.getSharedPropertiesAsync für eine Nachricht oder einen Termin im Verfassen- oder Lesemodus auf. Wenn sich das Element in einem freigegebenen Ordner oder freigegebenen Postfach befindet, gibt die Methode ein SharedProperties-Objekt zurück, das die Berechtigungen des Benutzers, die E-Mail-Adresse des Besitzers, die Basis-URL der REST-API und den Speicherort des Zielpostfachs bereitstellt.

Im folgenden Beispiel wird die getSharedPropertiesAsync -Methode aufgerufen, um den Besitzer des Postfachs und die Berechtigungen des Delegaten oder freigegebenen Postfachbenutzers zu identifizieren.

Office.context.mailbox.item.getSharedPropertiesAsync((result) => {
  if (result.status === Office.AsyncResultStatus.Failed) {
    console.error("The current folder or mailbox isn't shared.");
    return;
  }
  const sharedProperties = result.value;
  console.log(`Owner: ${sharedProperties.owner}`);
  console.log(`Permissions: ${sharedProperties.delegatePermissions} `);
});

Unterstützte Berechtigungen

In der folgenden Tabelle werden die Berechtigungen beschrieben, die getSharedPropertiesAsync für Stellvertretungen und Freigegebene Postfachbenutzer unterstützt werden.

Die delegatePermissions-Enumeration , die von der delegatePermissions-Eigenschaft zurückgegeben wird, wird mithilfe einer Bitmaske implementiert, um die Berechtigungen anzugeben. Jede Position in der Bitmaske stellt eine bestimmte Berechtigung dar, und wenn sie auf 1festgelegt ist, verfügt der Benutzer über die entsprechende Berechtigung. Wenn z. B. das zweite Bit von rechts ist 1, verfügt der Benutzer über die Berechtigung Schreiben .

Ausführen eines Vorgangs als Stellvertretung oder Benutzer eines freigegebenen Postfachs

Nachdem Sie festgestellt haben, dass sich das aktuelle E-Mail-Element in einem freigegebenen Ordner oder freigegebenen Postfach befindet, kann Ihr Add-In die erforderlichen Vorgänge für das Element in der freigegebenen Umgebung ausführen. Um Vorgänge für ein Element in einem freigegebenen Kontext auszuführen, müssen Sie zuerst die Berechtigung Ihres Add-Ins im Manifest konfigurieren. Verwenden Sie dann Microsoft Graph, um die Vorgänge abzuschließen.

Konfigurieren der Berechtigungen des Add-Ins

Um Microsoft Graph-Dienste verwenden zu können, muss ein Add-In die Lese-/Schreibberechtigung des Postfachs in seinem Manifest konfigurieren. Das Markup variiert je nach Art des Manifests, das ihr Add-In verwendet.

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

Verwenden von Microsoft Graph

Verwenden Sie Microsoft Graph, um Szenarien für freigegebene Ordner und freigegebene Postfächer zu implementieren, um auf zusätzliche Postfachinformationen und -ressourcen zuzugreifen. Sie können beispielsweise Microsoft Graph verwenden, um den Inhalt einer Outlook-Nachricht abzurufen, die an eine Nachricht in einem Postfach angefügt ist, in dem ein Benutzer über Stellvertretungszugriff verfügt. Anleitungen zur Verwendung von Microsoft Graph finden Sie unter Übersicht über Microsoft Graph und die Outlook-Mail-API in Microsoft Graph.

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.

Nachrichtenmodus Compose

Im Nachrichtenmodus Compose wird getSharedPropertiesAsync in Outlook im Web oder unter Windows (neu und klassisch) nur unterstützt, wenn die folgenden Bedingungen erfüllt sind.

• 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.

• Freigegebenes Postfach (gilt nur für das klassische 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.

Sobald diese Bedingungen erfüllt sind, wird die Nachricht in einem freigegebenen Kontext verfügbar, 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 persönlichen Postfachs des Absenders.

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, wurden die im Postfachbericht Office.context.mailbox.item geöffneten 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.

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 Microsoft Graph-Vorgänge zum Festlegen einer erweiterten Eigenschaft für ein Element verwendet wurden, kann die Synchronisierung solcher Änderungen einige Zeit in Anspruch nehmen. Um eine Verzögerung zu vermeiden, empfiehlt es sich, stattdessen das CustomProperties-Objekt und zugehörige APIs zu verwenden. Weitere Informationen finden Sie im Abschnitt "Benutzerdefinierte Daten pro Element in einem Postfach: benutzerdefinierte Eigenschaften" unter Abrufen und Festlegen von Metadaten in einem Outlook-Add-In.

Siehe auch

• Einen Stellvertreter die Verwaltung der E-Mails und des Kalenders vornehmen lassen
• Kalenderfreigabe in Microsoft 365
• Hinzufügen eines freigegebenen Postfachs zu Outlook
• Übersicht über Microsoft Graph