Verbreiten von Links

Artikel
05/01/2023

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. Mit der Verbreitung von Links kann Ihre App sich registrieren, um eine invoke-Aktivität zu empfangen, wenn URLs mit einer bestimmten Domäne in den Bereich zum Verfassen von Nachrichten 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.

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:

Desktop
Mobil

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:

Hinzufügen einer Verbreitung von Links zum App-Manifest

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. Domain-Auflistungen können Platzhalter enthalten, zum Beispiel *.example.com. Dies entspricht genau einem Segment der Domäne; 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.

Hinzufügen der Linkentfurlingung über das Entwicklerportal

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

Hinweis

Sie müssen die Entwicklerportal-App hinzufügen, wenn Sie sie nicht in Ihrem Teams-Client hinzugefügt haben.
Laden Sie Ihr App-Manifest.
Wählen Sie unter App-Features die Option Messaging-Erweiterung und dann entweder Vorhandenen Bot auswählen oder Neuen Bot erstellen aus.
Wählen Sie Speichern aus.
Wählen Sie im Abschnitt Vorschaulinks die Option Domäne hinzufügen aus, und geben Sie dann eine gültige Domäne ein.
Klicken Sie auf Hinzufügen. In der folgenden Abbildung wird der Prozess erläutert:

Verbreitung von Links manuell hinzufügen

Hinweis

Wenn die Authentifizierung über Azure AD 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.

Behandeln des `composeExtensions/queryLink`-Aufrufs

Nachdem Sie die Domäne zum App-Manifest hinzugefügt haben, müssen Sie Ihren Webdienstcode aktualisieren, um die Aufrufanforderung 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"
     }
   }

Es folgt ein 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 >>
       }
      ]
   }
}

 protected override Task<MessagingExtensionResponse> OnTeamsAppBasedLinkQueryAsync(ITurnContext<IInvokeActivity> turnContext, AppBasedLinkQuery query, CancellationToken cancellationToken)
  {
     AdaptiveCard adaptiveCard = new AdaptiveCard(new AdaptiveSchemaVersion(1, 3));
     adaptiveCard.Body.Add(new AdaptiveTextBlock()
       {
           Text = "Adaptive Card",
           Size = AdaptiveTextSize.ExtraLarge
       });
         adaptiveCard.Body.Add(new AdaptiveImage()
         {
           Url = new Uri("https://raw.githubusercontent.com/microsoft/botframework-sdk/master/icon.png")
         });
         var attachments = new MessagingExtensionAttachment()
         {
            Content = adaptiveCard,
            ContentType = AdaptiveCard.ContentType
         };
         return Task.FromResult(new MessagingExtensionResponse
         {
           ComposeExtension = new MessagingExtensionResult
             {
               AttachmentLayout = "list",
               Type = "result",
               Attachments = new List<MessagingExtensionAttachment>
                 {
                    new MessagingExtensionAttachment
                    {
                      Content = adaptiveCard,
                      ContentType = AdaptiveCard.ContentType,
                      Preview = attachments,
                    },       
                  },
              },
         }); 
   }


handleTeamsAppBasedLinkQuery(context, query) {
   const card = CardFactory.adaptiveCard({
   "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
   "type": "AdaptiveCard",
   "version": "1.3"
   });
const attachment = CardFactory.adaptiveCard(card);
attachment.preview = {
   content: {
     title: "Thumbnail Card",
     text: query.url,
     images: [
       {
          url: "https://raw.githubusercontent.com/microsoft/botframework-sdk/master/icon.png",
       },
     ],
   },
contentType: "application/vnd.microsoft.card.thumbnail",
}

Zero install for link unfurling (Nullinstallation für link unfurling)

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 hat. Sie können Karten anonym mit einer neuen Aufrufanforderung entfurlen 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:

Aktivieren der Entbündelung von Nullinstallationslinks

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

Legen Sie die Eigenschaft supportsAnonymizedPayloads im Manifestschema auf true fest.

Legen Sie Ihre App so fest, dass die neue Aufrufanforderung composeExtensions/anonymousQueryLinkverarbeitet wird.

Beispiel für die neue Aufrufanforderung:

Beispiel für die Nutzlast der Aufrufanforderung:

{
   "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"
}

Reagieren Sie auf die composeExtensions/anonymousQueryLink Nutzlast.

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"
                }
              ]
            }
           ]
         }
      }
    ]
  }
}

Für Authentifizierungsszenarien: Sie müssen eine Antwort mit dem type als auth mit einer optionalen Vorabauthentifizierung 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
            }
           ]
         }
      ]
   }
}

Pre-Auth-Karte (nur für 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. Die 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:

Die folgende Abbildung veranschaulicht eine Standardvorschau 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.
Vorteile und Einschränkungen:

Vorteile
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.

Im Folgenden sind die Einschränkungen aufgeführt:

Der Bot kann eine Antwort nur als result oder auth als Wert für die type -Eigenschaft als Antwort auf die composeExtensions/anonymousQueryLink Aufrufanforderung zurücksenden. Der Benutzer kann einen Fehler für alle anderen Antworttypen protokollieren, z. B. silentAuth und config.
Der Bot kann als Reaktion auf die composeExtensions/anonymousQueryLink Aufrufanforderung keine acv2-Karte zurücksenden, entweder als Ergebnis oder als Vorauthentifizierungs-Karte in der Authentifizierung.
Wenn der Bot den mit einer Vorauthentifizierungs-Karte zurücksenden "type": "auth" möchte, entfernt der Teams-Client alle Aktionsschaltflächen aus dem Karte und fügt eine Anmeldeaktionsschaltfläche hinzu, um Benutzer dazu zu bringen, sich bei Ihrer App zu authentifizieren.
Der Bot kann als Reaktion auf die composeExtensions/anonymousQueryLink Aufrufanforderung keine acv2-Karte zurücksenden, entweder als Ergebnis oder als Vorauthentifizierungs-Karte in der Authentifizierung.
Wenn der Bot den mit einer Vorauthentifizierungs-Karte zurücksenden "type": "auth" möchte, entfernt der Teams-Client alle Aktionsschaltflächen aus dem Karte und fügt eine Anmeldeaktionsschaltfläche hinzu, um Benutzer dazu zu bringen, sich bei Ihrer App zu authentifizieren.

Entfernen des Caches für die Linkentfernung

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. Dadurch können Sie unterschiedliche Inhalte auf einer adaptiven Karte anzeigen, 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 Die suchbasierte Messagingerweiterung mit einer Konfigurationsseite verwendet wird. Dieses Beispiel bietet auch die Entflechtung von Nullinstallationslinks.	View	View	Anzeigen

Verbreiten von Links

Hinzufügen einer Verbreitung von Links zum App-Manifest

Hinzufügen der Linkentfurlingung über das Entwicklerportal

Verbreitung von Links manuell hinzufügen

Behandeln des `composeExtensions/queryLink`-Aufrufs

Zero install for link unfurling (Nullinstallation für link unfurling)

Aktivieren der Entbündelung von Nullinstallationslinks

Entfernen des Caches für die Linkentfernung

Schrittweise Anleitung

Codebeispiel

Siehe auch

Zusätzliche Ressourcen

Zusätzliche Ressourcen

Verbreiten von Links

Hinzufügen einer Verbreitung von Links zum App-Manifest

Hinzufügen der Linkentfurlingung über das Entwicklerportal

Verbreitung von Links manuell hinzufügen

Behandeln des composeExtensions/queryLink-Aufrufs

Zero install for link unfurling (Nullinstallation für link unfurling)

Aktivieren der Entbündelung von Nullinstallationslinks

Entfernen des Caches für die Linkentfernung

Schrittweise Anleitung

Codebeispiel

Siehe auch

Zusätzliche Ressourcen

Zusätzliche Ressourcen

Behandeln des `composeExtensions/queryLink`-Aufrufs