Verbreiten von Links

  • Artikel

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt Nachrichtenerweiterungen – v3 SDK im Ordner Ressourcen der Dokumentation.

In diesem Dokument erfahren Sie, wie Sie Ihrem App-Manifest mithilfe des Entwicklerportals und manuell die Linkentflechtung hinzufügen. Beim Entpacken von Links kann sich Ihre App registrieren, um eine Aufrufaktivität zu empfangen, wenn URLs mit einer bestimmten Domäne in den Nachrichtenbereich zum Verfassen eingefügt werden. Die invoke-Aktivität enthält die vollständige URL, die in den Bereich zum Verfassen von Nachrichten eingefügt wurde, und Sie können mit einer Karte antworten, die der Benutzer öffnen kann, die zusätzliche Informationen oder Aktionen bereitstellt. Dies funktioniert ähnlich wie ein Suchbefehl, wobei die URL als Suchbegriff dient. Sie können jetzt Die Linkentflechtung zu Microsoft Teams hinzufügen, ohne die App zu installieren.

Screenshot: Link-Bereitstellung für eine Teams-App, die in Teams und anderen Apps installiert oder nicht installiert ist

Hinweis

  • Das Ergebnis der Verbreitung von Links wird 30 Minuten lang zwischengespeichert.
  • Das Entpacken von Links unterstützt adaptive Karten, Version 1.3 und früher.
  • Messagingerweiterungsbefehle sind für die Link-Entflechtung nicht erforderlich. Es muss jedoch mindestens ein Befehl im Manifest vorhanden sein, da es sich um eine obligatorische Eigenschaft in Messagingerweiterungen handelt. Weitere Informationen finden Sie unter Compose-Erweiterungen.
  • Für mobile Clients wird das Entflechten von Links nur für Links unterstützt, die keine Authentifizierung erfordern.

Die folgende Abbildung zeigt ein Beispiel für das Entpacken von Links in Teams-Desktop- und mobilen Clients:

Wenn ein Link in den Teams-Nachrichtenbereich zum Verfassen eingefügt wird, wird der Link in eine Karte mit den Arbeitselementdetails eingefügt.

Screenshot des Beispiels zum Entpacken von Links für Azure Dev Ops-Links, die im Nachrichtenbereich zum Verfassen von Teams eingefügt wurden.

Weitere Informationen zum Entpacken von Links finden Sie im folgenden Video:


Um Ihrem App-Manifest das Verbreiten von Links hinzuzufügen, fügen Sie dem composeExtensions-Abschnitt des JSON-Codes Ihres App-Manifests ein neues messageHandlers-Array hinzu. Sie können das Array mithilfe des Entwicklerportals oder manuell hinzufügen. Domänenauflistungen können Wildcards enthalten, die z. B *.example.com . genau einem Segment der Domäne entsprechen. Wenn Sie mit übereinstimmen a.b.example.commüssen, verwenden Sie *.*.example.com.

Hinweis

Stellen Sie sicher, dass Sie keine Domänen hinzufügen, die sich nicht in Ihrem Steuerelement befinden, weder direkt noch über Wildcards. Beispielsweise yourapp.onmicrosoft.com ist gültig, aber *.onmicrosoft.com nicht gültig. Die Domänen der obersten Ebene sind verboten, *.comz. B. , *.org.

  1. Öffnen Sie das Entwicklerportal über den Microsoft Teams-Client, und wählen Sie dann die Registerkarte Apps aus.

    Screenshot: Entwicklerportal mit rot hervorgehobenen Apps

    Hinweis

    Sie müssen die Entwicklerportal-App hinzufügen, wenn Sie sie nicht in Ihrem Teams-Client hinzugefügt haben.

    Screenshot: Teams mit rot hervorgehobenem Such- und Entwicklerportal

  2. Laden Sie Ihr App-Manifest.

    Screenshot des Entwicklerportals mit den App-Informationen.

  3. Wählen Sie unter App-Features die Option Messaging-Erweiterung und dann entweder Vorhandenen Bot auswählen oder Neuen Bot erstellen aus.

    Screenshot: App-Features mit rot hervorgehobener App-Features und Messaging-Erweiterung

    Screenshot der Messaging-Erweiterung mit rot hervorgehobener Option

  4. Klicken Sie auf Speichern.

  5. Wählen Sie im Abschnitt Vorschaulinks die Option Domäne hinzufügen aus, und geben Sie dann eine gültige Domäne ein.

  6. Wählen Sie Hinzufügen. In der folgenden Abbildung wird der Prozess erläutert:

    Screenshot des Abschnitts

Hinweis

Wenn die Authentifizierung über Microsoft Entra ID hinzugefügt wird, lösen Sie Links in Teams mithilfe des Bots auf.

Zuerst müssen Sie das messageHandlers Array ihrem App-Manifest hinzufügen und die Nachrichtenerweiterung für die Interaktion mit Links aktivieren. Im folgenden Beispiel wird erläutert, wie Sie das Verbreiten von Links manuell hinzufügen:

...
{
  "composeExtensions": [
    {
      "botId": "abc123456-ab12-ab12-ab12-abcdef123456",
      "messageHandlers": [
        {
          "type": "link",
          "value": {
            "domains": [
              "*.trackeddomain.com"
            ]
          }
        }
      ]
    }
  ]
}
...

Ein vollständiges Manifestbeispiel finden Sie unter Manifestreferenz.

Nachdem Sie die Domäne zum App-Manifest hinzugefügt haben, müssen Sie Ihren Webdienstcode aktualisieren, um die invoke Anforderung zu verarbeiten. Verwenden Sie die empfangene URL, um Ihren Dienst durchzusuchen und eine Kartenantwort zu erstellen. Wenn Sie mit mehr als einer Karte antworten, wird nur die erste Kartenantwort verwendet.

Hinweis

Die Antwort eines Bots muss eine preview -Eigenschaft enthalten.

Die folgenden Kartentypen werden unterstützt:

Weitere Informationen finden Sie unter Aktionstypaufruf.

Der folgende Code ist ein Beispiel für die invoke Anforderung:

Es folgt ein Beispiel für invoke, die an Ihren Bot gesendet werden:

   {
     "type": "invoke",
     "name": "composeExtension/queryLink",
     "value": {
       "url": "https://theurlsubmittedbyyouruser.trackeddomain.com/id/1234"
     }
   }

Beispiel für die Antwort:

{
 "composeExtension":
   {
     "type": "result",
     "attachmentLayout": "list",
     "attachments": 
     [
       {
         "contentType": "application/vnd.microsoft.card.adaptive",
         "preview": 
          {
            "contentType": "application/vnd.microsoft.card.adaptive",
            "content": << Card Payload >>
          },
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": << Card Payload >>
       }
      ]
   }
}

Die gängigste Möglichkeit zum Freigeben von Inhalten in Microsoft Teams ist links. Für jeden Link entpackt Teams eine Vorschau des Links in eine adaptive Karte mit den Informationen wie Bild, Titel und Beschreibung.

Sie können umfangreiche Unfurl-Vorschauen Ihrer Links anzeigen, ohne Ihre App in Microsoft Teams zu installieren. Fügen Sie ihrer Website die schema.org Metadaten im JSON-LD-Format hinzu, und verwenden Sie die Microfunktionsvorlagen , die Ihrem Produkt entsprechen. Teams verwendet diese Vorlagen, um umfangreiche Vorschauen für Ihre Links in Microsoft Teams zu entpacken.

Wenn Sie Ihrer Website bereits schema.org hinzugefügt haben, können Sie die umfangreiche Vorschau ihres Links anzeigen, indem Sie ihn in den Bereich Zum Verfassen von Teams-Nachrichten einfügen.

Screenshot: Beispiel für eine umfangreiche Unfurl-Vorschau, wenn ein Link im Bereich zum Verfassen von Teams-Nachrichten eingefügt wird.

Wenn Sie Ihrer Website keine schema.org hinzugefügt haben, können Sie die umfangreiche Vorschauversion manuell überprüfen, indem Sie die folgenden Schritte ausführen:

  1. Fügen Sie der Website die schema.org Metadaten im JSON-LD-Format hinzu.

  2. Suchen Sie auf Ihrer Website nach dem unterstützten @type Attribut, und kopieren Sie die Metadaten unter dem Skripttag application/ld+json.

  3. Öffnen Sie den Designer für adaptive Karten , und erstellen Sie eine neue Datei.

  4. Fügen Sie im SAMPLE DATA EDITOR die JSON-Metadaten von Ihrer Website ein.

    Screenshot: Beispiel für Websitemetadaten im Abschnitt

  5. Überprüfen Sie die Microfunktionsvorlage, und fügen Sie den Vorlagencode im CARD PAYLOAD EDITOR hinzu.

    Screenshots zeigen ein Beispiel für eine Mikrofunktionsvorlage, die im Karte Nutzlast-Editor in Adaptive Card Designer hinzugefügt wurde.

    Fügen Sie ihren Websitemetadaten im SAMPLE DATA EDITOR bei Bedarf neue Attribute aus der Vorlage hinzu.

  6. Wählen Sie Vorschaumodus aus, um eine Vorschau der Oberfläche für das Entpacken adaptiver Karten anzuzeigen.

Weitere Informationen finden Sie unter Mikrofunktionen für Websitelinks.

Das Entpacken von Zero Install-Links hilft Ihnen, Vorschauen für Ihre freigegebenen Links zu entpacken, noch bevor ein Benutzer Ihre App in Teams entdeckt oder installiert. Sie können Karten mit einer neuen invoke Anforderung anonym entpacken oder eine vorab authentifizierte Vorschau für adaptive Karten für Benutzer erstellen, bevor sie Ihre App installieren oder authentifizieren.

Die folgende Abbildung enthält einen sequenziellen Flow zum Aktivieren und Verwenden der Entflechtung von Nullinstallationslinks:

Screenshot des Benutzerflows zum Entkoppeln von Code

Führen Sie die folgenden Schritte aus, um Ihre App auf das Entpacken des Installationslinks vorzubereiten:

  1. Legen Sie die Eigenschaft supportsAnonymizedPayloads im Manifestschema auf true fest.

  2. Legen Sie Ihre App so fest, dass die neue invoke Anforderung composeExtensions/anonymousQueryLinkverarbeitet wird.

    Beispiel für die neue invoke Anforderung:

    Screenshot der Deklaration

    Beispiel für die Anforderungsnutzlast invoke :

    {
   "name":"composeExtension/anonymousQueryLink",
   "type":"invoke",
   "timestamp":"2021-12-02T08:12:21.148Z",
   "localTimestamp":"2021-12-02T00:12:21.148-08:00",
   "id":"f:43d59e15-6114-bd53-08c3-b232aa648ec1",
   "channelId":"msteams",
   "serviceUrl":"https://smba.trafficmanager.net/amer/",
   "from":{
      "id":"redacted",
      "name":"redacted"
   },
   "conversation":{
      "isGroup":true,
      "conversationType":"groupChat",
      "tenantId":"redacted",
      "id":" redacted",
      "name":" redacted"
   },
   "recipient":{
      "id":"28:85fa138c-7654-4236-86eb-466160687029",
      "name":"test bot"
   },
   "entities":[
      {
         "locale":"en-US",
         "country":"US",
         "platform":"Mac",
         "timezone":"America/Los_Angeles",
         "type":"clientInfo"
      }
   ],
   "channelData":{
      "tenant":{
         "id":" redacted"
      },
      "source":{
         "name":"compose"
      }
   },
   "value":{
      "url":"https://test.test.com/test"
   },
   "locale":"en-US",
   "localTimezone":"America/Los_Angeles"
}

  3. Reagieren Sie auf die composeExtensions/anonymousQueryLink Nutzlast.

    1. Für Szenarien ohne Authentifizierung: Sie müssen eine Antwort mit dem type als result und einem Karte zurücksenden. Verwenden Sie die folgende Vorlage:

      {
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.teams.card.o365connector",
        "content": {
          "sections": [
            {
              "activityTitle": "[85069]: Create a cool app",
              "activityImage": "https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
              "name": "Assigned to:",
              "value": "[Larry Brown](mailto:larryb@example.com)"
                },
                {
              "name": "State:",
              "value": "Active"
                }
              ]
            }
           ]
         }
      }
    ]
  }
}

    2. Für Authentifizierungsszenarien: Sie müssen eine Antwort mit dem type als auth mit einer optionalen Vorauthentifizierungs-Karte in den Anlagen zurücksenden. Verwenden Sie die folgende Vorlage:

      {
   "composeExtension": {
      "type": "auth",
      "attachmentLayout": "list",
      "attachments": [
         {
           "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
           "type": "AdaptiveCard",
           "version": "1.5",
           "actions": [],
           "body": [
             {
               "type": "TextBlock",
               "size": "medium",
               "weight": "bolder",
               "text": "Zero-install test app"
            },
            {
               "type": "TextBlock",
               "text": "Link your account with this app for a full experience",
               "wrap": true
            }
           ]
         }
      ]
   }
}

  4. Preauth Karte (nur für die Authentifizierung): Erstellen Sie eine Karte Vorschau, um Ihre Links für Benutzer zu entpacken, die Ihre App nicht installiert haben. Sie können entweder eine vorkonfigurierte Karte erstellen oder relevante Platzhalterfelder für die Benutzer hinzufügen, die aktualisiert werden sollen. Benutzer können sich bereits vor der Installation über die App informieren.

    Sie können eine benutzerdefinierte Karte erstellen und relevante Felder hinzufügen. Die Benutzer können die erforderlichen Informationen gemäß den Feldern eingeben. Die folgende Abbildung veranschaulicht eine angepasste Karte Vorschau:

    Screenshot der angepassten Karte mit Feldern, die der Benutzer aktualisieren soll.

    Die folgende Abbildung veranschaulicht eine Standardvorschau Karte:

    Screenshot: Link zum Entpacken des Standardmäßigen Codevorschau-Karte.

    Hinweis

    Nachdem der Link in den Bereich zum Verfassen von Nachrichten eingefügt wurde, löst Teams den Link in einem Karte aus und fordert den Benutzer auf, sich bei der App anzumelden. Wenn sich der Benutzer nicht bei der App anmeldet, wird der Link nicht als Karte im Chat gepostet.

  5. Vorteile und Einschränkungen:

    Das Entpacken von Nullinstallationslinks hilft Ihnen, den Benutzern eine verbesserte Benutzererfahrung zu bieten, z. B.:

    • Entpacken Sie Vorschauen für Ihre Links, die Benutzer in Teams freigeben, noch bevor sie Ihre App installiert haben.
    • Erstellen Sie eine Willkommens-Karte für Ihre App, um eine Vorschau mit den Platzhalterfeldern anzuzeigen.

Wenn Sie die Entflechtung des Nullinstallationslinks testen, installieren Sie die App nicht als persönliche App. Laden Sie stattdessen die App in Teams hoch.

Hinweis

Führen Sie die Test-App nicht direkt über den Microsoft Visual Studio-Debugger aus.

Führen Sie die folgenden Schritte aus, um die Entfurlingung von Nullinstallationslinks zu testen:

  1. Melden Sie sich im Teams Admin Center an.

  2. Wählen Sie im linken Bereich Teams-Apps>Apps verwalten aus.

    Screenshot: Teams Admin Center und Abschnitt zum Hochladen benutzerdefinierter Apps in Teams.

  3. Wählen Sie + Neue App hochladen aus.

    Screenshot des Teams Admin Centers und des Hochladens von benutzerdefinierten Apps

  4. Wählen Sie Hochladen aus.

  5. Wählen Sie Öffnen aus, um die ZIP-Datei für Ihre Testanwendung hochzuladen.

  6. Nachdem der App-Upload erfolgreich war, wechseln Sie zuTeams-Apps>>, die für Ihre Organisation erstellt wurden.

    Screenshot: Teams-Client mit hochgeladener Teams-App der Organisation

  7. Sie können die composeExtensions/anonymousQueryLink Aufrufanforderung testen, indem Sie einen Haltepunkt in der Methode einrichten, die die anonymousQueryLink-Anforderung in Ihrer Anwendung implementiert.

Wenn ein Benutzer einen Link in einer Besprechung freigibt, löst die Teams-App den Link zu einer adaptiven Karte aus. Das Ergebnis der Linkentflechtung wird 30 Minuten lang in Teams zwischengespeichert. Sie können Ihre App aktualisieren, um eine Cacherichtlinie festzulegen und den Cache für die App zu entfernen. Diese Aktion hilft Ihnen, unterschiedliche Inhalte auf einer adaptiven Karte anzuzeigen, wenn der App-Link in einem anderen Kontext in Teams freigegeben wird.

Um den Cache für die Linkentfernung zu entfernen, aktualisieren Sie Ihren Bot mit wie typesetcachepolicy unter der suggestedActions -Eigenschaft. Teams speichert die Ergebnisse für die App-Links nicht mit zwischen "type": "setCachePolicy".

Das folgende JSON-Nutzlastbeispiel für suggestedActions die Eigenschaft:

"suggestedActions": {
            "actions": [
                {
                    "type": "setCachePolicy",
                    "value": "{\"type\":\"no-cache\"}"
                }
            ]
        },

Schrittweise Anleitung

Befolgen Sie die Schritt-für-Schritt-Anleitung, um Links in Teams mithilfe des Bots zu verbreiten.

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Keine Installationslink-Entflechtung. In diesem Beispiel wird gezeigt, wie sie Search-basierte Messagingerweiterung mit einer Konfigurationsseite verwenden. Dieses Beispiel bietet auch die Entflechtung von Nullinstallationslinks. View View Anzeigen

Siehe auch