Freigeben über


Integration der Personenauswahl

Die Personenauswahl ist ein Eingabesteuerelement in Microsoft Teams, mit dem Benutzer Personen suchen und auswählen können. Sie können die Personenauswahl in eine Web-App integrieren, sodass Endbenutzer verschiedene Funktionen ausführen können, z. B. Personen in einem Chat, Kanal oder in der gesamten Organisation innerhalb Microsoft Teams suchen und auswählen. Das Personenauswahl-Steuerelement ist für alle Microsoft Teams-Clients verfügbar, z. B. Web, Desktop und Mobil.

Sie können die JavaScript-Clientbibliothek von Microsoft Teams verwenden, die die selectPeople API bereitstellt, um das Eingabesteuerelement für die Personenauswahl in Ihre Web-App zu integrieren.

Vorteile der Verwendung der Personenauswahl

  • Funktioniert für alle Teams-Funktionen, z. B. Dialog (in TeamsJS v1.x als Aufgabenmodul bezeichnet), Chat, Kanal, Besprechungsregisterkarte und persönliche App.
  • Ermöglicht es dem Benutzer, Personen in einem Chat, Kanal oder der gesamten Organisation innerhalb Microsoft Teams zu suchen und auszuwählen.
  • Hilft in Szenarien mit Aufgabenzuweisung, Tagging und Benachrichtigung von Benutzern.
  • Spart im Vergleich zum Erstellen eines ähnlichen Steuerelements viel Zeit und Mühe.

Verwenden Sie die selectPeople API, um die Personenauswahl in Ihre Microsoft Teams-App zu integrieren. Um die API zu integrieren und aufzurufen, müssen Sie über ein gutes Verständnis des zugehörigen Codeausschnitts verfügen. Außerdem benötigen Sie Kenntnisse über API-Antwortfehler.

selectPeople-API

Mit der selectPeople-API können Sie den Web-Apps die Personenauswahl von Microsoft Teams hinzufügen. Weitere Vorteile:

  • Ermöglicht es dem Benutzer, eine oder mehrere Personen in einer Liste zu suchen und auszuwählen.
  • Gibt die ID, den Namen und die E-Mail-Adresse ausgewählter Benutzer an die Web-App zurück.

Bei einer persönlichen App sucht das Steuerelement in der Organisation nach Namen oder E-Mail-ID innerhalb Microsoft Teams. Wenn die App einem Chat oder Kanal hinzugefügt wird, wird der Suchkontext basierend auf dem Szenario konfiguriert. Die Suche ist auf die Mitglieder dieses Chats oder Kanals beschränkt.

Die selectPeople-API umfasst die folgenden Eingabekonfigurationen:

Konfigurationsparameter Typ Beschreibung Standardwert
title Zeichenfolge Ein optionaler Parameter; legt den Titel für das Steuerelement "Personenauswahl" fest. selectPeople
setSelected Zeichenfolge Ein optionaler Parameter. Sie müssen Microsoft Entra IDs der Personen übergeben, die vorab ausgewählt werden sollen. Dieser Parameter wählt Personen beim Starten der Personenauswahl vorab aus. Bei einer einzelnen Auswahl wird nur der erste gültige Benutzer vorab geladen, während der Rest ignoriert wird. Null
openOrgWideSearchInChatOrChannel Boolescher Wert Optionaler Parameter. Wenn er auf "true" festgelegt ist, wird die Personenauswahl mit organisationsweitem Bereich gestartet, auch wenn die App einem Chat oder Kanal hinzugefügt wird. False
singleSelect Boolean Optionaler Parameter. Wenn er auf "true" festgelegt ist, wird die Personenauswahl gestartet und die Auswahl auf nur einen Benutzer beschränkt. False

Die folgende Abbildung zeigt die Personenauswahl auf Mobilgeräten und Desktops:

Die Personenauswahl ermöglicht dem Benutzer das Suchen und Hinzufügen von Personen mithilfe der folgenden Schritte:

  1. Geben Sie den Namen der erforderlichen Person ein. Eine Liste mit Namensvorschlägen wird angezeigt.

  2. Wählen Sie den Namen der erforderlichen Person aus der Liste aus.

    Screenshot: Auswahlauswahl auf Mobilgeräten

Codeausschnitt

Der folgende Codeausschnitt zeigt die Verwendung der selectPeople-API für eine Liste an:

people.selectPeople({ setSelected: ["aad id"], openOrgWideSearchInChatOrChannel: true, singleSelect: false, title: true}).then(people) => 
 {
    output(" People length: " + people.length + " " + JSON.stringify(people));
 }).catch((error) => { /*Unsuccessful operation*/ });

Fehlerbehandlung

In der folgenden Tabelle sind die Fehlercodes und deren Beschreibungen aufgeführt:

Fehlercode Fehlername Beschreibung
100 NOT_SUPPORTED_ON_PLATFORM Die API wird auf der aktuellen Plattform nicht unterstützt.
500 INTERNAL_ERROR Interner Fehler beim Starten der Personenauswahl.
4000 INVALID_ARGUMENTS Die API wird mit falschen oder nicht ausreichenden obligatorischen Argumenten aufgerufen.
8000 USER_ABORT Der Benutzer hat den Vorgang abgebrochen.
9000 OLD_PLATFORM Der Benutzer befindet sich auf einem alten Plattformbuild, in dem die Implementierung der API nicht verfügbar ist. Führen Sie ein Upgrade auf die neueste Version des Builds durch, um das Problem zu beheben.

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Registerkarte "Personenauswahl" Dieses Beispiel zeigt das Feature der Personenauswahl mithilfe des Teams js Client SDK auf der Registerkarte. View View Anzeigen

Siehe auch