Creación de conectores para Grupos de Microsoft 365

Importante

Los conectores de Microsoft 365 (anteriormente denominados conectores de Office 365) están a punto de desuso y la creación de nuevos conectores de Microsoft 365 pronto se bloqueará. Para obtener más información sobre la programación y cómo la aplicación Flujos de trabajo proporciona una experiencia más flexible y segura, consulte Retirada de conectores de Microsoft 365 en Microsoft Teams.

¿Cómo puede crear un webhook en Teams?

• Para publicar automáticamente en un chat o canal cuando se recibe una solicitud de webhook, use las plantillas de flujo de trabajo predefinidas o cree un flujo de trabajo desde cero mediante el desencadenador Cuando se recibe una solicitud de webhook de Teams . Para obtener más información, vea Publicar un flujo de trabajo cuando se recibe una solicitud de webhook en Microsoft Teams.

• Para obtener más información sobre el desencadenador Cuando se recibe una solicitud de webhook de Teams , consulte Microsoft Teams - Webhook.

Si ya ha creado conectores de Office 365:

• Creación de un conector de Power Automate: Power Automate mejora las aplicaciones de flujos de trabajo ampliamente utilizadas en Teams. Es el enfoque escalable y seguro para transmitir datos mediante programación dentro y fuera de Teams. Si adopta este método, puede crear plantillas de flujo de trabajo para publicar alertas desde el producto en canales de Teams. Este enfoque simplifica la adopción por parte del usuario del nuevo método. Para obtener más información, consulte Power Automate para desarrolladores empresariales, ISV y asociados.

• Actualizar la aplicación de Teams: puede mejorar la aplicación actual de Teams. Por ejemplo, puede permitir que los usuarios configuren mensajes proactivos basados en eventos de desencadenador dentro del sistema. Para obtener más información, consulte cómo los bots pueden publicar en canales a través de mensajes proactivos.

Problemas conocidos

• La aplicación Flujos de trabajo no puede publicar en canales privados como un bot de flujo. Sin embargo, puede publicar en nombre de un usuario.
• Los flujos de trabajo solo admiten tarjetas adaptables. No admite el formato de tarjeta de mensaje anterior que usan los conectores de Office 365. La compatibilidad con el uso del formato de tarjeta de mensaje en flujos de trabajo está disponible a partir de mediados de octubre. Para obtener más información, vea cómo convertir el formato de tarjeta de mensaje del conector a tarjeta adaptable.
• Los flujos de trabajo no ofrecen conectores de terceros, como DataDog y Jenkins.
• Los flujos de trabajo solo se pueden crear en el entorno predeterminado.

Limitaciones

Los flujos de trabajo solo están vinculados a usuarios específicos (denominados propietarios del flujo de trabajo) y no a un equipo o canal de Teams. Los flujos de trabajo pueden convertirse en flujos huérfanos en ausencia de un propietario si no se asigna ningún copropietario. Para mantener la continuidad en el proceso empresarial automatizado por el flujo, los administradores pueden agregar uno o varios copropietarios y concederles control total sobre el flujo de trabajo. También pueden agregar autenticación para las conexiones, si las hubiera, y habilitar el flujo si se ha deshabilitado. Para obtener más información, consulte Administración de flujos huérfanos.

Con las aplicaciones de Microsoft Teams, puede agregar el conector existente para Grupos de Microsoft 365 o crear uno nuevo en Teams. Para obtener más información, vea compilación de su propio conector.

Vea el siguiente vídeo para obtener información sobre cómo crear conectores para Grupos de Microsoft 365:

Nota:

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

Agregar un conector a la aplicación de Teams

Puede crear un paquete y publicar el conector como parte del envío de AppSource. Puede distribuir el conector registrado como parte del paquete de la aplicación de Teams. Para obtener información sobre los puntos de entrada de la aplicación de Teams, vea capacidades. También puede proporcionar el paquete directamente a los usuarios para cargarlo en Teams.

Para distribuir el conector, regístrelo en el Conectores Panel de control para desarrolladores.

Para que un conector funcione solo en Teams, siga las instrucciones para enviar el conector en la publicación de la aplicación en el artículo de Microsoft Teams Store . De lo contrario, un conector registrado funciona en todos los productos de Microsoft 365 que admiten aplicaciones, incluidos Outlook y Teams.

Importante

El conector se registra después de seleccionar Guardar en el Panel del desarrollador de conectores. Si desea publicar el conector en AppSource, siga las instrucciones de publicar la aplicación de Microsoft Teams en AppSource. Si no desea publicar la aplicación en AppSource, distribúyala directamente a la organización. Después de publicar conectores para su organización, no es necesario realizar ninguna otra acción en el panel del conector.

Cree la base de datos de configuración:

Los usuarios pueden completar toda la experiencia de configuración del conector sin tener que salir del cliente de Teams. Para obtener la experiencia, Teams puede insertar la página de configuración directamente en un iframe. La secuencia de operaciones es la siguiente:

1. El usuario selecciona su conector para iniciar el proceso de configuración.

2. El usuario interactúa con la experiencia web para completar la configuración.

3. El usuario selecciona Guardar, que desencadena una devolución de llamada en el código.

   Nota:

   • El código puede procesar el evento de guardado recuperando la configuración del webhook. El código almacena el webhook para publicar eventos más adelante.
   • La experiencia de configuración se carga en línea en Teams.

Puede reutilizar la experiencia de configuración web existente o crear una versión independiente para hospedarla específicamente en Teams. El código debe incluir la biblioteca TeamsJS. Esto proporciona a su código acceso a las API para realizar operaciones comunes, como obtener el contexto de usuario, canal o equipo, e iniciar flujos de autenticación.

Para integrar la experiencia de la configuración:

Nota:

A partir de la biblioteca TeamsJS v.2.0.0, las API del espacio de nombres de configuración han quedado en desuso en favor de API equivalentes en el espacio de nombres pages , incluidas pages.getConfig() y otras API del pages.config subespacial. Para obtener más información, consulte Novedades de TeamsJS versión 2.x.x.

1. Inicialice TeamsJS llamando a app.initialize().

2. Llame a pages.config.setValidityState(true) para habilitar Guardar.

   Nota:

   Debe llamar a microsoftTeams.pages.config.setValidityState(true) como respuesta a la selección del usuario o a la actualización de campos.

3. Registre microsoftTeams.pages.config.registerOnSaveHandler() el controlador de eventos, al que se llama cuando el usuario selecciona Guardar.

4. Llame a microsoftTeams.pages.config.setConfig() para guardar la configuración del conector. La configuración guardada también se muestra en el cuadro de diálogo de configuración si el usuario intenta actualizar una configuración existente para el conector.

5. Llame a microsoftTeams.pages.getConfig() para capturar las propiedades de webhook, incluida la dirección URL.

   Nota:

   Debe llamar a microsoftTeams.pages.getConfig() cuando la página se cargue por primera vez en caso de reconfiguración.

6. Registre microsoftTeams.pages.config.registerOnRemoveHandler() controlador de eventos, al que se llama cuando el usuario quita el conector.

Este evento ofrece al servicio la oportunidad de realizar cualquier acción de limpieza.

El código siguiente proporciona un código HTML de ejemplo para crear una página de configuración del conector sin el servicio de atención al cliente y el soporte técnico:

<h2>Send notifications when tasks are:</h2>
<div class="col-md-8">
    <section id="configSection">
        <form id="configForm">
            <input type="radio" name="notificationType" value="Create" onclick="onClick()"> Created
            <br>
            <br>
            <input type="radio" name="notificationType" value="Update" onclick="onClick()"> Updated
        </form>
    </section>
</div>

<script src="https://res.cdn.office.net/teams-js/2.2.0/js/MicrosoftTeams.min.js" integrity="sha384-Q2Z9S56exI6Oz/ThvYaV0SUn8j4HwS8BveGPmuwLXe4CvCUEGlL80qSzHMnvGqee" crossorigin="anonymous"></script>
<script src="/Scripts/jquery-1.10.2.js"></script>

<script>
        function onClick() {
            pages.config.setValidityState(true);
        }

        await microsoftTeams.app.initialize();
        pages.config.registerOnSaveHandler(function (saveEvent) {
            var radios = document.getElementsByName('notificationType');

            var eventType = '';
            if (radios[0].checked) {
                eventType = radios[0].value;
            } else {
                eventType = radios[1].value;
            }

            await pages.config.setConfig({
                entityId: eventType,
                contentUrl: "https://YourSite/Connector/Setup",
                removeUrl:"https://YourSite/Connector/Setup",
                configName: eventType
                });

            pages.getConfig().then(async (config) {
                // We get the Webhook URL from config.webhookUrl which needs to be saved. 
                // This can be used later to send notification.
            });

            saveEvent.notifySuccess();
        });

        pages.config.registerOnRemoveHandler(function (removeEvent) {
            alert("Removed" + JSON.stringify(removeEvent));
        });

</script>

Para autenticar al usuario como parte de la carga de la página, consulte flujo de autenticación para las pestañas para integrar el inicio de sesión cuando la página está incrustada.

Nota:

Antes de TeamsJS v.2.0.0, el código debe llamar a microsoftTeams.authentication.registerAuthenticationHandlers() con la dirección URL y los métodos de devolución de llamada correctos o incorrectos antes de llamar authenticate() a debido a motivos de compatibilidad entre clientes. A partir de TeamsJS v.2.0.0, registerAuthenticationHandlers ha quedado en desuso a favor de llamar directamente a authenticate() con los parámetros de autenticación necesarios.

getConfig Propiedades de la respuesta

Nota:

Los parámetros devueltos por la getConfig llamada son diferentes cuando se invoca este método desde una pestaña y difieren de los documentados en la referencia.

En la tabla siguiente se proporcionan los parámetros y los detalles de las propiedades de respuesta getConfig:

Parámetros	Detalles
entityId	El identificador de entidad, establecido por el código al llamar a setConfig().
configName	El nombre de configuración, según lo establecido por el código al llamar a setConfig().
contentUrl	Dirección URL de la página de configuración, establecida por el código al llamar a setConfig().
webhookUrl	Dirección URL del webhook creada para el conector. Use la dirección URL del webhook para POST structured JSON para enviar tarjetas al canal. webhookUrl Solo se devuelve cuando la aplicación devuelve datos correctamente.
appType	Los valores devueltos pueden ser mail, groupso teams correspondientes a Microsoft 365 Mail, Grupos de Microsoft 365 o Teams. respectivamente.
userObjectId	Identificador único correspondiente al usuario de Microsoft 365 que inició la instalación del conector. Debe estar protegido. Este valor se puede usar para asociar al usuario en Microsoft 365, que ha configurado la configuración en el servicio.

Controlar ediciones

El código debe controlar los usuarios que vuelven para editar una configuración de conector existente. Para ello, llame a microsoftTeams.pages.config.setConfig() durante la configuración inicial con los parámetros siguientes:

• entityId es el identificador personalizado que representa lo que el usuario ha configurado y comprendido por el servicio.
• configName es un nombre que el código de configuración puede recuperar.
• contentUrl es una dirección URL personalizada que se carga cuando un usuario edita una configuración de conector existente.

Esta llamada se realiza como parte del controlador de eventos de guardado. A continuación, cuando se carga, el código debe llamar getConfig() a para rellenar previamente cualquier configuración o formulario en la contentUrl interfaz de usuario de configuración.

Control de eliminaciones

Opcionalmente, puede ejecutar un controlador de eventos cuando el usuario quita una configuración de conector existente. Para registrar este controlador, llame a microsoftTeams.pages.config.registerOnRemoveHandler(). Este controlador se usa para realizar operaciones de limpieza, como quitar entradas de una base de datos.

Incluir el conector en el manifiesto de la aplicación

Descargue el manifiesto de aplicación generado automáticamente (anteriormente denominado manifiesto de aplicación de Teams) desde el Portal para desarrolladores. Realice los pasos siguientes antes de probar o publicar la aplicación:

1. Incluya dos iconos.
2. Modifique la icons parte del archivo de manifiesto de la aplicación para incluir los nombres de archivo de los iconos en lugar de las direcciones URL.

El siguiente ejemplo de manifest.json contiene los elementos necesarios para probar y enviar la aplicación:

Nota:

Reemplace id y connectorId en el ejemplo siguiente con el GUID del conector.

Ejemplo de manifest.json con conector

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "id": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
  "version": "1.0",
  "developer": {
    "name": "Publisher",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.microsoft.com",
    "termsOfUseUrl": "https://www.microsoft.com"
  },
  "description": {
    "full": "This is a small sample app we made for you! This app has samples of all capabilities Microsoft Teams supports.",
    "short": "This is a small sample app we made for you!"
  },
  "icons": {
    "outline": "sampleapp-outline.png",
    "color": "sampleapp-color.png"
  },
  "connectors": [
    {
      "connectorId": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
      "scopes": [
        "team"
      ]
    }
  ],
  "name": {
    "short": "Sample App",
    "full": "Sample App"
  },
  "accentColor": "#FFFFFF",
  "needsIdentity": "true"
}

Pruebe su conector

Para probar el conector, cárguelo en un equipo con cualquier otra aplicación. Puede crear un paquete de .zip mediante el archivo de manifiesto de la aplicación desde los dos archivos de icono y el Panel para desarrolladores de conectores, modificados como se indica en Incluir el conector en el manifiesto de la aplicación.

Después de cargar la aplicación, abra la lista Conectores desde cualquier canal. Desplácese hasta la parte inferior para ver la aplicación en la sección Cargada.

Nota:

El flujo se produce completamente dentro de Teams como una experiencia hospedada.

Para comprobar que HttpPOST acción funciona correctamente, envíe mensajes al conector.

Siga la guía paso a paso para crear y probar los conectores en Teams.

Distribución de webhook y conector

1. Cree webhooks entrantes directamente para su equipo.

2. Agregue una página de configuración y publique el webhook entrante en un conector para Grupos de Microsoft 365.

3. Empaqueta y publica el conector como parte del envío de AppSource.

Ejemplo de código

En la tabla siguiente se proporciona el nombre de ejemplo y su descripción:

Ejemplo de nombre	Descripción	.NET	Node.js
Notificación TODO del conector	En este ejemplo se muestra un conector para Grupos de Microsoft 365, que genera y envía notificaciones para el canal de Teams.	View	View
Ejemplo de conectores genéricos	En este ejemplo se muestra un conector genérico que es fácil de personalizar para cualquier sistema que admita webhooks.	ND	View

Guía paso a paso

Siga la guía paso a paso para crear y probar el conector en Teams.

Vea también

• Webhooks y conectores
• Creación de webhooks entrantes
• Crear webhooks salientes
• Crear y enviar mensajes
• Cómo pueden los administradores habilitar o deshabilitar conectores
• Cómo pueden los administradores publicar conectores personalizados en su organización
• Esquema del manifiesto de la aplicación