Antworten auf den SuchbefehlRespond to the search command

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf 4,6 und höheren Versionen des bot Framework SDK.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Wenn Sie nach einer Dokumentation für frühere Versionen suchen, lesen Sie den Abschnitt Messaging Extensions-V3 SDK im Ordner Resources der Dokumentation.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Der Webdienst erhält eine composeExtension/query Invoke-Nachricht, die ein value Objekt mit den Suchparametern enthält.Your web service will receive a composeExtension/query invoke message that contains a value object with the search parameters. Dieser Aufruf wird ausgelöst:This invoke is triggered:

  • Als Zeichen werden in das Suchfeld eingegeben.As characters are entered into the search box.
  • Wenn initialRun im App-Manifest auf true festgelegt ist, erhalten Sie die Invoke-Meldung, sobald der Suchbefehl aufgerufen wird.If initialRun is set to true in your app manifest, you'll receive the invoke message as soon as the search command is invoked. Siehe Standardabfrage.See default query.

Die Anforderungsparameter selbst werden im- value Objekt in der Anforderung gefunden, die die folgenden Eigenschaften enthält:The request parameters itself are found in the value object in the request, which includes the following properties:

EigenschaftennameProperty name ZweckPurpose
commandId Der Name des vom Benutzer aufgerufenen Befehls, der einem der im App-Manifest deklarierten Befehle entspricht.The name of the command invoked by the user, matching one of the commands declared in the app manifest.
parameters Array von Parametern.Array of parameters. Jedes Parameter-Objekt enthält den Namen des Parameters sowie den vom Benutzer bereitgestellten Parameterwert.Each parameter object contains the parameter name, along with the parameter value provided by the user.
queryOptions Paginierung Parameter:Pagination parameters:
skip: Skip count für diese Abfrageskip: skip count for this query
count: Anzahl der zurückzugebenden Elementecount: number of elements to return
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  //code to handle the query
}

Reagieren auf BenutzeranforderungenRespond to user requests

Wenn der Benutzer eine Abfrage ausführt, gibt Microsoft Teams eine synchrone http-Anforderung an Ihren Dienst aus.When the user performs a query, Microsoft Teams issues a synchronous HTTP request to your service. An diesem Zeitpunkt hat der Code 5 Sekunden, um eine HTTP-Antwort auf die Anforderung bereitzustellen.At that point, your code has 5 seconds to provide an HTTP response to the request. Während dieser Zeit kann der Dienst zusätzliche Suchvorgänge durchführen oder eine andere Geschäftslogik, die für die Zustellung der Anforderung benötigt wird.During this time, your service can perform additional lookup, or any other business logic needed to serve the request.

Ihr Dienst sollte mit den Ergebnissen Antworten, die mit der Benutzerabfrage übereinstimmen.Your service should respond with the results matching the user query. Die Antwort muss einen HTTP-Statuscode 200 OK und ein gültiges Application/JSON-Objekt mit folgendem Text angeben:The response must indicate an HTTP status code of 200 OK and a valid application/json object with the following body:

EigenschaftennameProperty name ZweckPurpose
composeExtension Antwortumschlag auf oberster Ebene.Top-level response envelope.
composeExtension.type Typ der Antwort.Type of response. Die folgenden Typen werden unterstützt:The following types are supported:
result: zeigt eine Liste der Suchergebnisse an.result: displays a list of search results
auth: der Benutzer wird aufgefordert, sich zu authentifizieren.auth: asks the user to authenticate
config: der Benutzer wird aufgefordert, die Messaging Erweiterung einzurichten.config: asks the user to set up the messaging extension
message: zeigt eine nur-Text-Nachricht an.message: displays a plain text message
composeExtension.attachmentLayout Gibt das Layout der Anlagen an.Specifies the layout of the attachments. Wird für Antworten vom Typ resultverwendet.Used for responses of type result.
Derzeit werden die folgenden Typen unterstützt:Currently the following types are supported:
list: eine Liste von Kartenobjekten, die Miniaturansichten, Titel und Textfelder enthaltenlist: a list of card objects containing thumbnail, title, and text fields
grid: ein Raster von Miniaturbilderngrid: a grid of thumbnail images
composeExtension.attachments Array gültiger Attachment-Objekte.Array of valid attachment objects. Wird für Antworten vom Typ resultverwendet.Used for responses of type result.
Derzeit werden die folgenden Typen unterstützt:Currently the following types are supported:
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.Suggested actions. Wird für Antworten vom Typ auth oder configverwendet.Used for responses of type auth or config.
composeExtension.text Anzuzeigende Meldung.Message to display. Wird für Antworten vom Typ messageverwendet.Used for responses of type message.

Antwortkarten Typen und-VorschauenResponse card types and previews

Wir unterstützen die folgenden Anlagentypen:We support the following attachment types:

Eine Übersicht finden Sie unter Was sind Karten .See What are cards for an overview.

Weitere Informationen zur Verwendung der Miniaturansicht-und Hero-Kartentypen finden Sie unter Add Cards and Card Actions.To learn how to use the thumbnail and hero card types, see Add cards and card actions.

Weitere Informationen zur Office 365-Verbindungskarte finden Sie unter using Office 365 Connector Cards.For additional documentation regarding the Office 365 Connector card, see Using Office 365 Connector cards.

Die Ergebnisliste wird auf der Microsoft Teams-Benutzeroberfläche mit einer Vorschau der einzelnen Elemente angezeigt.The result list is displayed in the Microsoft Teams UI with a preview of each item. Die Vorschau wird auf eine von zwei Arten generiert:The preview is generated in one of two ways:

  • Verwenden der preview -Eigenschaft innerhalb attachment des-Objekts.Using the preview property within the attachment object. Die preview Anlage kann nur eine Hero-oder Thumbnail-Karte sein.The preview attachment can only be a Hero or Thumbnail card.
  • Extrahiert aus den Eigenschaften titleBasic text, und image und der Anlage.Extracted from the basic title, text, and image properties of the attachment. Diese werden nur verwendet, wenn preview die Eigenschaft nicht festgelegt ist und diese Eigenschaften verfügbar sind.These are used only if the preview property is not set and these properties are available.

Sie können eine Vorschau einer adaptiven Karte oder Office 365-connectorkarte in der Ergebnisliste einfach über die Vorschau-Eigenschaft anzeigen.You can display a preview of an Adaptive Card or Office 365 Connector card in the result list simply by its preview property. Dies ist nicht erforderlich, wenn die Ergebnisse bereits Hero-oder Thumbnail-Karten sind.This is not necessary if the results are already hero or thumbnail cards. Wenn Sie die Vorschau Anlage verwenden, muss es sich entweder um eine Hero-oder eine Miniatur Ansichtskarte handeln.If you use the preview attachment, it must be either a Hero or Thumbnail card. Wenn keine Preview-Eigenschaft angegeben wird, schlägt die Vorschau der Karte fehl, und es wird nichts angezeigt.If no preview property is specified, the preview of the card will fail and nothing will be displayed.

AnforderungsbeispielResponse example

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
      }
  };
}

StandardabfrageDefault query

Wenn Sie im initialRun Manifest true auf festlegen, gibt Microsoft Teams eine "Standard"-Abfrage aus, wenn der Benutzer die Messaging Erweiterung zum ersten Mal öffnet.If you set initialRun to true in the manifest, Microsoft Teams issues a "default" query when the user first opens the messaging extension. Ihr Dienst kann auf diese Abfrage mit einer Reihe vorab aufgefüllter Ergebnisse Antworten.Your service can respond to this query with a set of pre-populated results. Dies kann hilfreich sein, wenn Ihr Suchbefehl Authentifizierung oder Konfiguration erfordert, wobei zuletzt angezeigte Elemente, Favoriten oder andere Informationen angezeigt werden, die nicht von der Benutzereingabe abhängig sind.This can be useful when your search command requires authentication or configuration, displaying recently viewed items, favorites, or any other information that is not dependent on user input.

Die Standard name Abfrage hat dieselbe Struktur wie jede reguläre Benutzerabfrage, wobei das Feld auf initialRun festgelegt und value auf true wie in dem unten stehenden Objekt festgelegt ist.The default query has the same structure as any regular user query, with the name field set to initialRun and value set to true as in the object below.

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

Nächste SchritteNext Steps

Hinzufügen von Authentifizierung und/oder KonfigurationAdd authentication and/or configuration

Bereitstellen der KonfigurationDeploy configuration

Weitere InformationenLearn more

Testen Sie es in einem Schnellstart:Try it out in a quickstart: