Erstellen einer API-basierten Nachrichtenerweiterung
Hinweis
API-basierte Nachrichtenerweiterungen unterstützen nur Suchbefehle.
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.
Bevor Sie beginnen, stellen Sie sicher, dass Sie die folgenden Anforderungen erfüllen:
1. OpenAPI Description (OAD)
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, undnot(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 finden Sie unter OpenAPI-Struktur.
2. App-Manifest
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.apiSpecificationFileals relativen Pfad zur OpenAPI-Beschreibungsdatei innerhalb des Ordners. Dadurch wird das App-Manifest mit der API-Spezifikation verknüpft.Definieren Sie
apiResponseRenderingTemplateFileals 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 demoperationIdin der OpenAPI-Beschreibung übereinstimmen.Wenn ein erforderlicher Parameter ohne Standardwert ist, muss der Befehl
parameters.nameim App-Manifest mit demparameters.nameim Dokument OpenAPI Description übereinstimmen.Wenn kein erforderlicher Parameter vorhanden ist, muss der Befehl
parameters.nameim App-Manifest mit dem optionalenparameters.namein der OpenAPI-Beschreibung übereinstimmen.Stellen Sie sicher, dass die Parameter für jeden Befehl genau mit den Namen der Parameter übereinstimmen, die für den Vorgang in der OpenAPI-Spezifikation definiert sind.
Eine Antwortrenderingvorlage muss pro Befehl definiert werden, der zum Konvertieren von Antworten von einer API verwendet wird.
Die vollständige Beschreibung darf 128 Zeichen nicht überschreiten.
{ "$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
| Name | Beschreibung |
|---|---|
composeExtensions.composeExtensionType |
Compose-Erweiterungstyp. Aktualisieren Sie den Wert auf apiBased. |
composeExtensions.authorization |
Autorisierungsbezogene Informationen für die API-basierte Nachrichtenerweiterung |
composeExtensions.authorization.authType |
Enumeration möglicher Autorisierungstypen. Unterstützte Werte sind none, apiSecretServiceAuthund microsoftEntra. |
composeExtensions.authorization.apiSecretServiceAuthConfiguration |
Objekterfassungsdetails, die für die Dienstauthentifizierung erforderlich sind. Gilt nur, wenn der Authentifizierungstyp ist apiSecretServiceAuth. |
composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId |
Die Registrierungs-ID wird zurückgegeben, wenn der Entwickler den API-Schlüssel über das Entwicklerportal übermittelt. |
composeExtensions.apiSpecificationFile |
Verweist auf eine OpenAPI-Beschreibungsdatei im App-Paket. Schließen Sie ein, wenn der Typ ist apiBased. |
composeExtensions.commands.id |
Eindeutige ID, die Sie dem Suchbefehl zuweisen. Die Benutzeranforderung enthält diese ID. Die ID muss mit der OperationId in der OpenAPI-Beschreibung verfügbaren übereinstimmen. |
composeExtensions.commands.context |
Array, in dem die Einstiegspunkte für die Nachrichtenerweiterung definiert sind. Die Standardwerte sind compose und commandBox. |
composeExtensions.commands.parameters |
Definiert eine statische Liste von Parametern für den Befehl. Der Name muss dem parameters.name in der OpenAPI-Beschreibung zugeordnet werden. Wenn Sie auf eine Eigenschaft im Anforderungstextschema verweisen, muss der Name oder abfrageparametern zugeordnet properties.name werden. |
composeExtensions.commands.apiResponseRenderingTemplateFile |
Vorlage, die zum Formatieren der JSON-Antwort von der Entwickler-API auf die Antwort für adaptive Karten verwendet wird. [Obligatorisch] |
Weitere Informationen finden Sie unter composeExtensions.
3. Antwortrenderingvorlage
Hinweis
Teams unterstützt adaptive Karten bis Version 1.5 und adaptive Karten Designer bis Version 1.6.
- Definieren Sie die Schemaverweis-URL in der
$schema-Eigenschaft, um die Struktur Ihrer Vorlage festzulegen. - Die unterstützten Werte für
responseLayoutsindlistundgrid, die bestimmen, wie die Antwort visuell dargestellt wird. - Ein
jsonPathwird für Arrays oder empfohlen, wenn die Daten für die adaptive Karte nicht das Stammobjekt sind. Wenn Ihre Daten beispielsweise unterproductDetailsgeschachtelt sind, lautetproductDetailsIhr JSON-Pfad . - Definieren Sie
jsonPathals 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 in den CARD PAYLOAD EDITOR ein, und fügen Sie den Beispielantworteintrag im SAMPLE DATA EDITOR ein.
Der folgende Code ist ein Beispiel für eine Antwortrenderingvorlage:
Beispiel für eine Antwortrenderingvorlage
{
"version": "1.0",
"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
Erweiterte adaptive Karte
Parameter
| Eigenschaft | Typ | Beschreibung | Erforderlich |
|---|---|---|---|
version |
string |
Die Schemaversion der aktuellen Antwortrenderingvorlage. | Ja |
jsonPath |
string |
Der Pfad zum relevanten Abschnitt in den Ergebnissen, auf den responseCardTemplate und previewCardTemplate angewendet werden sollen. Wenn nicht festgelegt, wird das Stammobjekt als relevanter Abschnitt behandelt. Wenn der relevante Abschnitt ein Array ist, wird jeder Eintrag der responseCardTemplate und der previewCardTemplate zugeordnet. | Nein |
responseLayout |
responseLayoutType |
Gibt das Layout der Ergebnisse im Nachrichtenerweiterungs-Flyout an. Die unterstützten Typen sind list und grid. |
Ja |
responseCardTemplate |
adaptiveCardTemplate |
Eine Vorlage zum Erstellen einer adaptiven Karte aus einem Ergebniseintrag. | Ja |
previewCardTemplate |
previewCardTemplate |
Eine Vorlage zum Erstellen einer Vorschauversion Karte aus einem Ergebniseintrag. Die resultierende Vorschauversion Karte wird im Flyoutmenü der Nachrichtenerweiterung angezeigt. | Ja |
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. 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 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 in den Editor für gleiche Daten auf der rechten Seite ein. Stellen Sie sicher, dass die Karte ordnungsgemäß gerendert wird und Ihren Wünschen entspricht. Beachten Sie, dass Teams Karten bis Version 1.5 unterstützt, während der Designer 1.6 unterstützt.
Schemazuordnung
Die Eigenschaften im OpenAPI-Beschreibungsdokument werden der Vorlage für adaptive Karten wie folgt zugeordnet:
stringDie Typen ,number, undintegerbooleanwerden in textBlock konvertiert.Beispiel
Quellschema:
string,number,integerundbooleanname: type: string example: doggieZielschema:
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:
arraytype: array items: required: - name type: object properties: id: type: integer category: type: object properties: name: type: stringZielschema:
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:
objectcomponents: schemas: Pet: category: type: object properties: id: type: integer name: type: stringZielschema: 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:
imageimage: type: string format: uri description: The URL of the image of the item to be repairedZielschema:
"Image"{ "type": "Image", "url": "${image}", "$when": "${image != null}" }
Authentifizierung
Sie können die Authentifizierung in API-basierten Nachrichtenerweiterungen implementieren, um sicheren und nahtlosen Zugriff auf Anwendungen zu ermöglichen. Wenn ihre Nachrichtenerweiterung eine Authentifizierung erfordert, fügen Sie die authorization -Eigenschaft unter composeExtensions im App-Manifest hinzu, und definieren Sie den Authentifizierungstyp für Ihre Anwendung, indem Sie die authType -Eigenschaft unter authorizationfestlegen. Um die Authentifizierung für Ihre Nachrichtenerweiterung zu aktivieren, aktualisieren Sie Ihr App-Manifest mit einer der folgenden Authentifizierungsmethoden:
nichts
Sie können als Wert für authorization in einer API-basierten Nachrichtenerweiterung aktualisierennone, wenn die Nachrichtenerweiterung keine Authentifizierung für den Benutzer für den Zugriff auf die API erfordert.
"authorization": {
"authType": "none"
}
},
Geheimnisdienstauthentifizierung
Die API-Geheimnisdienstauthentifizierung ist eine sichere Methode für ihre App zur Authentifizierung mit der API. Sie können einen API-Schlüssel über das Entwicklerportal für Teams registrieren und eine API-Schlüsselregistrierungs-ID generieren. Aktualisieren Sie das App-Manifest mit dem apiSecretServiceAuthConfiguration -Objekt mit einer apiSecretRegistrationId -Eigenschaft. Diese Eigenschaft sollte die Verweis-ID enthalten, die zurückgegeben wurde, als Sie den API-Schlüssel über das Portal übermittelt haben.
Wenn eine API-Anforderung initiiert wird, ruft das System den API-Schlüssel von einem sicheren Speicherort ab und schließt ihn mithilfe des Bearertokenschemas in den Autorisierungsheader ein. Der API-Endpunkt überprüft beim Empfang der Anforderung die Gültigkeit des API-Schlüssels. Wenn die Überprüfung erfolgreich ist, verarbeitet der Endpunkt die Anforderung und gibt die gewünschte Antwort zurück, um sicherzustellen, dass nur authentifizierte Anforderungen Zugriff auf die Ressourcen der API erhalten.
Registrieren eines API-Schlüssels
Mit der API-Schlüsselregistrierung können Sie ihre APIs schützen, die sich hinter einer Authentifizierung befinden und in Nachrichtenerweiterungen verwendet werden. Sie können einen API-Schlüssel registrieren und die Domäne, den Mandanten und die App angeben, die auf die APIs zugreifen können, und die Geheimnisse bereitstellen, die zum Authentifizieren der API-Aufrufe erforderlich sind. Anschließend können Sie die API-Schlüssel-ID in die vereinfachte Nachrichtenerweiterung einfügen, und die API-Schlüssel-ID aktiviert die Authentifizierung für die API-Aufrufe, die sich hinter einer Authentifizierung befinden.
Führen Sie die folgenden Schritte aus, um einen API-Schlüssel zu registrieren:
Wechseln Sie zu Tools>API-Schlüsselregistrierung.
Wählen Sie + Neuer API-Schlüssel aus.
Aktualisieren Sie auf der Seite API-Schlüsselregistrierung unter API-Schlüssel registrieren Folgendes:
Beschreibung: Beschreibung des API-Schlüssels.
Domäne hinzufügen: Aktualisieren Sie den Basispfad für API-Endpunkte. Der Pfad muss eine sichere HTTPS-URL sein, einen vollqualifizierten Domänennamen enthalten und optional einen bestimmten Pfad enthalten. Beispiel:
https://api.yelp.com.
Wählen Sie unter Zielmandanten festlegen eine der folgenden Optionen aus:
- Home tenens
- Beliebiger Mandant
Option Geeignet in folgender Situation Beschreibung Basismandant Wenn Sie Ihre App in Ihrem Mandanten entwickeln und die App als benutzerdefinierte App oder als benutzerdefinierte App testen, die für Ihre Organisation erstellt wurde. Der API-Schlüssel kann nur innerhalb des Mandanten verwendet werden, in dem die API registriert ist. Beliebiger Mandant Nachdem Sie das Testen der App abgeschlossen haben und die App über verschiedene Mandanten hinweg aktivieren möchten. Stellen Sie sicher, dass Sie Ihren Zielmandanten auf Any tenant (Beliebiger Mandant ) aktualisieren, bevor Sie Ihr App-Paket an partner Center übermitteln. Der API-Schlüssel kann in anderen Mandanten verwendet werden, nachdem die App im Teams Store verfügbar ist. 
Wählen Sie unter Teams-App festlegen eine der folgenden Optionen aus:
- Beliebige Teams-App
- Vorhandene Teams-App-ID
Option Geeignet in folgender Situation Beschreibung Beliebige Teams-App Wenn Sie Ihre App in Ihrem Mandanten entwickeln und die App als benutzerdefinierte App oder als benutzerdefinierte App testen, die für Ihre Organisation erstellt wurde. Der API-Schlüssel kann mit jeder Teams-App verwendet werden. Dies ist nützlich, wenn nach dem Hochladen der App IDs für benutzerdefinierte Apps oder benutzerdefinierte Apps generiert werden, die für Ihre Organisation erstellt wurden. Vorhandene Teams-App-ID Nachdem Sie das Testen Ihrer App in Ihrem Mandanten als benutzerdefinierte App oder benutzerdefinierte App abgeschlossen haben, die für Ihre Organisation erstellt wurde. Aktualisieren Sie Ihre API-Schlüsselregistrierung, und wählen Sie Vorhandene Teams-App aus, und geben Sie die Manifest-ID Ihrer App ein. Die Option Vorhandene Teams-App bindet die REGISTRIERUNG des API-Geheimnisses an Ihre spezifische Teams-App. 
Wählen Sie + Geheimnis hinzufügen aus. Das Dialogfeld API-Schlüssel hinzufügen wird angezeigt.
Geben Sie einen Wert für das Geheimnis ein, und wählen Sie Speichern aus.
Hinweis
- Sie können bis zu zwei Geheimnisse für jede API-Schlüsselregistrierung verwalten. Wenn ein Schlüssel kompromittiert wird, kann er sofort entfernt werden, sodass Teams zum zweiten Schlüssel wechseln kann.
- Der Geheimniswert muss mindestens 10 Zeichen und höchstens 128 Zeichen umfassen.
- Wenn der erste Schlüssel zu einem Fehler 401 führt, versucht Teams automatisch, den zweiten Schlüssel zu verwenden. Es hilft bei einem unterbrechungsfreien Dienst für Benutzer und beseitigt potenzielle Ausfallzeiten während der Erstellung eines neuen Geheimnisses.
Eine API-Schlüsselregistrierungs-ID wird generiert.
Kopieren und speichern Sie die REGISTRIERUNGS-ID des API-Schlüssels, und aktualisieren Sie sie als Wert für die apiSecretRegistrationId Eigenschaft im App-Manifest.
Aktualisieren des App-Manifests
Sie können eingehende Anforderungen an Ihren Dienst autorisieren, indem Sie einen statischen API-Schlüssel konfigurieren. Der API-Schlüssel wird sicher gespeichert und dem API-Aufruf hinzugefügt. Fügen Sie ein apiSecretServiceAuthConfiguration Objekt mit einer apiSecretRegistrationId -Eigenschaft hinzu, die die Verweis-ID enthält, wenn Sie den API-Schlüssel über das Entwicklerportal für Teams übermitteln. Weitere Informationen finden Sie unter composeExtensions.commands.
"composeExtensions": [
{
"composeExtensionType": "apiBased",
"authorization": {
"authType": "apiSecretServiceAuth",
"apiSecretServiceAuthConfiguration": {
"apiSecretRegistrationId": "9xxxxb0f-xxxx-40cc-xxxx-15xxxxxxxxx3"
}
},
Microsoft Entra
microsoftEntra bei der Authentifizierungsmethode wird die Teams-Identität eines App-Benutzers verwendet, um diesen Zugriff auf Ihre App zu gewähren. Ein Benutzer, der sich bei Teams angemeldet hat, muss sich innerhalb der Teams-Umgebung nicht erneut bei Ihrer App anmelden. Wenn nur eine Zustimmung des App-Benutzers erforderlich ist, ruft die Teams-App Zugriffsdetails für sie aus Microsoft Entra ID ab. Nachdem der App-Benutzer seine Einwilligung erteilt hat, kann er auch von anderen Geräten aus auf die App zugreifen, ohne erneut überprüft werden zu müssen.
Voraussetzungen
Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:
- Ein Azure-Konto mit einem aktiven Abonnement.
- Grundlegende Kenntnisse in der entwicklung von Microsoft Entra ID und Teams-Apps.
Die folgende Abbildung zeigt, wie einmaliges Anmelden funktioniert, wenn ein Teams-App-Benutzer versucht, auf eine API-bsed-Nachrichtenerweiterungs-App zuzugreifen:
- Der Benutzer ruft die API-basierte Nachrichtenerweiterungs-App aus einer Nachrichtenerweiterung in Teams auf und fordert einen Befehl an, der eine Authentifizierung erfordert.
- Die App sendet eine Anforderung mit der App-ID und dem erforderlichen Bereich (access_as_user) an den Teams-Back-End-Dienst.
- Der Teams-Back-End-Dienst überprüft, ob der Benutzer der App und dem Bereich zugestimmt hat. Andernfalls wird ein Zustimmungsbildschirm für den Benutzer angezeigt, und es wird um die Berechtigung gebeten.
- Wenn der Benutzer zustimmt, generiert der Teams-Back-End-Dienst ein Zugriffstoken für den Benutzer und die App und sendet es an die App im Autorisierungsheader der Anforderung.
- Die App überprüft das Token. Der Benutzer kann die Benutzerinformationen aus dem Token extrahieren, z. B. den Namen, die E-Mail-Adresse und die Objekt-ID.
- Die App kann das Token verwenden, um eine eigene API aufzurufen.
- Die App gibt die Antwort an den Benutzer in Teams zurück.
Führen Sie die folgenden Schritte aus, um die Authentifizierungsmethode für die API-basierte Nachrichtenerweiterung zu aktivieren microsoftEntra :
Registrieren einer neuen App in Microsoft Entra ID
Öffnen Sie das Azure-Portal in Ihrem Webbrowser.
Wählen Sie das Symbol App-Registrierungen aus.
Die Seite App-Registrierungen wird angezeigt.
Wählen Sie das Symbol + Neue Registrierung aus.
Die Seite Anwendung registrieren wird angezeigt.
Geben Sie den Namen Ihrer App ein, die dem App-Benutzer angezeigt werden soll. Sie können den Namen zu einem späteren Zeitpunkt ändern, wenn Sie möchten.
Wählen Sie den Typ des Benutzerkontos aus, das auf Ihre App zugreifen kann. Sie können aus einzel- oder mehrinstanzenfähigen Optionen in Organisationsverzeichnissen auswählen oder den Zugriff nur auf persönliche Microsoft-Konten beschränken.
Optionen für unterstützte Kontotypen
Option Wählen Sie dies aus, um... Nur Konten in diesem Organisationsverzeichnis (nur Microsoft – einzelner Mandant) Erstellen Sie eine Anwendung, die nur von Benutzern (oder Gästen) in Ihrem Mandanten verwendet werden kann.
Diese App wird häufig als benutzerdefinierte App bezeichnet, die für Ihre Organisation (LOB-App) erstellt wurde. Diese App ist eine Einzelmandantenanwendung im Microsoft Identity Platform.Konten in einem beliebigen Organisationsverzeichnis (beliebiger Microsoft Entra ID Mandanten – mehrinstanzenfähig) Ermöglichen Sie Benutzern in einem beliebigen Microsoft Entra Mandanten, Ihre Anwendung zu verwenden. Diese Option ist z. B. geeignet, wenn Sie eine SaaS-Anwendung erstellen und diese für mehrere Organisationen verfügbar machen möchten.
Dieser App-Typ wird im Microsoft Identity Platform als mehrinstanzenfähige Anwendung bezeichnet.Konten in einem beliebigen Organisationsverzeichnis (beliebiger Microsoft Entra ID Mandanten – mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) Sprechen Sie die breiteste Kundengruppe an.
Wenn Sie diese Option auswählen, registrieren Sie eine mehrinstanzenfähige Anwendung, die auch App-Benutzer unterstützen kann, die über persönliche Microsoft-Konten verfügen.Nur persönliche Microsoft-Konten Erstellen Sie eine Anwendung nur für Benutzer, die über persönliche Microsoft-Konten verfügen. Hinweis
Sie müssen keinen Umleitungs-URI eingeben, um einmaliges Anmelden für eine API-basierte Nachrichtenerweiterungs-App zu aktivieren.
Wählen Sie Registrieren aus. Im Browser wird eine Nachricht angezeigt, die besagt, dass die App erstellt wurde.
Die Seite mit der App-ID und anderen Konfigurationen wird angezeigt.
Notieren Und speichern Sie die App-ID aus der Anwendungs-ID (Client-ID), um das App-Manifest später zu aktualisieren.
Ihre App ist in Microsoft Entra ID registriert. Sie verfügen jetzt über die App-ID für Ihre API-basierte Nachrichtenerweiterungs-App.
Konfigurieren des Bereichs für das Zugriffstoken
Nachdem Sie eine neue App-Registrierung erstellt haben, konfigurieren Sie Bereichsoptionen (Berechtigungsoptionen) zum Senden von Zugriffstoken an den Teams-Client und Autorisieren vertrauenswürdiger Clientanwendungen zum Aktivieren des einmaligen Anmeldens.
Um den Bereich zu konfigurieren und vertrauenswürdige Clientanwendungen zu autorisieren, benötigen Sie Folgendes:
- Hinzufügen von Anwendungs-ID-URI: Konfigurieren Sie Bereichsoptionen (Berechtigungsoptionen) für Ihre App. Machen Sie eine Web-API verfügbar, und konfigurieren Sie den Anwendungs-ID-URI.
- API-Bereich konfigurieren: Definieren Sie den Bereich für die API und die Benutzer, die für einen Bereich zustimmen können. Sie können administratoren nur erlauben, ihre Zustimmung für Berechtigungen mit höheren Berechtigungen zu erteilen.
- Konfigurieren einer autorisierten Clientanwendung: Erstellen Sie autorisierte Client-IDs für Anwendungen, die Sie vorab authentifizieren möchten. Dadurch kann der App-Benutzer auf die von Ihnen konfigurierten App-Bereiche (Berechtigungen) zugreifen, ohne dass eine weitere Zustimmung erforderlich ist. Authentifizieren Sie nur die Clientanwendungen, denen Sie vertrauen, da Ihre App-Benutzer nicht die Möglichkeit haben, die Zustimmung abzulehnen.
Anwendungs-ID-URI
Wählen Sie im linken Bereich Verwalten>Eine API verfügbar machen aus.
Die Seite API verfügbar machen wird angezeigt.
Wählen Sie Hinzufügen aus, um den Anwendungs-ID-URI in Form von
api://{AppID}zu generieren.
Der Abschnitt zum Festlegen des Anwendungs-ID-URI wird angezeigt.
Geben Sie den Anwendungs-ID-URI im hier erläuterten Format ein.
- Der Anwendungs-ID-URI ist vorab mit der App-ID (GUID) im Format
api://{AppID}ausgefüllt. - Das URI-Format der Anwendungs-ID muss wie folgt sein:
api://fully-qualified-domain-name.com/{AppID}. - Fügen Sie die
fully-qualified-domain-name.comzwischenapi://und{AppID}(d. h. der GUID) ein. Beispiel: api://example.com/{AppID}.
Wichtig
Vertrauliche Informationen: Der Anwendungs-ID-URI wird im Rahmen des Authentifizierungsprozesses protokolliert und darf keine vertraulichen Informationen enthalten.
Anwendungs-ID-URI für Eine App mit mehreren Funktionen: Wenn Sie eine API-basierte Nachrichtenerweiterung erstellen, geben Sie den Anwendungs-ID-URI als
api://fully-qualified-domain-name.com/{YourClientId}ein, wobei {YourClientId} Ihre Microsoft Entra App-ID ist.Format für Domänennamen: Verwenden Sie Kleinbuchstaben als Domänennamen. Verwenden Sie keine Großbuchstaben.
Um beispielsweise einen App-Dienst oder eine Web-App mit dem Ressourcennamen zu erstellen:
demoapplicationWenn der verwendete Basisressourcenname wie folgt lautet Die URL wird folgende sein... Format wird unterstützt auf... demoapplication https://demoapplication.example.netAlle Plattformen. DemoApplication https://DemoApplication.example.netNur Desktop, Web und iOS. Es wird unter Android nicht unterstützt. Verwenden Sie die Demoanwendung der Kleinbuchstabenoption als Basisressourcennamen.
- Der Anwendungs-ID-URI ist vorab mit der App-ID (GUID) im Format
Wählen Sie Speichern.
Im Browser wird eine Meldung angezeigt, die besagt, dass der Anwendungs-ID-URI aktualisiert wurde.
Der Anwendungs-ID-URI wird auf der Seite angezeigt.
Notieren und speichern Sie den Anwendungs-ID-URI, um das App-Manifest später zu aktualisieren.
Konfigurieren des API-Bereichs
Hinweis
API-basierte Nachrichtenerweiterungen unterstützen nur access_as_user Bereich.
Wählen Sie + Bereich hinzufügen im Abschnitt Bereiche, die von dieser API definiert werden aus.
Die Seite Einen Bereich hinzufügen wird angezeigt.
Geben Sie die Details zum Konfigurieren des Bereichs ein.
- Geben Sie den Bereichsnamen ein. Dieses Feld ist obligatorisch.
- Wählen Sie den Benutzer aus, der die Zustimmung für diesen Bereich erteilen kann. Die Standardoption ist Nur Administratoren.
- Geben Sie den Anzeigename der Administratoreinwilligung ein. Dieses Feld ist obligatorisch.
- Geben Sie die Beschreibung für die Administratoreinwilligung ein. Dieses Feld ist obligatorisch.
- Geben Sie den Anzeigename der Benutzereinwilligung ein.
- Geben Sie die Beschreibung für die Benutzereinwilligung ein.
- Wählen Sie die Option Aktiviert für den Status aus.
- Klicken Sie auf Bereich hinzufügen.
Im Browser wird eine Meldung angezeigt, die besagt, dass der Bereich hinzugefügt wurde.
Der von Ihnen definierte neue Bereich wird auf der Seite angezeigt.
Konfigurieren einer autorisierten Clientanwendung
Navigieren Sie durch die Seite API verfügbar machen zum Abschnitt Autorisierte Clientanwendung, und wählen Sie + Clientanwendung hinzufügen aus.
Die Seite Ein Clientanwendung hinzufügen wird angezeigt.
Geben Sie die entsprechende Microsoft 365-Client-ID für die Anwendungen ein, die Sie für die Webanwendung Ihrer App autorisieren möchten.
Hinweis
- Die Microsoft 365-Client-IDs für mobile, Desktop- und Webanwendungen für Teams sind die tatsächlichen IDs, die Sie hinzufügen müssen.
- Für eine Teams-API-basierte Nachrichtenerweiterungs-App benötigen Sie entweder Web oder SPA, da Sie keine mobile oder Desktopclientanwendung in Teams verwenden können.
Wählen Sie eine der folgenden Client-IDs aus:
Client-ID verwenden Zum Autorisieren... 1fec8e78-bce4-4aaf-ab1b-5451cc387264 mobile Teams- oder Desktopanwendung 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 Teams-Webanwendung Wählen Sie den Anwendungs-ID-URI aus, den Sie für Ihre App in Autorisierte Bereiche erstellt haben, um den Bereich der Web-API hinzuzufügen, die Sie verfügbar gemacht haben.
Wählen Sie Anwendung hinzufügen aus.
Im Browser wird eine Meldung angezeigt, die besagt, dass die autorisierte Client-App hinzugefügt wurde.
Die Client-ID der autorisierten App wird auf der Seite angezeigt.
Hinweis
Sie können mehr als eine Clientanwendung autorisieren. Wiederholen Sie die Schritte dieses Verfahrens zum Konfigurieren einer anderen autorisierten Clientanwendung.
Sie haben app-Bereich, Berechtigungen und Clientanwendungen erfolgreich konfiguriert. Notieren und speichern Sie den Anwendungs-ID-URI. Als Nächstes konfigurieren Sie die Zugriffstokenversion.
Aktualisieren des App-Manifests
Hinweis
webApplicationInfo wird in der App-Manifestversion 1.5 oder höher unterstützt.
Aktualisieren Sie die folgenden Eigenschaften in der App-Manifestdatei:
webApplicationInfo: Ermöglicht SSO für Ihre App, damit App-Benutzer nahtlos auf Ihre API-basierte Nachrichtenerweiterungs-App zugreifen können. -Abschnitt, der wichtige Details zu Ihrer App enthält. Der Anwendungs-ID-URI, den Sie in Microsoft Entra ID registriert haben, ist mit dem Bereich der API konfiguriert, die Sie verfügbar gemacht haben. Konfigurieren Sie den Unterdomänen-URI Ihrer App inresource, um sicherzustellen, dass die Authentifizierungsanforderung vongetAuthToken()der im App-Manifest angegebenen Domäne stammt. Weitere Informationen finden Sie unter webApplicationInfo.
microsoftEntraConfiguration: Aktiviert die Authentifizierung mit einmaligem Anmelden für Ihre App. Konfigurieren Sie diesupportsSingleSignOn-Eigenschaft auf, umtrueeinmaliges Anmelden zu unterstützen und den Bedarf an mehreren Authentifizierungen zu reduzieren.
So konfigurieren Sie das App-Manifest:
Öffnen Sie das Api-basierte Nachrichtenerweiterungs-App-Projekt.
Öffnen Sie den App-Manifestordner.
Hinweis
- Der App-Manifestordner sollte sich im Stammverzeichnis Ihres Projekts befinden. Weitere Informationen finden Sie unter Erstellen eines Microsoft Teams-App-Pakets.
- Weitere Informationen zum Erstellen eines manifest.json finden Sie im App-Manifestschema.
Öffnen der
manifest.jsonDateiFügen Sie der App-Manifestdatei den folgenden Codeausschnitt hinzu:
webApplicationInfo
"webApplicationInfo": { "id": "{Microsoft Entra AppId}", "resource": "api://subdomain.example.com/{Microsoft Entra AppId}" }Dabei gilt Folgendes:
{Microsoft Entra AppId}ist die App-ID, die Sie erstellt haben, als Sie Ihre App in Microsoft Entra ID registriert haben. Es ist die GUID.subdomain.example.comist der Anwendungs-ID-URI, den Sie beim Erstellen des Bereichs in Microsoft Entra ID registriert haben.
MicrosoftEntraConfiguration
"authorization": { "authType": "microsoftEntra", “microsoftEntraConfiguration”: { “supportsSingleSignOn”: true } },Aktualisieren Sie die URL der tertiären Domäne in den folgenden Eigenschaften:
contentUrlconfigurationUrl
Speichern Sie die App-Manifestdatei.
Weitere Informationen finden Sie unter composeExtensions.commands.
Token authentifizieren
Wenn die Nachrichtenerweiterung die API während der Authentifizierung aufruft, empfängt sie eine Anforderung mit dem Authentifizierungstoken des Benutzers (AED-Token). Die Nachrichtenerweiterung fügt dann das Token im Autorisierungsheader der ausgehenden HTTP-Anforderung hinzu. Das Headerformat ist Authorization: Bearer <token_value>. Beispielsweise, wenn eine Nachrichtenerweiterung einen API-Aufruf an einen Dienst sendet, der eine Authentifizierung erfordert. Die Erweiterung erstellt eine HTTP-Anforderung wie folgt:
GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Nachdem die API-basierte Nachrichtenerweiterung einen Anforderungsheader mit Token abgerufen hat, führen Sie die folgenden Schritte aus:
Authentifizieren: Überprüfen Sie das Token für die Ansprüche "Zielgruppe", "Bereich", "Aussteller" und "Signatur", um zu überprüfen, ob das Token für Ihre App gilt.
Es folgt ein Beispiel für ein JSON-Webtoken (JWT) mit einem Header und einer Antwort:
{ "typ": "JWT", "rh": "0.AhoAv4j5cvGGr0GRqy180BHbR6Rnn7s7iddIqxdA7UZsDxYaABY.", "alg": "RS256", "kid": "q-23falevZhhD3hm9CQbkP5MQyU" }.{ "aud": "00000002-0000-0000-c000-000000000000", "iss": "https://login.microsoftonline.com/72f988bf-86f1-41af-91ab-2d7cd011db47/v2.0", "iat": 1712509315, "nbf": 1712509315, "exp": 1712513961, "aio": "Y2NgYEjJqF0stqv73u41a6ZmxPEvBgA=", "azp": "1fec8e78-bce4-4aaf-ab1b-5451cc387264", "azpacr": "0", "name": "John Doe", "oid": "00000000-0000-0000-0000-000000000000", "preferred_username": "john.doe@contoso.com", "rh": "I", "scp": "access_as_user", "sub": "e4uM7JgAEm08GBuasSltQjvPuMX1fR5TqxopJpqZJB8", "tid": "12345678-aaaa-bbbb-cccc-9876543210ab", "uti": "h7DMQwSPAEeiEe62JJUGAA", "ver": "2.0" }Verwenden Sie das Token: Extrahieren Sie die Benutzerinformationen aus dem Token, z. B. Name, E-Mail-Adresse und Objekt-ID, und verwenden Sie das Token, um die eigene API der Nachrichtenerweiterungs-App aufzurufen.
Hinweis
Die API empfängt ein Microsoft Entra Token, wobei der Bereich auf
access_as_userfestgelegt ist, wie im Azure-Portal registriert. Das Token ist jedoch nicht berechtigt, andere Downstream-APIs wie Microsoft Graph aufzurufen.
Problembehandlung
Wenn Beim Hochladen der App in Teams die Fehlermeldung Manifestanalyse hat fehlgeschlagen angezeigt wird, verwenden Sie das Teams-App-Validierungssteuerelement , um das App-Paket zu überprüfen, einschließlich des App-Manifests und der OpenAPI-Spezifikationsdatei. Überprüfen Sie das App-Manifest und die Dokumentanforderungen für die OpenAPI-Beschreibung , um Fehler oder Warnungen zu beheben, und versuchen Sie, Ihre App hochzuladen.
Wenn beim Ausführen Ihrer App in Teams Probleme auftreten, führen Sie die folgenden Schritte zur Problembehandlung aus, um Ihr Problem zu identifizieren und zu beheben:
Netzwerk: Wählen Sie die Registerkarte Netzwerk in Entwicklungstools aus, um die Netzwerkaktivität zu überprüfen.
Öffnen Sie den Teams-Webclient.
Melden Sie sich mit Ihren Microsoft 365-Anmeldeinformationen an.
Wechseln Sie zu einem Chat, und führen Sie Ihre Nachrichtenerweiterungs-App aus.
Wählen Sie oben rechts Einstellungen und mehr (...) aus. Wechseln Sie zu Weitere Tools>Entwicklungstools.
Wählen Sie Netzwerk aus. Wählen Sie die Filteroption aus, und geben Sie invoke in das Suchfeld ein.
Wählen Sie einen Fehler aus der Liste aus.
Wählen Sie im rechten Bereich die Registerkarte Antwort aus.
Ein JSON-Objekt, das eine Fehlerantwort eines Diensts oder einer API darstellt, wird angezeigt. Es enthält ein
standardizedError-Objekt miterrorCode,errorSubCodeunderrorDescription, die weitere Details zum Fehler enthalten.
Häufige HTTP-Fehlerantworten:
- Ein Fehler vom Typ 400 Ungültige Anforderung kann auftreten, wenn ein Anforderungsparameter fehlt oder falsch formatiert ist.
- Der Fehler 401 Unauthorized oder 403 Forbidden deutet auf Probleme mit dem API-Schlüssel hin, z. B. fehlender oder nicht autorisierter Schlüssel.
- Ein interner Serverfehler 500 gibt an, dass der Dienst aufgrund eines serverseitigen Problems nicht weiß, wie er reagieren soll.
Problembehandlung mit Tools: Wenn die Informationen aus der Netzwerkablaufverfolgung nicht ausreichen, können Sie eine Anforderung nach dem OpenAPI-Beschreibungsdokument erstellen und Tools wie Swagger Editor oder Postman verwenden, um die Anforderung zu testen, einschließlich des Autorisierungsheaders für den API-Schlüssel, falls erforderlich.
Wenn Sie die Fehler nicht beheben können, empfehlen wir Ihnen, sich an den Microsoft Teams-Produktsupport zu wenden, um weitere Unterstützung zu erhalten.
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für