API-Based Nachrichtenerweiterung für Einsteiger

Nachrichtenerweiterungen, die mit einer API (API-basiert) erstellt wurden, verbessern die Funktionalität Ihrer Teams-Apps erheblich, indem sie ihnen die Interaktion mit externen Diensten ermöglichen. Dies trägt dazu bei, Workflows zu optimieren, indem die Notwendigkeit reduziert wird, zwischen verschiedenen Anwendungen zu wechseln.

Sie können die API-Nachrichtenerweiterung verwenden, um externe Dienste zu integrieren, die häufig im Geschäftsworkflow verwendet werden. Beispielsweise könnte ein Unternehmen, das häufig ein CRM-System für die Kundenverwaltung verwendet, eine Messagingerweiterung verwenden, um Kundendaten direkt aus Teams abzurufen und anzuzeigen. Durch die Reduzierung der Notwendigkeit, zwischen verschiedenen Anwendungen zu wechseln, spart der Benutzer Zeit und verbessert sich. DIE API-basierte Nachrichtenerweiterung wird auf Teams-Desktop-, Web- und mobilen Clients unterstützt.

Voraussetzungen

• 4 Minuten verbleibend

Hier finden Sie eine Liste der Tools, die Sie zum Erstellen und Bereitstellen Ihrer Apps benötigen.

Vorbereiten der Entwicklungsumgebung

Nachdem Sie die erforderlichen Tools installiert haben, richten Sie die Entwicklungsumgebung ein.

Installieren des Teams-Toolkits

Das Teams Toolkit vereinfacht den Entwicklungsprozess mit Tools zum Bereitstellen und Bereitstellen von Cloudressourcen für Ihre App, veröffentlichen sie im Teams Store und vieles mehr.

Sie können das Toolkit mit Visual Studio Code oder der CLI (Befehlszeilenschnittstelle) Teamsappverwenden.

npm install -g @microsoft/teamsapp-cli

sudo npm install -g --unsafe-perm @microsoft/teamsapp-cli

Einrichten Ihres Teams-Entwicklungsmandanten

Ein Mandant ist wie ein Raum oder ein Container für Ihre organization in Teams, in dem Sie chatten, Dateien freigeben und Besprechungen ausführen. Dieser Bereich ist auch der Ort, an dem Sie Ihre benutzerdefinierte App hochladen und testen. Lassen Sie uns überprüfen, ob Sie bereit sind, mit dem Mandanten zu entwickeln.

Überprüfen auf benutzerdefinierte App-Uploadoption

Nachdem Sie die App erstellt haben, müssen Sie ihre App in Teams laden, ohne sie zu verteilen. Dieser Vorgang wird als benutzerdefinierter App-Upload bezeichnet. Melden Sie sich bei Ihrem Microsoft 365-Konto an, um diese Option anzuzeigen.

Verfügen Sie bereits über einen Mandanten und über Administratorzugriff? Lassen Sie uns überprüfen, ob Sie dies wirklich tun!

Überprüfen Sie, ob Sie eine benutzerdefinierte App in Teams hochladen können:

1. Wählen Sie im Teams-Client das Symbol Apps aus.

2. Wählen Sie Verwalten Ihrer Apps aus.

3. Wählen Sie App hochladen aus.

4. Suchen Sie nach der Option Hochladen einer benutzerdefinierten App. Wenn die Option angezeigt wird, ist der benutzerdefinierte App-Upload aktiviert.

   

   Hinweis

   Wenden Sie sich an Ihren Teams-Administrator, wenn Sie die Option zum Hochladen einer benutzerdefinierten App nicht finden.

Erstellen eines kostenlosen Teams-Entwicklermandanten (optional)

Wenn Sie nicht über ein Teams-Entwicklerkonto verfügen, können Sie es kostenlos erhalten. Nehmen Sie am Microsoft 365-Entwicklerprogramm teil!

1. Gehen Sie zu Microsoft 365-Entwicklerprogramm.

2. Wählen Sie Jetzt beitreten aus, und folgen Sie den Anweisungen auf dem Bildschirm.

3. Wählen Sie auf der Willkommensseite E5-Abonnement einrichten aus.

4. Einrichten Ihres Administratorkontos. Nachdem Sie fertig sind, wird der folgende Bildschirm angezeigt.

   

5. Melden Sie sich bei Teams mit dem Administratorkonto an, das Sie gerade eingerichtet haben. Vergewissern Sie sich, dass Sie über die Option Benutzerdefinierte App hochladen in Teams verfügen.

Abrufen eines kostenlosen Azure-Kontos

Wenn Sie Ihre App hosten oder auf Ressourcen in Azure zugreifen möchten, benötigen Sie ein Azure-Abonnement. Erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Jetzt verfügen Sie über alle Tools zum Einrichten Ihres Kontos. Richten Sie als Nächstes Ihre Entwicklungsumgebung ein, und beginnen Sie mit dem Erstellen! Wählen Sie zuerst die App aus, die Sie erstellen möchten.

Erstellen einer API-basierten Nachrichtenerweiterung

• 3 Minuten verbleibend

Nachdem Sie Ihren Projektarbeitsbereich mit Teams Toolkit eingerichtet haben, erstellen Sie Ihr Botprojekt. Stellen Sie sicher, dass Sie bei Ihrem Microsoft 365-Konto angemeldet sind.

Anmelden bei Ihrem Microsoft 365-Konto

Verwenden Sie dieses Konto, um sich bei Teams anzumelden. Wenn Sie einen Microsoft 365-Entwicklerprogrammmandanten verwenden, ist das Administratorkonto, das Sie bei der Registrierung eingerichtet haben, Ihr Microsoft 365-Konto.

Erstellen eines OpenAPI-Beschreibungsdokuments

OpenAPI Description (OAD) ist die Branchenstandardspezifikation, die beschreibt, wie OpenAPI-Dateien strukturiert und umrissen werden. Es handelt sich um ein sprachunabhängiges, für Menschen lesbares Format zum Beschreiben von APIs. Es ist sowohl für Menschen als auch für Computer einfach zu lesen und zu schreiben. Das Schema ist maschinenlesbar und wird entweder in YAML oder JSON dargestellt.

Sie müssen über ein OAD-Dokument (OpenAPI Description) verfügen, bevor Sie eine API-basierte Nachrichtenerweiterung erstellen können. Die API-Spezifikation muss die folgenden Kriterien erfüllen:

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

Wir haben die folgende OpenAPI-Beschreibung als Beispiel für dieses Tutorial verwendet:

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" gives 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.

Nachdem Sie nun ihr OpenAPI-Beschreibungsdokument haben, ist auch eine Antwortrenderingvorlage für die App erforderlich, um auf die GET- oder POST-Anforderungen zu reagieren. Die Antwortrenderingvorlage besteht aus einer Vorlage für adaptive Karten, einer Vorschauvorlage Karte und Metadaten. Wenn Sie eine App mithilfe des Teams Toolkits oder des Entwicklerportals für Teams erstellen, wird die Antwortrenderingvorlage automatisch aus dem OpenAPI-Beschreibungsdokument extrahiert.

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

   {
   "version": "1.0.0",
   "jsonPath": "tools",
   "responseLayout": "list",
   "responseCardTemplate": {
       "type": "AdaptiveCard",
       "version": "1.4",
       "body": [
       {
           "type": "TextBlock",
           "text": "${if(name, name, 'N/A')}",
           "size": "Large",
           "weight": "Bolder",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Categories: ${join(categories, ', ')}",
           "size": "Small",
           "isSubtle": true,
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "${if(main_summary, main_summary, 'N/A')}",
           "size": "Medium",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Supported Platforms: ${join(platforms, ', ')}",
           "size": "Small",
           "isSubtle": true,
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Pricing Summary:",
           "size": "Medium",
           "weight": "Bolder",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "${if(pricing_summary, pricing_summary, 'N/A')}",
           "size": "Small",
           "wrap": true
       }
       ],
       "actions": [
       {
           "type": "Action.OpenUrl",
           "title": "Learn More",
           "url": "${opentools_url}",
           "$when": "${opentools_url != null}"
       },
       {
           "type": "Action.OpenUrl",
           "title": "Chat with Chatbot",
           "url": "${chatbot_short_url}",
           "$when": "${chatbot_short_url != null}"
       }
       ],
       "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
   },
   "previewCardTemplate": {
       "title": "${if(name, name, 'N/A')}"
   }
   }

Sie können jetzt eine Nachrichtenerweiterung erstellen, die das OpenAPI-Beschreibungsdokument verwendet. Führen Sie die folgenden Schritte aus, um eine Nachrichtenerweiterung mithilfe des OpenAPI-Beschreibungsdokuments zu erstellen:

1. Öffnen Sie Visual Studio Code.

2. Wählen Sie das Symbol Teams Toolkit in der Visual Studio Code-Aktivitätsleiste aus.

3. Wählen Sie Neue App erstellenaus.

   

4. Wählen Sie Nachrichtenerweiterungaus.

5. Auswählen von benutzerdefinierten Suchergebnissen

6. Wählen Sie Mit einem OpenAPI-Beschreibungsdokument beginnen aus.

7. Wählen Sie Durchsuchen aus, und wählen Sie das Dokument OpenAPI-Beschreibung aus, das Sie zuvor gespeichert haben. Eine Liste der im Dokument verfügbaren APIs wird angezeigt.

8. Wählen Sie die APIs aus der Liste aus, und klicken Sie auf OK.

9. Wählen Sie Standardordner aus, um ihren Projektstammordner am Standardspeicherort zu speichern.

   

   Sie können den Standardspeicherort auch mithilfe der folgenden Schritte ändern:

   1. Wählen Sie Durchsuchen aus.

      

   2. Wählen Sie den Speicherort für den Projektarbeitsbereich aus.

   3. Wählen Sie ordner auswählen aus.

      

10. Geben Sie einen geeigneten Namen für Ihre App ein, und drücken Sie dann die EINGABETASTE.

    

    Ein Dialogfeld wird angezeigt. Wählen Sie Ja, ich vertraue den Autoren oder Nein, ich vertraue den Autoren nicht basierend auf Ihren Anforderungen aus.

    

    Ihre Teams-App mit einer API-basierten Nachrichtenerweiterungsfunktion wird in wenigen Sekunden erstellt.

    

    Nachdem Ihre App erstellt wurde, zeigt das Teams-Toolkit die folgende Meldung an:

    

    Wählen Sie Lokales Debuggen aus, um eine Vorschau Ihres Projekts anzuzeigen.

Nachdem das Gerüst erstellt wurde, zeigen Sie die Projektverzeichnisse und -dateien unter Explorer in Visual Studio Code an.

Bereitstellen Ihrer App

So stellen Sie Ihre App in Azure bereit:

1. Wechseln Sie zu Teams Toolkit, und wählen Sie im linken Bereich Ausführen und Debuggen aus (STRG+UMSCHALT+D).

2. Wählen Sie remote in Teams (Edge) starten aus der Dropdownliste Startkonfiguration aus.

   Das Teams-Toolkit stellt Ihre App in Azure bereit und stellt sie in Teams bereit.

   Hinweis

   Wenn Sie Ihre App zum ersten Mal bereitstellen, dauert es einige Minuten. Nachfolgende Rückstellungen sind schneller.

3. Wechseln Sie zu einer Chatnachricht, und wählen Sie das Symbol Aktionen und Apps aus. Suchen Sie im Flyoutmenü nach Ihrer App.

4. Wählen Sie die App aus der Liste aus, und lösen Sie Ihre Suchbefehle im Nachrichtenbereich zum Verfassen aus.

   

   Teams sendet das Suchergebnis als adaptive Karte in der Chatnachricht.

   

Abschließen der Herausforderung

• 2 Minuten verbleibend

Haben Sie sich so etwas einfallen lassen?

Herzlichen Glückwunsch!

• 100 % abgeschlossen!

Du hast es geschafft! Sie haben eine API-basierte Nachrichtenerweiterung erstellt.