Apertura de vínculos

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección Extensiones de mensaje - SDK v3 en la carpeta Recursos de la documentación.

El documento le guía sobre cómo agregar vínculos desplegadas al manifiesto de la aplicación mediante el Portal para desarrolladores y manualmente. Con la desplegada de vínculos, la aplicación puede registrarse para recibir una actividad de invocación cuando las direcciones URL con un dominio determinado se pegan en el área del mensaje de redacción. El invoke contiene la dirección URL completa que se pegó en el área de redacción del mensaje y puede responder con una tarjeta que el usuario puede abrir, proporcionando información o acciones adicionales. Esto funciona de forma similar a un comando de búsqueda con la dirección URL que actúa como término de búsqueda. Ahora puede agregar un vínculo que se desplegue a Microsoft Teams sin instalar la aplicación.

Nota:

• El resultado de la apertura del enlace se almacena en caché durante 30 minutos.
• La desplegamiento de vínculos admite la versión 1.3 y anteriores de las tarjetas adaptables.
• Los comandos de extensión de mensajería no son necesarios para la desplegamiento de vínculos. Sin embargo, debe haber al menos un comando en el manifiesto, ya que es una propiedad obligatoria en las extensiones de mensajería. Para obtener más información, consulte Redacción de extensiones.
• Para el cliente móvil, la desplegamiento de vínculos solo se admite para los vínculos que no requieren autenticación.

La siguiente imagen es un ejemplo de desplegamiento de vínculos en clientes móviles y de escritorio de Teams:

Escritorio

Cuando se pega un vínculo en el área de mensajes de redacción de Teams, el vínculo se desplegó en una tarjeta con los detalles del elemento de trabajo.

Móvil

Cuando se pega un vínculo de aplicación en el área de mensajes de redacción de Teams, el vínculo se desplegó en una tarjeta con los detalles del vínculo.

Consulte el siguiente vídeo para obtener más información sobre la desplegamiento de vínculos:

Agregue el enlace que se abre al manifiesto de su aplicación

Para agregar una apertura de enlace al manifiesto de la aplicación, agregue una nueva matriz de messageHandlers a la sección composeExtensions del JSON del manifiesto de la aplicación. Puede agregar la matriz con la ayuda del Portal para desarrolladores o manualmente. Las listas de dominios pueden incluir caracteres comodín, por ejemplo *.example.com , que coincidan exactamente con un segmento del dominio. Si necesita hacer coincidir a.b.example.com, use *.*.example.com.

Nota:

Asegúrese de que no agrega dominios que no están en el control, ya sea directamente o a través de caracteres comodín. Por ejemplo, yourapp.onmicrosoft.com es válido, pero *.onmicrosoft.com no es válido. Los dominios de nivel superior están prohibidos, por ejemplo, *.com, *.org.

Incorporación de la desurling de vínculos mediante el Portal para desarrolladores

1. Abra el Portal para desarrolladores en el cliente de Microsoft Teams y, a continuación, seleccione la pestaña Aplicaciones .

   

   Nota:

   Debe agregar la aplicación Portal para desarrolladores, si no la tiene agregada en el cliente de Teams.

   

2. Cargue el manifiesto de la aplicación.

   

3. Seleccione Extensión de mensajería en Características de la aplicación y elija Seleccionar un bot existente o Crear un bot nuevo.

   

   

4. Seleccione Guardar.

5. Seleccione Agregar un dominio en la sección Vínculos de vista previa y, a continuación, escriba dominio válido.

6. Seleccione Agregar. En la imagen siguiente se explica el proceso:

   

Agregar la apertura de vínculos manualmente

Nota:

Si la autenticación se agrega a través de Microsoft Entra ID, desplegar vínculos en Teams mediante bot.

En primer lugar, debe agregar la messageHandlers matriz al manifiesto de la aplicación y habilitar la extensión de mensaje para interactuar con vínculos. En el ejemplo siguiente se explica cómo agregar manualmente la apertura de vínculos:

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

Para obtener un ejemplo de manifiesto completo, consulte referencia de manifiesto.

Controlar la invocación de composeExtensions/queryLink

Después de agregar el dominio al manifiesto de la aplicación, debe actualizar el código del servicio web para controlar la invoke solicitud. Use la dirección URL recibida para buscar en el servicio y crear una respuesta de tarjeta. Si responde con más de una tarjeta, solo se usa la primera respuesta de la tarjeta.

Nota:

La respuesta de un bot debe incluir una preview propiedad .

Se admiten los siguientes tipos de tarjeta:

• Tarjeta adaptable
• Tarjeta miniatura
• Tarjeta de héroe
• Tarjeta del conector para Grupos de Microsoft 365

Para obtener más información, vea Invocación de tipo de acción.

El código siguiente es un ejemplo de la invoke solicitud:

JSON

A continuación se muestra un ejemplo del invoke enviado al bot:

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

Ejemplo de la respuesta:

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

C#

 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,
                    },       
                  },
              },
         }); 
   }

JavaScript

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

Micro funcionalidades para vínculos a sitios web

La manera más común de compartir contenido en Microsoft Teams es a través de vínculos. Para cualquier vínculo, Teams desplegó una vista previa del vínculo en una tarjeta adaptable con la información como imagen, título y descripción.

Puede mostrar las vistas previas completas de los vínculos sin instalar la aplicación en Microsoft Teams. Agregue los metadatos de schema.org al sitio web en el formato JSON-LD y use las plantillas de micro funcionalidad que coincidan con el producto. Teams usa estas plantillas para desenrollar las vistas previas enriquecidas de los vínculos en Microsoft Teams.

Habilitación de vistas previas de desplegadas enriquecidas de vínculos

Si ya ha agregado schema.org a su sitio web, puede ver la vista previa de unfurl enriquecida del vínculo pegándola en el área de redacción de mensajes de Teams.

Si no ha agregado schema.org a su sitio web, puede comprobar manualmente la experiencia de vista previa de unfurl enriquecida siguiendo estos pasos:

1. Agregue los metadatos de schema.org con el formato JSON-LD al sitio web.

2. En el sitio web, compruebe el atributo admitido @type y copie los metadatos bajo la etiqueta application/ld+jsonde script .

3. Abra el diseñador de tarjetas adaptables y cree un nuevo archivo.

4. En EL EDITOR DE DATOS DE EJEMPLO, pegue los metadatos json del sitio web.

   

5. Compruebe la plantilla de micro funcionalidad y agregue el código de plantilla en EL EDITOR DE CARGA ÚTIL DE TARJETA.

   

   Si es necesario, agregue nuevos atributos de la plantilla a los metadatos del sitio web en SAMPLE DATA EDITOR.

6. Para obtener una vista previa de la experiencia de desurl de la tarjeta adaptable, seleccione Modo de vista previa.

Para obtener más información, consulte Micro-funcionalidades para vínculos a sitios web.

Instalación cero para la desplegamiento de vínculos

La desplegamiento de vínculos de instalación cero le ayuda a desenrollar las vistas previas de los vínculos compartidos incluso antes de que un usuario detecte o instale la aplicación en Teams. Puede desatar tarjetas de forma anónima con una nueva invoke solicitud o crear una versión preliminar de tarjeta adaptable preautorizado para los usuarios antes de que instalen o autentiquen la aplicación.

La siguiente imagen proporciona un flujo secuencial para habilitar y usar el vínculo de instalación cero desplegándose:

Habilitar la desplegamiento del vínculo de instalación cero

Para preparar la aplicación para que no se desplegue el vínculo de instalación cero, siga estos pasos:

1. Establezca la propiedad supportsAnonymizedPayloads en true en el esquema de manifiesto.

2. Establezca la aplicación para controlar la nueva invoke solicitud composeExtensions/anonymousQueryLink.

   Ejemplo de la nueva invoke solicitud:

   

   Ejemplo de la carga útil de la invoke solicitud:

   {
      "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. Responda a la composeExtensions/anonymousQueryLink carga.

   1. Para escenarios que no son de autenticación: debe devolver una respuesta con el type como result y una tarjeta. Use la plantilla siguiente:

      {
        "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. Para escenarios de autenticación: debe devolver una respuesta con como typeauth con una tarjeta de autenticación previa opcional en los datos adjuntos. Use la plantilla siguiente:

      {
         "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. Tarjeta de autenticación previa (solo para autenticación): cree una vista previa de tarjeta para desenlazar los vínculos de los usuarios que no tengan instalada la aplicación. Puede crear una tarjeta con plantilla previa o agregar campos de marcador de posición pertinentes para que los usuarios actualicen. Los usuarios pueden obtener información sobre la aplicación incluso antes de instalarla.

   Puede crear una tarjeta personalizada y agregar campos pertinentes. Los usuarios pueden rellenar la información necesaria según los campos. En la imagen siguiente se muestra una vista previa de tarjeta personalizada:

   

   En la imagen siguiente se muestra una tarjeta de vista previa predeterminada:

   

   Nota:

   Después de pegar el vínculo en el área de redacción del mensaje, Teams desplegó el vínculo en una tarjeta y pide al usuario que inicie sesión en la aplicación. Si el usuario no inicia sesión en la aplicación, el vínculo no se publica como una tarjeta en el chat.

5. Ventajas y limitaciones:

   Ventajas

   La desplegamiento de vínculos de instalación cero le ayuda a proporcionar una experiencia mejorada a los usuarios, como:

   • Desurl previews for your links that users share in Teams even before they've installed your app.
   • Cree una tarjeta de bienvenida para que la aplicación muestre una vista previa con los campos de marcador de posición.

   Limitaciones

   Estas son las limitaciones:

   • El bot solo puede devolver una respuesta como result o auth como el valor de la type propiedad en respuesta a la composeExtensions/anonymousQueryLink solicitud de invocación. El usuario puede registrar un error para todos los demás tipos de respuesta, como silentAuth y config.

   • El bot no puede devolver una tarjeta adaptable con acciones universales en respuesta a la composeExtensions/anonymousQueryLink solicitud de invocación, ya sea como resultado o como una tarjeta de autenticación previa en la autenticación.

   • Si el bot selecciona devolver la "type": "auth" propiedad con una tarjeta de autenticación previa, Teams quita los botones de acción de la tarjeta y agrega un botón de acción de inicio de sesión para que los usuarios se autentiquen en la aplicación.

---

Cómo probar la desplegamiento del vínculo de instalación cero

Al probar la desplegada del vínculo de instalación cero, no instale la aplicación como una aplicación personal. En su lugar, cargue la aplicación en Teams.

Nota:

No ejecute la aplicación de prueba directamente desde el depurador de Microsoft Visual Studio.

Para probar la desplegación del vínculo de instalación cero, siga estos pasos:

1. Inicie la sesión en el Centro de administración de Teams.

2. En el panel izquierdo, seleccione Aplicaciones> de TeamsAdministrar aplicaciones.

   

3. Seleccione + Cargar nueva aplicación.

   

4. Seleccione Cargar.

5. Seleccione Abrir para cargar el archivo ZIP de la aplicación de prueba.

6. Una vez que la carga de la aplicación se realice correctamente, vaya aAplicaciones> de Teams>compiladas para su organización.

   

7. Puede probar la solicitud de composeExtensions/anonymousQueryLink invocación configurando un punto de interrupción en el método que implementa la solicitud anonymousQueryLink en la aplicación.

Eliminación de la caché de desplegada de vínculos

Cuando un usuario comparte un vínculo en una reunión, la aplicación teams desplegó el vínculo a una tarjeta adaptable. El resultado de la desplegada del vínculo se almacena en caché en Teams durante 30 minutos. Puede actualizar la aplicación para establecer una directiva de caché y quitar la caché de la aplicación. Esta acción le ayuda a mostrar contenido diferente en una tarjeta adaptable cuando el vínculo de la aplicación se comparte en un contexto diferente en Teams.

Para quitar la caché de desplegada de vínculos, actualice el bot con como typesetcachepolicy en la suggestedActions propiedad . Teams no almacena en caché los resultados de los vínculos de aplicación con "type": "setCachePolicy".

El siguiente ejemplo de carga JSON para la suggestedActions propiedad:

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

Guía paso a paso

Siga la guía paso a paso para abrir vínculos en Teams mediante bot.

Ejemplo de código

Ejemplo de nombre	Descripción	.NET	Node.js	Manifiesto
Se desplegó el vínculo de instalación cero.	En este ejemplo se muestra cómo usar la extensión de mensajería basada en Búsqueda con una página de configuración. En este ejemplo también se muestra la desplegamiento de vínculos de instalación cero.	View	View	Ver

Consulte también

• Extensiones de mensajes
• Tarjetas adaptables
• Vínculos de tabulación desplegadas y vista previa
• Controladores de actividad de bots