Crear vínculos profundos

  • Artigo
  • 19 minutos de lectura

Los vínculos profundos son un mecanismo de navegación que puede usar para conectar a los usuarios con información y características dentro de Teams y las aplicaciones de Teams. Los escenarios en los que la creación de vínculos profundos es útil son los siguientes:

  • Llevar al usuario al contenido dentro de una de las pestañas de la aplicación. Por ejemplo, la aplicación puede tener un bot que envía mensajes que notifican al usuario de una actividad importante. Cuando el usuario pulsa en la notificación, el vínculo profundo navega a la pestaña para que el usuario pueda ver más detalles sobre la actividad.
  • La aplicación automatiza o simplifica determinadas tareas de usuario, como crear un chat o programar una reunión, rellenando previamente los vínculos profundos con los parámetros necesarios. Evita la necesidad de que los usuarios escriban manualmente la información.

El SDK de cliente de JavaScript de Microsoft Teams (TeamsJS) simplifica el proceso de navegación. En muchos escenarios, como cuando se navega a contenido e información dentro de la pestaña o se iniciar un cuadro de diálogo de chat, el SDK proporciona API tipeadas que proporcionan una experiencia mejorada y pueden reemplazar el uso de vínculos profundos. Estas API se recomiendan para las aplicaciones de Teams que se pueden ejecutar en otros hosts (Outlook, Office), ya que también proporcionan una manera de comprobar que ese host admite la funcionalidad que se usa. En las secciones siguientes se muestra información sobre la vinculación profunda, pero también se resalta cómo han cambiado los escenarios que solían requerirla con la versión v2 de TeamsJS.

Nota

En este tema se refleja la versión 2.0.x del SDK de cliente JavaScript de Microsoft Teams. Si usa una versión anterior, consulte la introducción al SDK de JS de Teams para obtener instrucciones sobre las diferencias entre la versión más reciente de TeamsJS y las versiones anteriores.

Nota

El comportamiento de los vínculos profundos depende de una serie de factores. En la siguiente lista se describe el comportamiento de los vínculos profundos en entidades de Teams.

Pestaña:
✔ Navega directamente a la dirección URL del vínculo profundo.

Bot:
✔ Vínculo profundo en el cuerpo de la tarjeta: se abre primero en el explorador.
✔ Vínculo profundo agregado a la acción OpenURL en la tarjeta adaptable: navega directamente a la dirección URL del vínculo profundo.
✔ Texto de markdown de hipervínculo en la tarjeta: se abre primero en el explorador.

Chat:
✔ Markdown de hipervínculo de mensaje de texto: navega directamente a la dirección URL del vínculo profundo.
✔ Vínculo pegado en la conversación de chat general: navega directamente a la dirección URL del vínculo profundo.

El comportamiento de navegación de una aplicación de Teams extendida en Microsoft 365 (Outlook/Office) depende de dos factores:

  • Destino al que apunta el vínculo profundo.
  • Host en el que se ejecuta la aplicación de Teams.

Si la aplicación Teams se ejecuta dentro del host donde se dirige el vínculo profundo, la aplicación se abrirá directamente dentro del host. Sin embargo, si la aplicación de Teams se ejecuta en un host diferente del destino del vínculo profundo, la aplicación se abrirá primero en el explorador.

Puede crear vínculos profundos a entidades en las aplicaciones de Teams. Se usa para crear vínculos que naveguen al contenido y a la información dentro de la pestaña. Por ejemplo, si la pestaña contiene una lista de tareas, los miembros del equipo pueden crear y compartir vínculos a tareas individuales. Al seleccionar el vínculo, navega a la pestaña que se centra en el elemento específico.

Para implementar, agregue una acción copiar vínculo a cada elemento, de la manera que mejor se adapte a su interfaz de usuario. Cuando el usuario realiza esta acción, se llama a pages.shareDeepLink() para mostrar un cuadro de diálogo que contiene un vínculo que el usuario puede copiar en el portapapeles. Cuando realice esta llamada, pase un id. para el elemento. Se devuelve en contexto cuando se sigue el vínculo y se vuelve a cargar la pestaña.

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

Tendrá que reemplazar los campos por la información adecuada:

  • subPageId: identificador único del elemento de la pestaña al que está vinculando en profundidad.
  • subPageLabel: etiqueta del elemento que se va a usar para mostrar el vínculo profundo.
  • subPageWebUrl: dirección URL de reserva que se usará si el cliente no puede representar la página.

Para obtener más información, consulte pages.shareDeepLink().

Como alternativa, también puede generar vínculos profundos mediante programación, con el formato especificado más adelante en este artículo. Puede usar vínculos profundos en mensajes de bot y conector que informan a los usuarios sobre los cambios en la pestaña o en los elementos que contiene.

Nota

Este vínculo profundo es diferente de los vínculos proporcionados por el elemento de menú Copiar vínculo a la pestaña, que solo genera un vínculo profundo que apunta a esta pestaña.

Importante

Actualmente, shareDeepLink no funciona en plataformas móviles.

Al navegar a un vínculo profundo, Microsoft Teams simplemente navega a la pestaña y proporciona un mecanismo a través de la biblioteca JavaScript de Teams para recuperar el identificador de la subentidad si existe.

La llamada app.getContext() (microsoftTeams.getContext()) en TeamsJS v1) devuelve una promesa que se resolverá con el contexto que incluye la propiedad subPageId (subEntityId para TeamsJS v1) si la pestaña se navega a través de un vínculo profundo. Para obtener más información, vea la interfaz PageInfo.

Aunque se recomienda usar shareDeepLink() para generar un vínculo profundo a la pestaña, también es posible crear uno manualmente.

Nota

  • Las pestañas personales tienen un ámbito personal, mientras que las pestañas de canal y grupo usan ámbitos team o group. Los dos tipos de pestaña tienen una sintaxis ligeramente diferente, ya que solo la pestaña configurable tiene una propiedad channel asociada a su objeto de contexto. Para obtener más información sobre los ámbitos de pestaña, vea la referencia del manifiesto.
  • Los vínculos profundos solo funcionan correctamente si la pestaña se configuró mediante la biblioteca v0.4 o posterior y por ello tiene un identificador de entidad. Los vínculos profundos a pestañas sin identificadores de entidad siguen navegando a la pestaña, pero no pueden proporcionar el identificador de subentidad a la pestaña.

Use el formato siguiente para un vínculo profundo que puede usar en un bot, conector o tarjeta de extensión de mensajería:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>

Nota

Si el bot envía un mensaje que contiene un TextBlock con un vínculo profundo, se abre una nueva pestaña del explorador cuando el usuario selecciona el vínculo. Esto sucede en Chrome y en la aplicación de escritorio de Teams, ejecutados en Linux. Si el bot envía la misma dirección URL de vínculo profundo a un Action.OpenUrl, la pestaña Teams se abre en la pestaña actual del explorador cuando el usuario selecciona el vínculo. No se abre una nueva pestaña del explorador.

Los parámetros de consulta son:

Nombre del parámetro Descripción Ejemplo
appId  Identificador del Centro de administración de Teams. fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  Id. del elemento en la pestaña, que proporcionó al configurar la pestaña. Al generar una dirección URL para la vinculación en profundidad, siga usando entityID como nombre de parámetro en la dirección URL. Al configurar la pestaña, el objeto de contexto hace referencia al entityID como {page.id}. Lista de tareas123
entityWebUrl o subEntityWebUrl  Un campo opcional con una dirección URL de reserva que se usará si el cliente no admite la representación de la pestaña. https://tasklist.example.com/123 o https://tasklist.example.com/list123/task456
entityLabel o subEntityLabel  Etiqueta del elemento de la pestaña que se va a usar al mostrar el vínculo profundo. Lista de tareas 123 o "Tarea 456
context.subEntityId  Identificador del elemento dentro de la pestaña. Al generar una dirección URL para la vinculación en profundidad, siga usando subEntityId como nombre de parámetro en la dirección URL. Al configurar la pestaña, el objeto de contexto hace referencia a subEntityID como subPageID. Tarea 456
context.channelId  Id. de canal de Microsoft Teams que está disponible en la pestaña contexto. Esta propiedad solo está disponible en pestañas configurables con un ámbito de equipo. No está disponible en pestañas estáticas, que tienen un ámbito personal. 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
chatId  ChatId que está disponible desde el contexto de la pestaña para el chat de grupo y de reunión 17:b42de192376346a7906a7dd5cb84b673@thread.v2
contextType  Chat es el único contextType admitido para reuniones chat

Ejemplos:

  • Vínculo a una pestaña estática (personal):

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123

  • Vínculo a un elemento de tarea dentro de la pestaña estática (personal):

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}

  • Vínculo a una pestaña configurable:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • Vínculo a un elemento de tarea en la pestaña configurable:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • Vínculo a una aplicación de pestaña agregada a una reunión o chat grupal:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

Importante

Asegúrese de que todos los parámetros de consulta estén correctamente codificados por URI. Debe seguir los ejemplos anteriores con el último ejemplo:

var encodedWebUrl = encodeURI('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURI('{"subEntityId": "task456"}');
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

Puede navegar hasta el contenido de Teams desde la pestaña mediante TeamsJS o vínculos profundos. Esto es útil si la pestaña necesita vincular a otro contenido de Teams, como un canal, un mensaje, otra pestaña o incluso para abrir un cuadro de diálogo de programación. Anteriormente, la navegación podría haber requerido un vínculo profundo, pero ahora se puede realizar en muchas instancias mediante el SDK. En las secciones siguientes se muestran ambos métodos, pero siempre que sea posible se recomienda el uso de las funcionalidades tipeadas del SDK.

Una de las ventajas de usar TeamsJS, especialmente para las aplicaciones Teams que se pueden ejecutar en otros hosts (Outlook y Office), es que es posible comprobar que el host admite la funcionalidad que intenta usar. Para comprobar la compatibilidad de un host con una funcionalidad, puede usar la función isSupported() asociada al espacio de nombres de la API. La versión preliminar v2 del SDK de TeamsJS organiza las API en funcionalidades por medio de espacios de nombres. Por ejemplo, antes de usar una API en el espacio de nombres pages, puede comprobar el valor booleano devuelto desde pages.isSupported() y realizar la acción adecuada en el contexto de la interfaz de usuario de aplicaciones y aplicaciones.

Para obtener información adicional sobre las funcionalidades y las API en TeamsJS, consulte Creación de pestañas y otras experiencias hospedadas con el SDK de cliente de JavaScript de Microsoft Teams.

Es posible navegar dentro de una aplicación mediante TeamsJS. En el código siguiente se muestra cómo navegar a una entidad específica dentro de la aplicación de Teams.

Puede desencadenar una navegación desde la pestaña mediante la función pages.navigateToApp() como se muestra en el código siguiente:

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

Para obtener más información sobre el uso de la funcionalidad páginas, consulte pages.navigateToApp() y el espacio de nombres páginas para ver otras opciones de navegación. Si es necesario, también es posible abrir directamente un vínculo profundo mediante la función app.openLink().

Abrir un cuadro de diálogo

Nota

Para abrir el cuadro de diálogo de programación en Teams, los desarrolladores deben seguir usando el método original basado en la dirección URL de vínculo profundo, ya que Teams aún no admite la funcionalidad de calendario.

Para obtener más información sobre cómo trabajar con el calendario, consulte el espacio de nombres del calendario en la documentación de referencia de la API.

// Open a scheduling dialog from your tab
if(calendar.isSupported()) {
   const calendarPromise = calendar.composeMeeting({
      attendees: ["joe@contoso.com", "bob@contoso.com"],
      content: "test content",
      endTime: "2018-10-24T10:30:00-07:00",
      startTime: "2018-10-24T10:00:00-07:00",
      subject: "test subject"});
   calendarPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

De forma alternativa, puede crear manualmente vínculos profundos al diálogo de programación integrado de Teams.

Aunque se recomienda usar las API tipadas de TeamsJS, es posible crear manualmente vínculos profundos al cuadro de diálogo de programación integrado Teams. Use el formato siguiente para un vínculo profundo que puede usar en un bot, conector o tarjeta de extensión de mensajería: https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

Ejemplo: https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=test%3Acontent

Nota

Los parámetros de búsqueda no admiten la señal + en lugar de espacios en blanco (``). Asegúrese de que el código de codificación uri devuelve %20 para los espacios, por ejemplo, ?subject=test%20subject es correcto, pero ?subject=test+subject es incorrecto.

Los parámetros de consulta son:

  • attendees: lista opcional separada por comas de identificadores de usuario que representan a los asistentes a la reunión. El usuario que realiza la acción es el organizador de la reunión. Actualmente, el campo Id. de usuario solo admite el UserPrincipalName de Azure AD, normalmente una dirección de correo electrónico.
  • startTime: la hora de inicio opcional del evento. Debe tener formato ISO 8601 largo, por ejemplo, 2018-03-12T23:55:25+02:00.
  • endTime: la hora de finalización opcional del evento, también en formato ISO 8601.
  • subject: un campo opcional para el asunto de la reunión.
  • content: un campo opcional para el campo de detalles de la reunión.

Nota

En estos momentos, no se puede especificar la ubicación. Debe especificar la diferencia horaria con UTC, que significa zonas horarias al generar las horas de inicio y finalización.

Para usar este vínculo profundo con el bot, puede especificarlo como destino de la dirección URL en el botón de la tarjeta o pulsar la acción a través del tipo de acción openUrl.

Abrir un cuadro de diálogo de instalación de aplicaciones

Puede abrir un cuadro de diálogo de instalación de la aplicación desde la aplicación de Teams, como se muestra en el código siguiente.

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: <appId>});
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Para obtener más información sobre el cuadro de diálogo de instalación, consulte la función appInstallDialog.openAppInstallDialog() en la documentación de referencia de la API.

Puede crear vínculos profundos a chats privados entre usuarios especificando el conjunto de participantes. Si no existe un chat con los participantes especificados, el vínculo lleva al usuario a un nuevo chat vacío. Los chats nuevos se crean en estado de borrador hasta que el usuario envía el primer mensaje. De lo contrario, puede especificar el nombre del chat si aún no existe, junto con el texto que se debe insertar en el cuadro de redacción del usuario. Puede considerar esta característica como un acceso directo para que el usuario realice la acción manual de ir al chat o crearlo y, después, escribir el mensaje.

Como ejemplo de caso de uso, si va a devolver un perfil de usuario de Office 365 desde el bot como una tarjeta, este vínculo profundo puede permitir que el usuario chatee fácilmente con esa persona. En el ejemplo siguiente se muestra cómo abrir un mensaje de chat a un grupo de participantes con un mensaje inicial.

if(chat.isSupported()) {
    const chatPromise = chat.openGroupChat({ users: ["joe@contoso.com","bob@contoso.com"], topic: "Prep For Meeting Tomorrow", message: "Hi folks kicking off chat about our meeting tomorrow"});
    chatPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Aunque se recomienda el uso de las API tipeadas, también puede usar el siguiente formato para un vínculo profundo creado manualmente que puede usar en un bot, conector o tarjeta de extensión de mensaje:

https://teams.microsoft.com/l/chat/0/0?users=<user1>,<user2>,...&topicName=<chat name>&message=<precanned text>

Ejemplo: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

Los parámetros de consulta son:

  • users: lista separada por comas de identificadores de usuario que representan a los participantes del chat. El usuario que realiza la acción siempre se incluye como participante. Actualmente, el campo Id. de usuario admite el UserPrincipalName de Microsoft Azure Active Directory (Azure AD), como solo una dirección de correo electrónico.
  • topicName: un campo opcional para el nombre para mostrar del chat, si un chat tiene tres o más usuarios. Si no se especifica este campo, el nombre para mostrar del chat se basa en los nombres de los participantes.
  • message: un campo opcional para el texto del mensaje que quiere insertar en el cuadro de redacción del usuario actual mientras el chat está en un estado de borrador.

Para usar este vínculo profundo con el bot, puede especificarlo como destino de la dirección URL en el botón de la tarjeta o pulsar la acción a través del tipo de acción openUrl.

Use este formato de vínculo profundo para navegar a una conversación determinada dentro de la conversación del canal:

https://teams.microsoft.com/l/message/<channelId>/<parentMessageId>?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=<parentMessageId>&teamName=<teamName>&channelName=<channelName>&createdTime=<createdTime>

Ejemplo: https://teams.microsoft.com/l/message/<channelId>/1648741500652?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=1648741500652&teamName=<teamName>&channelName=<channelName>&createdTime=1648741500652

Los parámetros de consulta son:

  • channelId: id. de canal de la conversación. Por ejemplo, 19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2.
  • tenantId: identificador de inquilino como 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • groupId: id. de grupo del archivo. Por ejemplo, 3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: id. de mensaje primario de la conversación.
  • teamName: nombre del equipo.
  • channelName: nombre del canal del equipo.

Nota

Puede ver channelId y groupId en la dirección URL del canal.

El siguiente formato de vínculo profundo se puede usar en un bot, conector o tarjeta de extensión de mensajería:

https://teams.microsoft.com/l/file/<fileId>?tenantId=<tenantId>&fileType=<fileType>&objectURL=<objectURL>&baseUrl=<baseURL>&serviceName=<Name>&threadId=<threadId>&groupId=<groupId>

Los parámetros de consulta son:

  • fileId: Identificador de archivo único de Sharepoint Online, también conocido como sourcedoc. Por ejemplo, 1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: identificador de inquilino como 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • fileType: tipo de archivo admitido, como docx, pptx, xlsx y pdf.
  • objectUrl: dirección URL del objeto del archivo. El formato es https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. Por ejemplo, https://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl: dirección URL base del archivo. El formato es https://{tenantName}.sharepoint.com/sites/{TeamName}. Por ejemplo, https://microsoft.sharepoint.com/teams.
  • serviceName: nombre del servicio, id. de aplicación. Por ejemplo, teams.
  • threadId: threadId es el identificador del equipo donde se almacena el archivo. Es opcional y no se puede establecer para los archivos almacenados en la carpeta de OneDrive de un usuario. threadId - 19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype.
  • groupId: id. de grupo del archivo. Por ejemplo, ae063b79-5315-4ddb-ba70-27328ba6c31e.

Nota

Puede ver threadId y groupId en la dirección URL del canal.

El siguiente formato de vínculo profundo se usa en un bot, conector o tarjeta de extensión de mensajería:

https://teams.microsoft.com/l/file/<fileId>?tenantId=<tenantId>&fileType=<fileType>&objectURL=<objectURL>&baseUrl=<baseURL>&serviceName=<Name>&threadId=<threadId>&groupId=<groupId>

En el siguiente formato de ejemplo se muestra el vínculo profundo a los archivos:

https://teams.microsoft.com/l/file/5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80?tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb&fileType=pptx&objectUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform%2FShared%20Documents%2FFC7-%20Bot%20and%20Action%20Infra%2FKaizala%20Actions%20in%20Adaptive%20Cards%20-%20Deck.pptx&baseUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform&serviceName=teams&threadId=19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype&groupId=ae063b79-5315-4ddb-ba70-27328ba6c31e

Serialización de este objeto

{
fileId: "5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80",
tenantId: "0d9b645f-597b-41f0-a2a3-ef103fbd91bb",
filetype: = "pptx",
objectUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform/Shared Documents/FC7- Bot and Action Infra/Kaizala Actions in Adaptive Cards - Deck.pptx",
baseUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform",
serviceName: "teams",
threadId: = "19:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype",
groupId: "ae063b79-5315-4ddb-ba70-27328ba6c31e"
}

Vinculación profunda a una aplicación

Cree vínculos profundos para la aplicación después de que la aplicación aparezca en la tienda de Teams. Para crear un vínculo para iniciar Teams, anexe el identificador de aplicación a la siguiente dirección URL: https://teams.microsoft.com/l/app/<your-app-id>. Aparece un cuadro de diálogo para instalar la aplicación.

Vinculación profunda para pestañas de SharePoint Framework

El siguiente formato de vínculo profundo se puede usar en un bot, conector o tarjeta de extensión de mensajería: https://teams.microsoft.com/l/entity/<AppId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>

Nota

Cuando un bot envía un mensaje de TextBlock con un vínculo profundo, se abre una nueva pestaña del explorador cuando los usuarios seleccionan el vínculo. Esto sucede en Chrome y en la aplicación de escritorio de Microsoft Teams, ejecutados en Linux. Si el bot envía la misma dirección URL de vínculo profundo a un Action.OpenUrl, la pestaña Teams se abre en el explorador actual cuando el usuario selecciona el vínculo. No se abre una nueva pestaña del explorador.

Los parámetros de consulta son:

  • appID: el identificador del manifiesto, por ejemplo, fe4a8eba-2a31-4737-8e33-e5fae6fee194.

  • entityID: el identificador de elemento que proporcionó al configurar la pestaña. Por ejemplo, tasklist123.

  • entityWebUrl: campo opcional con una dirección URL de reserva que se usará si el cliente no admite la representación de la pestaña (https://tasklist.example.com/123 o https://tasklist.example.com/list123/task456).

  • entityName: etiqueta del elemento de la pestaña que se usará al mostrar el vínculo profundo, Lista de tareas 123 o Tarea 456.

Ejemplo: https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

Puede crear vínculos profundos para invocar solo audio o llamadas de audio y vídeo a un único usuario o grupo de usuarios, especificando el tipo de llamada y los participantes. Antes de realizar la llamada, el cliente de Teams solicita una confirmación para realizar la llamada. Si hay una llamada grupal, puede llamar a un conjunto de usuarios de VoIP y a un conjunto de usuarios de RTC en la misma invocación de vínculo profundo.

En el caso de una videollamada, el cliente pedirá confirmación y activará el vídeo del autor de la llamada para la llamada. El receptor de la llamada tiene la opción de responder solo a través de audio o con audio y vídeo, a través de la ventana de notificación de llamadas de Teams.

Nota

Este vínculo profundo no se puede usar para invocar una reunión.

En el código siguiente se muestra cómo usar el SDK de TeamsJS para iniciar una llamada:

if(call.isSupported()) {
    const callPromise = call.startCall({ targets: ["joe@contoso.com","bob@contoso.com","4:9876543210"], requestedModalities: [call.CallModalities.Audio], source: "demoApp"});
    callPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Aunque se recomienda el uso de las API tipeadas de TeamsJS, también puede usar un vínculo profundo creado manualmente para iniciar una llamada.

Vínculo profundo Formato Ejemplo
Realizar una llamada de audio https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com
Realizar una llamada de audio y vídeo https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>&withVideo=true https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com&withVideo=true
Realizar una llamada de audio y vídeo con un origen de parámetros opcional https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>&withVideo=true&source=demoApp https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com&withVideo=true&source=demoApp
Realizar una llamada de audio y vídeo a una combinación de usuarios de VoIP y RTC https://teams.microsoft.com/l/call/0/0?users=<user1>,4:<phonenumber> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com,4:9876543210

Estos son los parámetros de consulta:

  • users: lista separada por comas de identificadores de usuario que representan a los participantes de la llamada. Actualmente, el campo Id. de usuario admite el UserPrincipalName de Azure AD, normalmente una dirección de correo electrónico, o en el caso de una llamada RTC, admite un pstn mri 4:<número de teléfono>.
  • withVideo: este es un parámetro opcional que puede usar para realizar una videollamada. Al establecer este parámetro, solo se activará la cámara del autor de la llamada. El receptor de la llamada tiene la opción de responder a través de llamada de audio o de audio y vídeo a través de la ventana de notificación de llamadas de Teams.
  • Source: este es un parámetro opcional, que informa sobre el origen del vínculo profundo.

Ejemplo de código

Ejemplo de nombre Descripción C# Node.js
Vínculo profundo que consume el id. de subentidad Aplicación de ejemplo de Teams para mostrar el vínculo profundo del chat del bot a la pestaña que consume el identificador de subentidad. View Ver

Consulte también