API-basierte Nachrichtenerweiterung

Nachrichtenerweiterungen, die mit der API (API-basiert) erstellt wurden, verwenden einen Webdienst zum Verwalten von Benutzeranforderungen und -antworten und erfordern keine Botregistrierung. API-basierte Nachrichtenerweiterungen sind eine Microsoft Teams-App-Funktion, die externe APIs direkt in Teams integriert, um die Benutzerfreundlichkeit Ihrer App zu verbessern und eine nahtlose Benutzererfahrung zu bieten. API-basierte Nachrichtenerweiterungen unterstützen Suchbefehle und können zum Abrufen und Anzeigen von Daten aus externen Diensten innerhalb von Teams verwendet werden, um Workflows zu optimieren, indem sie den Wechsel zwischen Anwendungen reduzieren. API-basierte Nachrichtenerweiterungen helfen Ihren Apps, direkt mit Daten, Apps und Diensten von Drittanbietern zu interagieren, wodurch die Funktionen verbessert werden. Die API-basierte Nachrichtenerweiterung ermöglicht Folgendes:

• Rufen Sie Echtzeitinformationen ab, z. B. aktuelle Nachrichten zu einer Produkteinführung.
• Abrufen wissensbasierter Informationen, z. B. der Entwurfsdateien meines Teams in Figma

Weitere Informationen zum Erstellen einer API-basierten Nachrichtenerweiterung mithilfe des Teams Toolkits finden Sie im Video:

Die folgenden Abbildungen zeigen den Fluss von Benutzerabfragen über herkömmliche Nachrichtenerweiterungen und API-Nachrichtenerweiterungen:

Benutzerabfrageflow mit herkömmlichen Nachrichtenerweiterungen. Der Entwickler muss einen benutzerdefinierten Bothandlerdienst verwalten, der die Anforderungen eines Teams-Bots verarbeitet. Der Handlerdienst sendet eine Anforderung an den Entwicklerdienst, wenn eine Abfrage aufgerufen wird.

Benutzerabfrageflow mit API-Nachrichtenerweiterungen. Ein vom Entwickler verwalteter Handlerdienst ist nicht erforderlich, solange die Interaktion in der OpenAPI-Spezifikation im App-Paket klar beschrieben ist.

Hier sehen Sie eine allgemeine Abfolge von Ereignissen, die während eines Abfragebefehlsaufrufs auftreten:

1. Wenn ein Benutzer einen Abfragebefehl aufruft, werden die Parameter des Abfragebefehls vom Teams-Bot Service empfangen.

2. Der Abfragebefehl wird in der App-Manifestdatei definiert. Die Befehlsdefinition enthält einen Verweis auf die operationId in der OpenAPI-Spezifikationsdatei sowie die Details der Parameter, die der Teams-Client für diesen Befehl rendert. Zur Referenz ist die operationId in der OpenAPI-Spezifikationsdatei für einen bestimmten HTTP-Vorgang eindeutig.

3. Der Teams-Bot Service verwendet dann die vom Benutzer angegebenen Parameter zusammen mit der Kopie der OpenAPI-Spezifikation für die zugeordneteoperationId, um eine HTTP-Anforderung für den Endpunkt des Entwicklers zu erstellen.

4. Wenn die Authentifizierung erforderlich ist und im Manifest konfiguriert ist. Es wird in das entsprechende Token oder den entsprechenden Schlüssel aufgelöst. Dieses Token oder dieser Schlüssel wird als Teil der ausgehenden Anforderung verwendet. [Optional]

5. Der Teams-Botdienst führt die HTTP-Anforderung an den Entwicklerdienst aus.

6. Der Entwicklerdienst sollte entsprechend dem in der OpenAPI-Spezifikation beschriebenen Schema reagieren. Dies liegt im JSON-Format vor.

7. Der Teams-Client muss dem Benutzer die Ergebnisse wieder anzeigen. Um die JSON-Ergebnisse aus dem vorherigen Schritt in die Benutzeroberfläche zu konvertieren, verwendet der Teams-Botdienst die Antwort-Rendering-Vorlage, um eine adaptive Karte für jedes Ergebnis zu erstellen.

8. Die adaptiven Karten werden an den Client gesendet, der sie auf der Benutzeroberfläche rendert.

Voraussetzungen

Das App-Definitionspaket enthält verschiedene überzeugende Artefakte, die die Funktionalität dieses Features unterstützen. Bevor Sie beginnen, stellen Sie sicher, dass Sie über grundlegende Kenntnisse der folgenden Dateien verfügen:

OpenAPI Description (OAD)

OpenAPI description documenat ist ein übernommener Industriestandard zum Beschreiben von APIs. Damit können Sie Ihre APIs von ihrer Implementierung abstrahieren und sprachunabhängige Definitionen bereitstellen, die sowohl für Menschen lesbar als auch maschinenlesbar sind. Das OpenAPI description documenat beschreibt die Interaktionen, die Ihre Erweiterung unterstützt, sodass Teams Anforderungen erstellen und direkt mit Ihrem Dienst kommunizieren kann, ohne dass ein Verarbeitungsdienst der mittleren Ebene erforderlich ist.

Ein OpenAPI-Beschreibungsdokument enthält Details zur Kommunikation mit dem Entwicklerdienst. Stellen Sie sicher, dass Sie die folgenden Richtlinien für das OAD-Dokument (OpenAPI Description) einhalten:

• Die OpenAPI-Versionen 2.0 und 3.0.x werden unterstützt.
• JSON und YAML sind die unterstützten Formate.
• Falls vorhanden, muss der Anforderungstext application/JSON sein.
• Definieren Sie eine HTTPS-Protokollserver-URL für die servers.url -Eigenschaft.
• Nur DIE HTTP-Methoden POST und GET werden unterstützt.
• Das OpenAPI-Beschreibungsdokument muss über einen verfügen operationId.
• Nur ein erforderlicher Parameter ohne Standardwert ist zulässig.
• Ein erforderlicher Parameter mit einem Standardwert wird als optional betrachtet.
• Benutzer dürfen keinen Parameter für eine Kopfzeile oder ein Cookie eingeben.
• Der Vorgang darf keine erforderlichen Header- oder Cookieparameter ohne Standardwerte aufweisen.
• Stellen Sie sicher, dass im Dokument OpenAPI Description keine Remoteverweise vorhanden sind.
• Das Erstellen von Arrays für die Anforderung wird nicht unterstützt. Geschachtelte Objekte in einem JSON-Anforderungstext werden jedoch unterstützt.
• Teams unterstützt oneOfdie Konstrukte , anyOf, allOf, und not (swagger.io) nicht.

Der folgende Code ist ein Beispiel für ein OpenAPI-Beschreibungsdokument:

openapi: 3.0.1
info:
title: OpenTools Plugin
description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
version: 'v1'
servers:
- url: https://gptplugin.opentools.ai
paths:
/tools:
 get:
   operationId: searchTools
   summary: Search for AI Tools
   parameters:
     - in: query
       name: search
       required: true
       schema:
         type: string
       description: Used to search for AI tools by their category based on the keywords. For example, ?search="tool to create music" will give tools that can create music.
   responses:
     "200":
       description: OK
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/searchToolsResponse'
     "400":
       description: Search Error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/searchToolsError'
components:
schemas:
 searchToolsResponse:
   required:
     - search
   type: object
   properties:
     tools:
       type: array
       items:
         type: object
         properties:
           name:
             type: string
             description: The name of the tool.
           opentools_url:
             type: string
             description: The URL to access the tool.
           main_summary:
             type: string
             description: A summary of what the tool is.
           pricing_summary:
             type: string
             description: A summary of the pricing of the tool.
           categories:
             type: array
             items:
               type: string
             description: The categories assigned to the tool.
           platforms:
             type: array
             items:
               type: string
             description: The platforms that this tool is available on.
       description: The list of AI tools.
 searchToolsError:
   type: object
   properties:
     message:
       type: string
       description: Message of the error.

Weitere Informationen zum Schreiben von OpenAPI-Definitionen in YAML finden Sie unter OpenAPI-Struktur.

App-Manifest

Das App-Manifest ist eine Blaupause für Ihre Teams-App, die definiert, wie und wo die Nachrichtenerweiterung im Teams-Client aufgerufen wird. Sie enthält die Befehle, die Ihre Erweiterung unterstützt, und die Speicherorte, von denen aus darauf zugegriffen werden kann, z. B. der Nachrichtenbereich zum Verfassen, die Befehlsleiste und die Nachricht. Das Manifest ist mit der OpenAPI-Spezifikation und der Antwortrenderingvorlage verknüpft, um die ordnungsgemäße Funktionalität sicherzustellen.

Das App-Manifest enthält die Abfragebefehlsdefinition. Stellen Sie sicher, dass Sie die folgenden Richtlinien für das App-Manifest einhalten:

• Legen Sie die App-Manifestversion auf fest 1.17.
• Legen Sie auf fest composeExtensions.composeExtensionTypeapiBased.
• Definieren Sie composeExtensions.apiSpecificationFile als relativen Pfad zum OpenAPI-Beschreibungsdokument innerhalb des Ordners. Dadurch wird das App-Manifest mit der API-Spezifikation verknüpft.
• Definieren Sie apiResponseRenderingTemplateFile als relativen Pfad zur Antwortrenderingvorlage. Dies gibt den Speicherort der Vorlage an, die zum Rendern von API-Antworten verwendet wird.
• Jeder Befehl muss über einen Link zur Antwortrenderingvorlage verfügen. Dadurch wird jeder Befehl mit dem entsprechenden Antwortformat verbunden.
• Die Commands.id -Eigenschaft im App-Manifest muss mit dem operationId im Dokument OpenAPI Description übereinstimmen.
• Wenn ein erforderlicher Parameter ohne Standardwert ist, muss der Befehl parameters.name im App-Manifest mit dem parameters.name im OpenAPI-Beschreibungsdokument übereinstimmen.
• Wenn kein erforderlicher Parameter vorhanden ist, muss der Befehl parameters.name im App-Manifest mit dem optionalen parameters.name im OpenAPI-Beschreibungsdokument übereinstimmen.
• Stellen Sie sicher, dass der Name der Parameter für jeden Befehl im App-Manifest genau mit dem entsprechenden Namen des Parameters übereinstimmt, der im OpenAPI-Beschreibungsdokument für den Vorgang definiert ist.
• Eine Antwortrenderingvorlage muss pro Befehl definiert werden, der zum Konvertieren von Antworten von einer API verwendet wird.
• Die Befehls- und Parameterbeschreibungen dürfen 128 Zeichen nicht überschreiten.

Im Folgenden sehen Sie ein Beispiel für ein App-Manifest mit Definitionen für API-basierte Nachrichtenerweiterungen:

 {
 "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
 +  "manifestVersion": "devPreview",
 "version": "1.0.0",
 "id": "04805b4b-xxxx-xxxx-xxxx-4dbc1cac8f89",
 "packageName": "com.microsoft.teams.extension",
 "developer": {
    "name": "Teams App, Inc.",
    "websiteUrl": "https://www.example.com",
    "privacyUrl": "https://www.example.com/termofuse",
    "termsOfUseUrl": "https://www.example.com/privacy"
 },
 "icons": {
    "color": "color.png",
    "outline": "outline.png"
 },
 "name": {
    "short": "AI tools",
    "full": "AI tools"
 },
 "description": {
    "short": "AI tools",
    "full": "AI tools"
 },
 "accentColor": "#FFFFFF",
 "composeExtensions": [
    {
 +      "composeExtensionType": "apiBased",
 +      "authorization": {
 +        "authType": "apiSecretServiceAuth ",
 +        "apiSecretServiceAuthConfiguration": {
 +            "apiSecretRegistrationId": "96270b0f-7298-40cc-b333-152f84321813"
 +        }
 +      },
 +      "apiSpecificationFile": "aitools-openapi.yml",
       "commands": [
       {
          "id": "searchTools",
          "type": "query",
          "context": [
             "compose",
             "commandBox"
          ],
          "title": "search for AI tools",
          "description": "search for AI tools",
          "parameters": [
             {
             "name": "search",
             "title": "search query",
             "description": "e.g. search='tool to create music'"
             }
          ],
 +          "apiResponseRenderingTemplateFile": "response-template.json"
       }
       ]
    }
 ],
 "validDomains": []
 }

Parameter

Weitere Informationen finden Sie unter composeExtensions.

Antwortrenderingvorlage

Die Antwortrenderingvorlage ist ein vordefiniertes Format, das vorschreibt, wie die Ergebnisse Ihrer API in Teams angezeigt werden. Es verwendet Vorlagen, um adaptive Karten oder andere Benutzeroberflächenelemente aus der Api-Antwort zu erstellen, um eine nahtlose und integrierte Benutzererfahrung in Teams zu gewährleisten. Die Vorlage definiert das Layout und den Stil der präsentierten Informationen, die Text, Bilder und interaktive Komponenten enthalten können. Stellen Sie sicher, dass Sie die folgenden Richtlinien für die Antwortrenderingvorlage einhalten:

• Definieren Sie die Schemaverweis-URL in der $schema -Eigenschaft, um die Struktur Ihrer Vorlage für das Schema der Antwortrenderingvorlage festzulegen.
• Die unterstützten Werte für responseLayout sind list und grid, die bestimmen, wie die Antwort visuell dargestellt wird. Weitere Informationen zum Layout finden Sie unter Reagieren auf Benutzeranforderungen.
• Ein jsonPath wird für Arrays oder erforderlich, wenn die Daten für die adaptive Karte nicht das Stammobjekt sind. Wenn Ihre Daten beispielsweise unter productDetailsgeschachtelt sind, lautet productDetailsIhr JSON-Pfad .
• Definieren Sie jsonPath als Pfad zu den relevanten Daten oder Arrays in der API-Antwort. Wenn der Pfad auf ein Array zeigt, wird jeder Eintrag im Array an die Vorlage adaptive Karte gebunden und als separates Ergebnis zurückgegeben. [Optional]
• Rufen Sie eine Beispielantwort zum Überprüfen der Antwortrenderingvorlage ab. Dies dient als Test, um sicherzustellen, dass Ihre Vorlage wie erwartet funktioniert.
• Verwenden Sie Tools wie Fiddler oder Postman, um die API aufzurufen und sicherzustellen, dass die Anforderung und die Antwort gültig sind. Dieser Schritt ist entscheidend für die Problembehandlung und die Bestätigung, dass Ihre API ordnungsgemäß funktioniert.
• Sie können die adaptive Karte Designer verwenden, um die API-Antwort an die Antwortrenderingvorlage zu binden und eine Vorschau der adaptiven Karte anzuzeigen. Fügen Sie die Vorlage adaptive Karte in den KARTENNUTZLAST-EDITOR ein, und fügen Sie den Beispielantworteintrag im SAMPLE DATA EDITOR ein.

Der folgende Code ist ein Beispiel für eine Antwortrenderingvorlage:

{
"version": "1.0",
"$schema": "developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
"jsonPath": "repairs",
"responseLayout": "grid",
"responseCardTemplate": {
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Title: ${if(title, title, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Description: ${if(description, description, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
                  "wrap": true
                },
                {
                  "type": "Image",
                  "url": "${image}",
                  "size": "Medium",
                  "$when": "${image != null}"
                }
              ]
            },
            {
              "type": "Column",
              "width": "auto",
              "items": [
                {
                  "type": "Image",
                  "url": "${if(image, image, '')}",
                  "size": "Medium"
                }
              ]
            }
          ]
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Repair ID:",
              "value": "${if(id, id, 'N/A')}"
            },
            {
              "title": "Date:",
              "value": "${if(date, date, 'N/A')}"
            }
          ]
        }
      ]
    }
  ]
  },
  "previewCardTemplate": {
  "title": "Title: ${if(title, title, 'N/A')}",
  "subtitle": "Description: ${if(description, description, 'N/A')}",
  "text": "Assigned To: ${if(assignedTo, assignedTo, 'N/A')}",
  "image": {
    "url": "${image}",
    "$when": "${image != null}"
    }
  }
 }

Vorschaukarte

Eine Vorschau Karte Vorlage im Schema der Antwortrenderingvorlage wird verwendet, um JSON-Antworten einer Vorschauversion Karte zuzuordnen, die Benutzern angezeigt werden, wenn sie ein Suchergebnis auswählen. Die Vorschauversion Karte wird dann im Feld zum Verfassen von Nachrichten zu einer adaptiven Karte erweitert. Die Vorschauversion Karte Vorlage ist Teil der Antwortrenderingvorlage, die auch eine Vorlage für adaptive Karten und Metadaten enthält.

Erweiterte adaptive Karte

Parameter

JSON-Pfad

Der JSON-Pfad ist optional, sollte aber für Arrays verwendet werden, oder wenn das Objekt, das als Daten für die adaptive Karte verwendet werden soll, nicht das Stammobjekt ist. Der JSON-Pfad sollte dem von Newtonsoft definierten Format folgen. Dieses Tool kann verwendet werden. Sie können das JSON-Tool verwenden, um zu überprüfen, ob ein JSON-Pfad korrekt ist. Wenn der JSON-Pfad auf ein Array verweist, wird jeder Eintrag in diesem Array an die Vorlage adaptive Karte gebunden und als separate Ergebnisse zurückgegeben.

Beispiel Angenommen, Sie verfügen über den folgenden JSON-Code für eine Liste von Produkten und möchten für jeden Eintrag ein Karte Ergebnis erstellen.

{
   "version": "1.0",
   "title": "All Products",
   "warehouse": {
      "products": [
        ...
      ]
   }
}

Wie Sie sehen können, befindet sich das Ergebnisarray unter "products", das unter "warehouse" geschachtelt ist, sodass der JSON-Pfad "warehouse.products" lautet.

Verwenden Sie , um eine Vorschau der adaptiven Karte anzuzeigen, indem Sie die Vorlage in die Kartennutzlast Editor einfügen. Nehmen Sie https://adaptivecards.io/designer/ einen Beispielantworteintrag aus Ihrem Array oder für Ihr Objekt, und fügen Sie ihn rechts in den Editor für gleiche Daten ein. Stellen Sie sicher, dass die Karte ordnungsgemäß gerendert wird und Ihren Wünschen entspricht. Teams unterstützt Karten bis Version 1.5, während der Designer 1.6 unterstützt.

OpenAPI-Schemakonvertierung

Die folgenden Datentypen im OpenAPI-Beschreibungsdokument werden wie folgt in Elemente innerhalb einer adaptiven Karte konvertiert:

• stringDie Typen , number, und integerboolean werden in textBlock konvertiert.

  Beispiel

  • Quellschema: string, number, integerund boolean

     name:
       type: string
       example: doggie
    

  • Zielschema: Textblock

    {
    "type": "TextBlock",
    "text": "name: ${if(name, name, 'N/A')}",
    "wrap": true
    }
    

• array: Ein Array wird in einen Container innerhalb der adaptiven Karte konvertiert.

  Beispiel

  • Quellschema: array

        type: array
                  items:
                  required:
                    - name
                  type: object
                    properties:
                    id:
                      type: integer
                    category:
                      type: object
                      properties:
                      name:
                        type: string
    

  • Zielschema: Container

        {
                  "type": "Container",
                  "$data": "${$root}",
                  "items": [
                    {
                      "type": "TextBlock",
                      "text": "id: ${if(id, id, 'N/A')}",
                      "wrap": true
                    },
                    {
                      "type": "TextBlock",
                      "text": "category.name: ${if(category.name, category.name, 'N/A')}",
                      "wrap": true
                    }
                  ]
                }
    
    

• object: Ein Objekt wird in adaptive Karte in eine geschachtelte Eigenschaft konvertiert.

  Beispiel

  • Quellschema: object

    components:
      schemas:
        Pet:
            category:
              type: object
            properties:
              id:
                type: integer
              name:
                type: string
    
    

  • Zielschema: Geschachtelte Eigenschaft in einer adaptiven Karte

    {
      "type": "TextBlock",
      "text": "category.id: ${if(category.id, category.id, 'N/A')}",
      "wrap": true
    },
    {
      "type": "TextBlock",
      "text": "category.name: ${if(category.name, category.name, 'N/A')}",
      "wrap": true
    }
    
    

• image: Wenn eine Eigenschaft eine Bild-URL ist, wird sie in ein Image-Element auf der adaptiven Karte konvertiert.

  Beispiel

  • Quellschema: image

        image:
          type: string
          format: uri
          description: The URL of the image of the item to be repaired
    
    

  • Zielschema: "Image"

    {
          "type": "Image",
          "url": "${image}",
          "$when": "${image != null}"
        }
    
    

Nächster Schritt