Freigeben über

Aufrufen eines Outlook-Add-Ins in einer Nachricht mit Aktionen

  • Artikel

Nachrichten mit Aktionen ermöglichen es dem Benutzer, schnelle Aktionen für eine E-Mail-Nachricht auszuführen, und Outlook-Add-Ins ermöglichen es Ihnen, Outlook zu erweitern, um neue Features und Interaktionen hinzuzufügen. Mit dem Aktionstyp Action.InvokeAddInCommand können Sie nun diese beiden Arten von Integration kombinieren, um leistungsstärkere und ansprechendere Benutzeroberflächen zu erstellen. So haben Sie zum Beispiel die folgenden Möglichkeiten:

  • Senden Sie neuen Benutzern nach der Registrierung für Ihren Dienst eine Begrüßungsnachricht als Aktion erfordernde E-Mail mit einer Aktion, mit der sie das Add-In schnell installieren und verwenden können.
  • Verwenden Sie ein Add-In für komplexere Aktionen (um dem Benutzer ein Formular zu präsentieren) bei Szenarien, in denen eine einfache Aktion zur Eingabe nicht ausreichend wäre.
  • Füllen Sie Elemente der Benutzeroberfläche im Add-In vorab aus, bevor Sie die Benutzeroberfläche dem Benutzer präsentieren.

Action.InvokeAddInCommand-Aktionen können Add-Ins, die bereits vom Benutzer installiert wurden, oder noch nicht installierte Add-Ins verwenden. Wenn das erforderlich Add-In nicht installiert ist, wird der Benutzer aufgefordert, das Add-In mit einem einzigen Mausklick zu installieren.

Hinweis

Die Installation des erforderlichen Add-Ins mit nur einem Klick wird nur unterstützt, wenn das Add-In in AppSource veröffentlicht wird.

Das folgende Beispiel zeigt die Eingabeaufforderung, die Benutzern angezeigt wird, wenn das Add-In nicht installiert ist.

Screenshot der Aufforderung zum Installieren eines Add-Ins, wenn sie über eine Nachricht mit Aktionen aufgerufen werden.

Aufrufen des Add-Ins

Nachrichten mit Aktionen rufen Add-Ins durch Angabe einer Action.InvokeAddInCommand-Aktion in der Nachricht auf. Diese Aktion gibt das aufzurufende Add-In zusammen mit dem Bezeichner der Add-In-Schaltfläche an, die den entsprechenden Aufgabenbereich öffnet.

Die erforderlichen Informationen befinden sich im Manifest des Add-Ins. Zunächst benötigen Sie die Add-In-ID, die im Id-Element angegeben ist.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
  xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
  xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0"
  xsi:type="MailApp">
  <Id>527104a1-f1a5-475a-9199-7a968161c870</Id>
  <Version>1.0.0.0</Version>
  ...
</OfficeApp>

Für dieses Add-In lautet die Add-In-ID 527104a1-f1a5-475a-9199-7a968161c870.

Im nächsten Schritt benötigen Sie das id-Attribut des Control-Elements, das die Add-In-Schaltfläche definiert, die den entsprechenden Aufgabenbereich öffnet. Bedenken Sie, dass das Control-Element Folgendes erfüllen MUSS:

<ExtensionPoint xsi:type="MessageReadCommandSurface">
  <OfficeTab id="TabDefault">
    <Group id="msgReadCmdGroup">
      <Label resid="groupLabel"/>
      <Control xsi:type="Button" id="showInitContext">
        <Label resid="readButtonLabel"/>
        <Supertip>
          <Title resid="readButtonTitle"/>
          <Description resid="readButtonDesc"/>
        </Supertip>
        <Icon>
          <bt:Image size="16" resid="icon-16"/>
          <bt:Image size="32" resid="icon-32"/>
          <bt:Image size="80" resid="icon-80"/>
        </Icon>
        <Action xsi:type="ShowTaskpane">
          <SourceLocation resid="readPaneUrl"/>
          <SupportsPinning>true</SupportsPinning>
        </Action>
      </Control>
    </Group>
  </OfficeTab>
</ExtensionPoint>

Für diese Add-In-Schaltfläche lautet die ID showInitContext.

Mit diesen beiden Informationen können wir eine grundlegende Action.InvokeAddInCommand-Aktion wie folgt erstellen:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext"
    }
  ]
}

Übergeben von Initialisierungsdaten an das Add-In

Die Action.InvokeAddInCommand-Aktion kann auch zusätzlichen Kontext für das Add-In bereitstellen, der dem Add-In neben der Aktivierung weitere Aktionen ermöglicht. Die Aktion könnte z. B. Anfangswerte für ein Formular oder Informationen bereitstellen, die dem Add-In einen „Deep-Link“ zu einem bestimmten Element in Ihrem Back-End-Dienst ermöglicht.

Um Initialisierungsdaten zu übergeben, schließen Sie eine initializationContext-Eigenschaft in die Action.InvokeAddInCommand-Aktion ein. Es gibt kein Satzschema für die initializationContext-Eigenschaft. Sie können jedes gültige JSON-Objekt einschließen.

Zum Erweitern der Beispielaktion von oben könnten wir die Aktion beispielsweise wie folgt ändern:

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Invoking an add-in command from an Actionable Message card",
      "size": "large"
    }
  ],
  "actions": [
    {
      "type": "Action.InvokeAddInCommand",
      "title": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext",
      "initializationContext": {
        "property1": "Hello world",
        "property2": 5,
        "property3": true
      }
    }
  ]
}

Empfangen von Initialisierungsdaten im Add-In

Wenn die Aktion Initialisierungsdaten übergibt, muss das Add-In darauf vorbereitet sein, sie zu empfangen. Add-Ins können Initialisierungsdaten durch einen Aufruf der Office.context.mailbox.item.getInitializationContextAsync-Methode abrufen. Dies sollte immer dann erfolgen, wenn der Aufgabenbereich eine neue Nachricht öffnet oder lädt.

// Get the initialization context (if present).
Office.context.mailbox.item.getInitializationContextAsync((asyncResult) => {
  if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
    if (asyncResult.value.length > 0) {
      // The value is a string, parse to an object.
      const context = JSON.parse(asyncResult.value);
      // Do something with context.
    } else {
      // Empty context, treat as no context.
    }
  } else {
    // Handle the error.
  }
});

Ressourcen