Auf Suchbefehl antworten

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höher des Bot Framework SDK. Wenn Sie nach Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt "Messaging-Erweiterungen – v3 SDK" im Ordner "Ressourcen" der Dokumentation.

Nachdem der Benutzer den Suchbefehl übermittelt hat, empfängt Ihr Webdienst eine composeExtension/query Aufrufnachricht, die ein value Objekt mit den Suchparametern enthält. Dieser Aufruf, der mit den folgenden Bedingungen ausgelöst wird:

  • Wenn Zeichen in das Suchfeld eingegeben werden.
  • initialRun in Ihrem App-Manifest auf "true" festgelegt ist, erhalten Sie die Aufrufnachricht, sobald der Suchbefehl aufgerufen wird. Weitere Informationen finden Sie unter Standardabfrage.

In diesem Dokument erfahren Sie, wie Sie auf Benutzeranforderungen in Form von Karten und Vorschauen reagieren und unter welchen Bedingungen Microsoft Teams eine Standardabfrage ausgibt.

Die Anforderungsparameter befinden sich im value Objekt in der Anforderung, das die folgenden Eigenschaften enthält:

Eigenschaftenname Zweck
commandId Der Name des vom Benutzer aufgerufenen Befehls, der einem der im App-Manifest deklarierten Befehle entspricht.
parameters Array von Parametern. Jedes Parameterobjekt enthält den Parameternamen sowie den vom Benutzer bereitgestellten Parameterwert.
queryOptions Paginierungsparameter:
skip: Anzahl für diese Abfrage überspringen
count: Anzahl der zurückzugebenden Elemente.
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  //code to handle the query
}

Antworten auf Benutzeranforderungen

Wenn der Benutzer eine Abfrage ausführt, Microsoft Teams eine synchrone HTTP-Anforderung an Ihren Dienst ausstellt. An diesem Punkt hat Ihr Code Sekunden Zeit, 5 um eine HTTP-Antwort auf die Anforderung bereitzustellen. Während dieser Zeit kann Ihr Dienst zusätzliche Nachschlagevorgänge oder eine beliebige andere Geschäftslogik ausführen, die für die Bearbeitung der Anforderung erforderlich ist.

Ihr Dienst muss mit den Ergebnissen antworten, die der Benutzerabfrage entsprechen. Die Antwort muss einen HTTP-Statuscode 200 OK und ein gültiges Anwendungs- oder JSON-Objekt mit den folgenden Eigenschaften angeben:

Eigenschaftenname Zweck
composeExtension Antwortumschlag auf oberster Ebene.
composeExtension.type Antworttyp. Die folgenden Typen werden unterstützt:
result: Zeigt eine Liste der Suchergebnisse an
auth: Fordert den Benutzer zur Authentifizierung auf
config: Fordert den Benutzer auf, die Messaging-Erweiterung einzurichten
message: Zeigt eine Nur-Text-Nachricht an
composeExtension.attachmentLayout Gibt das Layout der Anlagen an. Wird für Antworten vom Typ result verwendet.
Derzeit werden die folgenden Typen unterstützt:
list: Eine Liste von Kartenobjekten, die Miniaturansichten, Titel und Textfelder enthalten
grid: Ein Raster mit Miniaturansichten
composeExtension.attachments Array gültiger Anlagenobjekte. Wird für Antworten vom Typ result verwendet.
Derzeit werden die folgenden Typen unterstützt:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions Vorgeschlagene Aktionen. Wird für Antworten vom Typ auth oder config verwendet.
composeExtension.text Anzuzeigende Meldung. Wird für Antworten vom Typ message verwendet.

Antwortkartentypen und Vorschauen

Teams unterstützt die folgenden Kartentypen:

Um ein besseres Verständnis und einen besseren Überblick über Karten zu haben, sehen Sie sich an, was Karten sind.

Informationen zur Verwendung der Miniaturansicht- und Herokartentypen finden Sie unter Hinzufügen von Karten und Kartenaktionen.

Weitere Informationen zur Office 365 Connectorkarte finden Sie unter Verwenden von Office 365 Connectorkarten.

Die Ergebnisliste wird auf der Microsoft Teams Benutzeroberfläche mit einer Vorschau der einzelnen Elemente angezeigt. Die Vorschau wird auf eine der beiden folgenden Arten generiert:

  • Verwenden der preview Eigenschaft innerhalb des attachment Objekts. Die preview Anlage kann nur ein Held oder eine Miniaturansichtskarte sein.
  • Extrahieren aus den title grundlegenden text , und Eigenschaften image des attachment Objekts. Die grundlegenden Eigenschaften werden nur verwendet, wenn die preview Eigenschaft nicht angegeben ist.

Für Hero- oder Miniaturansichtskarte werden mit Ausnahme der Aufrufaktion andere Aktionen wie Schaltfläche und Tippen in der Vorschaukarte nicht unterstützt.

Um eine adaptive Karte oder eine Ofiice 365-Connectorkarte zu senden, müssen Sie eine Vorschau einschließen. Die preview Eigenschaft muss eine Hero- oder Miniaturansichtskarte sein. Wenn Sie die Vorschaueigenschaft im Objekt nicht attachment angeben, wird keine Vorschau generiert.

Für Hero- und Miniaturansichtskarten müssen Sie keine Vorschaueigenschaft angeben, eine Vorschau wird standardmäßig generiert. Im folgenden Beispiel wird das Feature zum Aufheben von Links angezeigt, wenn ein Link in die Messaging-Erweiterung eingefügt wird:
Verbreitung von Links

Anforderungsbeispiel

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  //searches NuGet for a package
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

Aktivieren und Behandeln von Tippaktionen

protected override Task<MessagingExtensionResponse> OnTeamsMessagingExtensionSelectItemAsync(ITurnContext<IInvokeActivity> turnContext, JObject query, CancellationToken cancellationToken)
{
    // The Preview card's Tap should have a Value property assigned, this will be returned to the bot in this event. 
    var (packageId, version, description, projectUrl, iconUrl) = query.ToObject<(string, string, string, string, string)>();

    var card = new ThumbnailCard
    {
        Title = "Card Select Item",
        Subtitle = description
    };

    var attachment = new MessagingExtensionAttachment
    {
        ContentType = ThumbnailCard.ContentType,
        Content = card,
    };

    return Task.FromResult(new MessagingExtensionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            Type = "result",
            AttachmentLayout = "list",
            Attachments = new List<MessagingExtensionAttachment> { attachment }
        }
    });
}

Hinweis

OnTeamsMessagingExtensionSelectItemAsync wird in der mobilen Teams-Anwendung nicht ausgelöst.

Standardabfrage

Wenn Sie initialRun true dies im Manifest festlegen, gibt Microsoft Teams eine Standardabfrage aus, wenn der Benutzer die Messaging-Erweiterung zum ersten Mal öffnet. Ihr Dienst kann auf diese Abfrage mit einer Reihe vorab ausgefüllter Ergebnisse antworten. Dies ist nützlich, wenn ihr Suchbefehl eine Authentifizierung oder Konfiguration erfordert und zuletzt angezeigte Elemente, Favoriten oder andere Informationen anzeigt, die nicht von benutzereingaben abhängig sind.

Die Standardabfrage weist die gleiche Struktur wie jede normale Benutzerabfrage auf, wobei das name Feld auf das folgende Objekt festgelegt und festgelegt initialRun value true ist:

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Codebeispiel

Beispielname Beschreibung .NET Node.js
Teams Messaging-Erweiterungsaktion Beschreibt, wie Aktionsbefehle definiert, Aufgabenmodul erstellt und auf Aufgabenmodul-Sendeaktion reagiert wird. View View
Teams Suche nach Messaging-Erweiterungen Beschreibt, wie Suchbefehle definiert und auf Suchvorgänge reagiert wird. View View

Nächster Schritt

Weitere Informationen

Hinzufügen einer Konfiguration zu einer Messaging-Erweiterung