Erweitertes Tutorial zum Erstellen einer API-basierten Nachrichtenerweiterung

Nachrichtenerweiterungen, die mit der API (API-basiert) erstellt wurden, verbessern die Funktionalität Ihrer Teams-Apps erheblich, indem sie ihnen die Interaktion mit externen Diensten ermöglichen. API-basierte Nachrichtenerweiterungen können dazu beitragen, Workflows zu optimieren, indem sie die Notwendigkeit reduzieren, zwischen verschiedenen Anwendungen zu wechseln.

Sie können API-basierte Nachrichtenerweiterungen 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 Nachrichtenerweiterung verwenden, um Kundendaten direkt aus Teams abzurufen und anzuzeigen. Diese App hilft dabei, Zeit zu sparen und die Effizienz zu verbessern, indem sie die Notwendigkeit reduziert, zwischen verschiedenen Anwendungen zu wechseln. Dieses Feature wird auf allen Plattformen unterstützt, auf denen Teams verfügbar ist, einschließlich Desktop, Web und Mobilgeräte.

Voraussetzungen

• 16 Minuten verbleibend

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

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.

Sie verfügen ü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 eines OpenAPI-Beschreibungsdokuments

• 15 Minuten verbleibend

OpenAPI-Beschreibung

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.

Für die Interaktion mit den APIs ist ein OpenAPI-Beschreibungsdokument erforderlich. Das OpenAPI-Beschreibungsdokument 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 keine Header- oder Cookie-Parameter ohne Standardwerte erfordern.
• 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, a search for "tool to create music" provides a list of 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.
      

Sie können überprüfen, ob das OpenAPI-Beschreibungsdokument gültig ist. Führen Sie die folgenden Schritte aus, um dies zu überprüfen:

1. Wechseln Sie zum Swagger/OpenAPI-Validierungssteuerelement , und überprüfen Sie das Dokument Zur OpenAPI-Beschreibung.

2. Speichern Sie das OpenAPI-Beschreibungsdokument.

3. Wechseln Sie zu Swagger Editor.

4. Fügen Sie im linken Bereich die OpenAPI-Beschreibung in den Editor ein.

5. Wählen Sie im rechten Bereich GET aus.

6. Wählen Sie Ausprobieren aus.

7. Geben Sie die Werte für den Suchparameter als Tool zum Erstellen von Musik ein.

8. Wählen Sie Ausführen aus. Der Swagger-Editor zeigt eine Antwort mit einer Liste von Produkten an.

   

9. Wechseln Sie zuAntworttext der Serverantwort>.

10. Kopieren Sie unter productsdas erste Produkt aus der Liste, und speichern Sie es zur späteren Referenz.

    

Erstellen einer Antwortrenderingvorlage

• 10 Minuten verbleibend

Ein OpenAPI-Beschreibungsdokument erfordert eine Antwortrenderingvorlage, damit die App auf die GET- oder POST-Anforderungen reagieren kann. Die Antwortrenderingvorlage besteht aus einer Vorlage für adaptive Karten, einer Vorschauvorlage Karte und Metadaten.

Vorlage für adaptive Karten

Führen Sie die folgenden Schritte aus, um eine Vorlage für adaptive Karten zu erstellen:

1. Wechseln Sie zu ChatGPT, und stellen Sie die folgende Abfrage im Bereich zum Verfassen von Nachrichten:

    Create an Adaptive Card Template that binds to the following response:
        "categories": [
            "Music Generation",
            "AI Detection"
        ],
        "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator",
        "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
        "name": "AI Music Generator",
        "opentools_url": "https://goto.opentools.ai/ai-music-generator",
        "platforms": [
            "Web",
            "App",
            "API"
        ]
   

2. Wählen Sie Nachricht senden aus.

3. ChatGPT generiert eine Antwort mit einer Vorlage für adaptive Karten, die an die Beispieldaten gebunden ist. Speichern Sie die Vorlage für adaptive Karten zur späteren Referenz.

   Es folgt ein Beispiel für die Vorlage für adaptive Karten:

   Vorlage für adaptive Karten

   {
   "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
   "type": "AdaptiveCard",
   "version": "1.4",
   "body": [
       {
       "type": "TextBlock",
       "text": "AI Music Generator",
       "weight": "Bolder",
       "size": "Large"
       },
       {
       "type": "TextBlock",
       "text": "Categories",
       "size": "Medium"
       },
       {
       "type": "TextBlock",
       "text": "Music Generation, AI Detection",
       "wrap": true
       },
       {
       "type": "TextBlock",
       "text": "Description",
       "size": "Medium"
       },
       {
       "type": "TextBlock",
       "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
       "wrap": true
       },
       {
       "type": "TextBlock",
       "text": "Platform",
       "size": "Medium"
       },
       {
       "type": "TextBlock",
       "text": "Web, App, API",
       "wrap": true
       }
   ],
   "actions": [
       {
       "type": "Action.OpenUrl",
       "title": "Learn More",
       "url": "https://goto.opentools.ai/ai-music-generator"
       },
       {
       "type": "Action.OpenUrl",
       "title": "Try It",
       "url": "https://goto.opentools.ai/c/ai-music-generator"
       }
   ]
   }
   
   

4. Führen Sie die folgenden Schritte aus, um zu überprüfen, ob die generierte adaptive Karte an die Beispieldaten gebunden ist:

   1. Wechseln Sie zu adaptiver Karte Designer.

   2. Wechseln Sie zu Host-App auswählen, und wählen Sie dann microsoft Teams aus der Dropdownliste aus.

   3. Wechseln Sie zum KARTENNUTZLAST-EDITOR , und fügen Sie den Vorlagencode für adaptive Karten ein.

   4. Wechseln Sie zum BEISPIELDATEN-EDITOR , und fügen Sie die GET-API-Antwort ein, die Sie zuvor gespeichert haben.

      

   5. Wählen Sie Vorschaumodus aus. Der Designer für adaptive Karten zeigt eine adaptive Karte mit den Daten an, die die Antwort an die Vorlage binden.

      

Erstellen einer Vorschauvorlage Karte

Die Vorschauversion Karte Vorlage kann die titleEigenschaften , subtitle und image enthalten. Wenn die API-Antwort kein Bild enthält, können Sie die Imageeigenschaft entfernen.

Im Folgenden sehen Sie ein Beispiel für eine Vorschau Karte Vorlage:

   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}",
    } 

Antwortrenderingvorlage

Die Antwortrenderingvorlage muss dem schema entsprechen, das unter gehostet wird https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.json.

Führen Sie die folgenden Schritte aus, um eine Antwortrenderingvorlage zu erstellen:

1. Erstellen Sie eine JSON-Datei, und fügen Sie der Datei den folgenden Code hinzu:

   { 
     "version": "1.0.0", 
     "$schema": "<URL_REFERENCE_TO_SCHEMA>", 
     "jsonPath": "", 
     "responseLayout": "", 
     "responseCardTemplate": { 
    },
    "previewCardTemplate": {
        }
    }
   

2. Aktualisieren Sie die Eigenschaften in der Antwortrenderingvorlage wie folgt:

   1. "version": "1.0.0"

   2. "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"

   3. "jsonPath": "tools"

      jsonPath ist der Pfad zu einem oder mehreren Ergebnissen in der JSON-Antwortantwort. Fügen Sie den jsonPath relevanten Daten/Arrays aus der Produktliste in der API-Antwort hinzu. In diesem Fall handelt es sich um jsonPath Tools. Weitere Informationen zum Bestimmen des JSON-Pfads finden Sie unter Abfragen von JSON mit JSON-Pfad.

   4. "responseLayout": "list"

      responseLayout gibt das Layout der Anlagen an. Wird für Antworten vom Typ Ergebnis verwendet. Unterstützte Typen sind List und Grid. Wenn der Antworttext ein Objekt mit mehreren Elementen wie Text, Titel und Bild enthält, muss das Antwortlayout auf listfestgelegt werden. Wenn die API-Antwort nur Bilder oder Miniaturansichten enthält, muss das Antwortlayout auf gridfestgelegt werden.

   5. "responseCardTemplate": Fügen Sie den Vorlagencode für adaptive Karten ein, den Sie zuvor gespeichert haben.

      responseCardTemplate ist eine Vorlage für adaptive Karten zum Zuordnen der JSON-Antwort zu einer adaptiven Karte.

   6. "previewCardTemplate": Fügen Sie die Vorschauversion Karte Vorlagencode ein, den Sie zuvor gespeichert haben.

      previewCardTemplateist eine Vorschau Karte Vorlage verwendet wird, um eine Vorschau der Ergebnisse im Nachrichtenerweiterungs-Flyout anzuzeigen.

3. Speichern Sie die Antwortrenderingvorlage im selben Ordner, in dem Sie das OpenAPI-Beschreibungsdokument gespeichert haben.

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

{
        "version": "devPreview",
        "jsonPath": "tools",
        "responseLayout": "list",
        "responseCardTemplate": {
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.4",
    "body": [
        {
        "type": "TextBlock",
        "text": "AI Music Generator",
        "weight": "Bolder",
        "size": "Large"
        },
        {
        "type": "TextBlock",
        "text": "Categories",
        "size": "Medium"
        },
        {
        "type": "TextBlock",
        "text": "Music Generation, AI Detection",
        "wrap": true
        },
        {
        "type": "TextBlock",
        "text": "Description",
        "size": "Medium"
        },
        {
        "type": "TextBlock",
        "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
        "wrap": true
        },
        {
        "type": "TextBlock",
        "text": "Platform",
        "size": "Medium"
        },
        {
        "type": "TextBlock",
        "text": "Web, App, API",
        "wrap": true
        }
    ],
    "actions": [
        {
        "type": "Action.OpenUrl",
        "title": "Learn More",
        "url": "https://goto.opentools.ai/ai-music-generator"
        },
        {
        "type": "Action.OpenUrl",
        "title": "Try It",
        "url": "https://goto.opentools.ai/c/ai-music-generator"
        }
    ]
    },
    "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}",
    } 
    }

Erstellen eines App-Manifests

• 5 Minuten verbleibend

Jetzt müssen Sie ein App-Manifest erstellen (zuvor als Teams-App-Manifest bezeichnet). Das App-Manifest beschreibt, wie Ihre App in das Microsoft Teams-Produkt integriert wird.

Erstellen eines Teams-App-Manifests

Führen Sie die folgenden Schritte aus, um das Manifest zu erstellen:

1. Erstellen Sie eine neue JSON-Datei. Ihr App-Manifest muss dem Schema entsprechen, das im Manifestschema der öffentlichen Entwicklervorschau definiert ist.

2. Fügen Sie der JSON-Datei den folgenden Code hinzu:

   App-Manifest

   {
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json",
    "manifestVersion": "devPreview",
    "version": "1.0.3",
    "id": "<<YOUR-MICROSOFT-APP-ID>>",
    "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": "Search ME API",
        "full": "Search ME API full"
    },
    "description": {
        "short": "product app for testing API Message Extensions",
        "full": "product app for testing API Message Extensions"
    },
    "accentColor": "#FFFFFF",
    "composeExtensions": [
        {
            "composeExtensionType": "",
            "apiSpecificationFile": "",
            "commands": [
                {
                    "context": [
                        "compose"
                    ],
                    "type": "query",
                    "title": "API for fetching Klarna.",
                    "id": "",
                    "parameters": [
                        {
                            "name": "",
                            "title": "",
                            "description": ""
                        }
                    ],
                    "description": "",
                    "apiResponseRenderingTemplateFile": ""
                }
            ]
        }
    ],
    "permissions": [
        "identity",
        "messageTeamMembers"
    ],
    "validDomains": []
   }
   

3. Aktualisieren Sie die App-Manifesteigenschaften wie folgt:

   • Ersetzen Sie durch <<YOUR-MICROSOFT-APP-ID>> die Microsoft App-ID des Bots.
   • Aktualisieren Sie den Wert für in composeExtensionTypeapiBased.
   • Aktualisieren Sie den Wert für in apiSpecificationFile den Pfad Ihrer OpenAPI-Beschreibungsdatei.
   • Aktualisieren Sie den Wert für in commands.idsearchTools.
   • Aktualisieren Sie den Wert für in commands.titleSearch for AI Tools.
   • Aktualisieren Sie den Wert für in commands.descriptionSearch for AI Tools.
   • Aktualisieren Sie den Wert für in parameters.namesearch. Wenn keine Parameter vorhanden sind, müssen die Werte Abfrageparameter sein oder properties.name auf eine Eigenschaft im Anforderungstextschema verweisen.
   • Aktualisieren Sie in apiResponseRenderingTemplateFile den Pfad Ihrer Antwortrenderingvorlagendatei.
   • Aktualisieren Sie den Wert für auf validDomains den Endpunkt, der service URL in der OpenAPI-Beschreibungsdatei definiert ist.

4. Speichern Sie das Teams-App-Manifest in demSelben Ordner, in dem Sie das OpenAPI-Beschreibungsdokument und die Antwortrenderingvorlage gespeichert haben.

   • Sie benötigen ein Farbbild und ein Gliederungsbild. Diese Bilder sollten im Ordner enthalten sein und in Ihrem Teams-App-Manifest referenziert werden.
   • Zippen Sie den Inhalt des Ordners. Die ZIP-Datei muss die folgenden Dateien enthalten:
     • OpenAPI-Beschreibungsdokument
     • Antwortrenderingvorlage
     • App-Manifest
     • Farbsymbol
     • Kontursymbol

Hochladen einer benutzerdefinierten App in Teams

• 2 Minuten verbleibend

Melden Sie sich bei der Teams-Testumgebung an, um Ihre App in Teams zu testen. Führen Sie die folgenden Schritte aus, um eine benutzerdefinierte App in Teams hochzuladen:

1. Wechseln Sie zu Microsoft Teams, und melden Sie sich mit Ihren Testmandantenanmeldeinformationen an.

2. Wechseln Sie zu Apps>App verwalten>App hochladen.

3. Wählen Sie Angepasste App hochladen aus.

4. Wählen Sie die erstellte ZIP-Datei und dann Öffnen aus.

5. Klicken Sie auf Hinzufügen. Die App wird Teams hinzugefügt.

   

6. Wechseln Sie zu einem Chat, wählen Sie + dann im Bereich Zum Verfassen von Nachrichten aus, und suchen Sie nach Ihrer App.

7. Wählen Sie die App aus, und erstellen Sie eine Suchabfrage.

   

8. Die App antwortet mit einer adaptiven Karte im Chatfenster.

9. Wählen Sie Senden aus.

   

Herzlichen Glückwunsch!

• 100 % abgeschlossen!

Du hast es geschafft! Sie haben gelernt, eine API-basierte Nachrichtenerweiterung mithilfe des OpenAPI-Beschreibungsdokuments zu erstellen.