Teilen über

Reagieren Sie auf den Suchbefehl

  • Artikel

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt Nachrichtenerweiterungen – 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. Der Aufruf wird mit den folgenden Bedingungen ausgelöst:

  • Wenn Zeichen in das Suchfeld eingegeben werden.
  • initialRun ist in Ihrem App-Manifest auf TRUE festgelegt, und Sie erhalten 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 mit einem der im App-Manifest deklarierten Befehle übereinstimmt.
parameters Array von Parametern. Jedes Parameterobjekt enthält den Parameternamen zusammen mit dem 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.
}

Reagieren auf Benutzeranforderungen

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

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

Eigenschaftenname Zweck
composeExtension Antwortumschlag der obersten Ebene.
composeExtension.type Typ der Antwort. 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 Nachrichtenerweiterung einzurichten.
message: Zeigt eine Nur-Text-Nachricht an
composeExtension.attachmentLayout Gibt das Layout der Anlagen an. Wird für Antworten vom Typ resultverwendet.
Die folgenden Typen werden 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 resultverwendet.
Die folgenden Typen werden 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 configverwendet.
composeExtension.text Anzuzeigende Meldung. Wird für Antworten vom Typ messageverwendet.

Konfigurationsantwort

Konfigurationsantwort sind die Daten, die vom Server oder der Anwendung zum Konfigurieren und Aktivieren der Nachrichtenerweiterung innerhalb der Messagingplattform zurückgegeben werden. Der folgende Code ist ein Beispiel für die Konfiguration der Nachrichtenerweiterung:

{
    "name": "composeExtension/submitAction",
    "type": "invoke",
    "timestamp": "2024-03-08T14:10:47.575Z",
    "localTimestamp": "2024-03-08T19:40:47.575+05:30",
    "id": "f:7dfe18de-94e3-9f38-5d44-adeb31cd8243",
    "channelId": "msteams",
    "serviceUrl": "https://smba.trafficmanager.net/amer/",
    "from": {
        "id": "29:1PBlnIsEROUYzpFjULDVodMHrnpujmfhBdQAf0pcO1EkaDkhI0_Pj_ql-jZUYOGdSc3_KcqaIIjzbleraVJ2Z3g",
        "name": "MOD Administrator",
        "aadObjectId": "ce9def33-d7fc-444c-8728-be1f95e6b6f2"
    },
    "conversation": {
        "isGroup": true,
        "conversationType": "groupChat",
        "tenantId": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b",
        "id": "19:1dd50ba7-e5bd-46ea-b34e-80a415148de7_ce9def33-d7fc-444c-8728-be1f95e6b6f2@unq.gbl.spaces"
    },
    "recipient": {
        "id": "28:9a2b01fc-88c1-40e1-bf87-5079c8e35626",
        "name": "PSDAzureBot"
    },
    "entities": [
        {
            "locale": "en-GB",
            "country": "GB",
            "platform": "Web",
            "timezone": "Asia/Calcutta",
            "type": "clientInfo"
        }
    ],
    "channelData": {
        "tenant": {
            "id": "4ad59956-0f88-4b88-a9d0-570b6eb4e66b"
        },
        "source": {
            "name": "compose"
        }
    },
    "value": {
        "commandId": "razorView",
        "commandContext": "compose",
        "data": {
            "Title": "Welcome to RazorView!",
            "DisplayData": " Today&#x27;s date is 8-3-2024, Friday"
        },
        "context": {
            "theme": "default"
        }
    },
    "locale": "en-GB",
    "localTimezone": "Asia/Calcutta"
}

Die folgende Antwort ist die Konfigurationsantwort, die angezeigt wird, wenn der Benutzer mit der Compose-Erweiterung interagiert:

{
    "composeExtension": {
        "type": "config",
        "suggestedActions": {
            "actions": [
                {
                    "type": "openUrl",
                    "value": "https://7a03-2405-201-a00c-7191-b472-ff64-112d-f806.ngrok-free.app"
                }
            ]
        }
    }
}

Der Screenshot zeigt die Konfigurationsantwort für die Nachrichtenerweiterung.

Antwortkartentypen und Vorschauen

Hinweis

Die Suchergebnisse der Nachrichtenerweiterung unterstützen kein Auffüllen.

Teams unterstützt die folgenden Kartentypen:

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

Informationen zum Verwenden der Miniaturansichts- und Herokartentypen finden Sie unter Hinzufügen von Karten und Kartenaktionen.

Weitere Informationen zur Connectorkarte für Microsoft 365-Gruppen finden Sie unter Verwenden von Connectorkarten für Microsoft 365-Gruppen.

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

  • Verwenden der preview -Eigenschaft im attachment -Objekt. Die preview Anlage kann nur eine Hero- oder Miniaturansichtskarte sein.
  • Extrahieren aus den grundlegenden titleEigenschaften , textund image des attachment -Objekts. Die grundlegenden Eigenschaften werden nur verwendet, wenn die preview Eigenschaft nicht angegeben ist.

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

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

Für Hero- und Miniaturansichtskarten müssen Sie keine Vorschaueigenschaft angeben, es wird standardmäßig eine Vorschau generiert.

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

Standardabfrage

Wenn Sie im Manifest auf true festlegeninitialRun, gibt Microsoft Teams eine Standardabfrage aus, wenn der Benutzer die Nachrichtenerweiterung zum ersten Mal öffnet. Ihr Dienst kann auf diese Abfrage mit einer Reihe vorab aufgefüllter Ergebnisse antworten. Dies ist nützlich, wenn Ihr Suchbefehl eine Authentifizierung oder Konfiguration erfordert, die zuletzt angezeigten Elemente, Favoriten oder andere Informationen anzeigt, die nicht von der Benutzereingabe abhängig sind.

Die Standardabfrage hat dieselbe Struktur wie jede reguläre Benutzerabfrage, wobei das name Feld auf initialRun und value auf true festgelegt ist, wie im folgenden Objekt gezeigt:

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

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Teams Nachrichtenerweiterungen – Suche In diesem Beispiel wird gezeigt, wie Sie eine suchbasierte Nachrichtenerweiterung erstellen. Es durchsucht Nudget-Pakete und zeigt die Ergebnisse in der suchbasierten Messagingerweiterung an. View View View
Authentifizierung und Konfiguration der Teams-Nachrichtenerweiterung Dieses Beispiel zeigt eine Nachrichtenerweiterung, die über eine Konfigurationsseite verfügt, Suchanforderungen akzeptiert und Ergebnisse zurückgibt, nachdem sich der Benutzer angemeldet hat. Es zeigt auch, dass keine App-Installationslinks entfurling zusammen mit normalem Link-Entfurling View View View

Nächster Schritt

Hinzufügen der Authentifizierung von Drittanbietern zur Nachrichtenerweiterung

Siehe auch