Aufrufen eines Outlook-Add-Ins in einer Nachricht mit AktionenInvoke an Outlook add-in from an actionable message

Über Nachrichten mit Aktionen können Benutzer in einer E-Mail oder Connectorkarte schnelle Aktionen durchführen, und mit Outlook-Add-Ins können Sie Outlook um neue Features und Interaktionen erweitern.Actionable messages allow the user to take quick actions on an email message or connector card, and Outlook add-ins allow you to extend Outlook to add new features and interactions. Mit dem Aktionstyp InvokeAddInCommand können Sie nun diese beiden Arten von Integration kombinieren, um leistungsstärkere und ansprechendere Benutzeroberflächen zu erstellen.Now, with the InvokeAddInCommand action type, you can combine these two types of integrations to create more powerful and compelling experiences. So haben Sie zum Beispiel die folgenden Möglichkeiten:For example, you could:

  • 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.Send a welcome message as an actionable email message to new users after they sign up for your service, with an action that allows them to quickly install and start using your add-in.
  • 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.Use an add-in for more complex actions (i.e. to present a form to the user), for scenarios where a simple action input would not suffice.
  • Füllen Sie Elemente der Benutzeroberfläche im Add-In vorab aus, bevor Sie die Benutzeroberfläche dem Benutzer präsentieren.Pre-populate UI elements in your add-in before presenting UI to the user.

InvokeAddInCommand-Aktionen können Add-Ins, die bereits vom Benutzer installiert wurden, oder noch nicht installierte Add-Ins verwenden.InvokeAddInCommand actions can work with add-ins that are already installed by the user, or they can work with add-ins that are not installed. Wenn das erforderlich Add-In nicht installiert ist, wird der Benutzer aufgefordert, das Add-In mit einem einzigen Mausklick zu installieren.If the required add-in is not installed, the user is prompted to install the add-in with a single click.

Hinweis

Die Installation des erforderlichen-Add-Ins mit nur einem Klick wird nur unterstützt, wenn das Add-In im Office Store veröffentlicht ist.Single-click installation of the required add-in is only supported if the add-in is published in the Office Store.

Das folgende Beispiel zeigt die Eingabeaufforderung, die Benutzern angezeigt wird, wenn das Add-In nicht installiert ist.The following example shows the prompt users see if the add-in is not installed.

Ein Screenshot der Eingabeaufforderung zum Installieren eines Add-Ins beim Aufruf des Add-Ins in einer Aktion erfordernden Nachricht

Aufrufen des Add-InsInvoking the add-in

Nachrichten mit Aktionen rufen Add-Ins durch Angabe einer InvokeAddInCommand-Aktion in der Nachricht auf.Actionable messages invoke add-ins by specifying an InvokeAddInCommand action in the message. Diese Aktion gibt das aufzurufende Add-In zusammen mit dem Bezeichner der Add-In-Schaltfläche an, die den entsprechenden Aufgabenbereich öffnet.This action specifies the add-in to invoke, along with the identifier of the add-in button that opens the appropriate taskpane.

Die erforderlichen Informationen befinden sich im Manifest des Add-Ins.The required information is found in the add-in's manifest. Zunächst benötigen Sie die Add-In-ID, die im Id-Element angegeben ist.First, you'll need the add-in's identifier, which is specified in the Id element.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp 
  xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" 
  xmlns:xsi="http://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.For this add-in, the add-in identifier is 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.Next, you'll need the id attribute of the Control element that defines the add-in button that opens the appropriate taskpane. Bedenken Sie, dass das Control-Element Folgendes erfüllen MUSS:Keep in mind that the Control element MUST:

<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.For this add-in button, the ID is showInitContext.

Mit diesen beiden Informationen können wir eine grundlegende InvokeAddInCommand-Aktion wie folgt erstellen:With these two pieces of information, we can create a basic InvokeAddInCommand action as follows:

{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "title": "Invoking an Add-in command from an Actionable Message card",
  "potentialAction": [
    {
      "@type": "InvokeAddInCommand",
      "name": "Invoke \"View Initialization Context\"",
      "addInId": "527104a1-f1a5-475a-9199-7a968161c870",
      "desktopCommandId": "showInitContext"
    }
  ]
}

Übergeben von Initialisierungsdaten an das Add-InPassing initialization data to the add-in

Die InvokeAddInCommand-Aktion kann auch zusätzlichen Kontext für das Add-In bereitstellen, der dem Add-In neben der Aktivierung weitere Aktionen ermöglicht.The InvokeAddInCommand action can also provide additional context to the add-in, allowing the add-in to do more than just simply activate. 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.For example, the action could provide initial values for a form, or provide information that allows the add-in to "deep link" to a specific item in your back-end service.

Um Initialisierungsdaten zu übergeben, schließen Sie eine initializationContext-Eigenschaft in die InvokeAddInCommand-Aktion ein.In order to pass initialization data, include an initializationContext property in the InvokeAddInCommand action. Es gibt kein Satzschema für die initializationContext-Eigenschaft. Sie können jedes gültige JSON-Objekt einschließen.There is no set schema for the initializationContext property, you can include any valid JSON object.

Zum Erweitern der Beispielaktion von oben könnten wir die Aktion beispielsweise wie folgt ändern:For example, to extend the sample action from above, we could modify the action as follows:

{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "title": "Invoking an Add-in command from an Actionable Message card",
  "potentialAction": [
    {
      "@type": "InvokeAddInCommand",
      "name": "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-InReceiving initialization data in the add-in

Wenn die Aktion Initialisierungsdaten übergibt, muss das Add-In darauf vorbereitet sein, sie zu empfangen.If your action passes initialization data, the add-in must be prepared to receive it. Add-Ins können Initialisierungsdaten durch einen Aufruf der Office.context.mailbox.item.getInitializationContextAsync-Methode abrufen.Add-ins can retrieve initialization data by calling the Office.context.mailbox.item.getInitializationContextAsync method. Dies sollte immer dann erfolgen, wenn der Aufgabenbereich geöffnet wird oder eine neue Nachricht lädt.This should be done whenever the taskpane opens or loads a new message.

// Get the intialization context (if present)
Office.context.mailbox.item.getInitializationContextAsync(
  function(asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Succeeded) {
      if (asyncResult.value != null && asyncResult.value.length > 0) {
        // The value is a string, parse to an object
        var context = JSON.parse(asyncResult.value);
        // Do something with context
      } else {
        // Empty context, treat as no context
      }
    } else {
      if (asyncResult.error.code == 9020) {
        // GenericResponseError returned when there is
        // no context
        // Treat as no context
      } else {
        // Handle the error
      }
    }
  }
);

RessourcenResources