Como ya sabemos WSO2 y sus productos cuentan con muchas particularidades y facilidades para llevar a cabo nuestras integraciones. Hoy hablaremos de una más: los conectores (Connectors).
Los conectores son componentes encapsulados que pueden contener múltiples operaciones. Cada una de estas operaciones nos permitirá mediante diferentes medios ponernos en contacto con APIs de terceros.
En base al medio con el que nos comuniquemos, podremos diferenciar los distintos tipos de conectores que tenemos:
- Java: Realiza las operaciones a través de custom class mediators.
- SOAP: Realiza las operaciones a través de llamadas SOAP.
- REST: Realiza las operaciones a través de llamadas REST.
Como es normal, WSO2 ya cuenta con un numeroso listado de conectores ad hoc para algunas de las aplicaciones más famosas mundialmente, como puede ser Twitter o Facebook.
En este tutorial veremos cómo realizar un conector REST que nos permita comunicarnos con la aplicación de mensajería instantánea Telegram.
Creación del Conector
La estructura básica del conector podemos realizarla a través de un arquetipo maven. Esta estructura estará compuesta por los ficheros de configuración, las plantillas/templates que realizarán las conexiones con las APIs de terceros y clases Java (en caso de que se trate de un conector Java).
Nuestro conector se llamará telegramConnector y el comando para su creación sería el siguiente:
mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.wso2.carbon.extension.archetype -DarchetypeArtifactId=org.wso2.carbon.extension.esb.connector-archetype -DarchetypeVersion=2.0.4 -DgroupId=org.wso2.carbon.connector -DartifactId=telegramConnector -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/
Componentes del Conector
Los conectores tienen dos partes diferenciadas:
1) Los ficheros de configuración que nos permitan indicar los distintos templates y la forma de acceder a ellos
- <connector_home>/src/main/resources/connector.xml
Es el fichero de configuración principal. En él indicaremos los valores descriptivos del conector como su nombre, descripción y sus dependencias o componentes.
<connector> <component name="telegramConnector" package="org.wso2.carbon.connector"> <dependency component="message" /> <description>WSO2 telegramConnector connector library</description> </component> <icon>icon/icon-small.gif</icon> </connector>
- <connector_home>/src/main/resources/config/component.xml
Estos componentes que a su vez se pueden dividir en otros subcomponentes, son las operaciones que pondremos a disposición de los usuarios. Y será en estos componentes donde indicaremos la plantilla asociada a la operación.
<component name="message" type="synapse/template" >
<subComponents>
<component name="message" >
<file>message_template.xml</file>
<description>telegram message method</description>
</component>
</subComponents>
</component>
En un conector sencillo podríamos tener un único componente y que esté a su vez tuviera una única operación asociada. Pero si pensamos en APIs más grandes, podremos diferenciar estos componentes en base al contexto de la API y los subcomponentes en base a los recursos de esta.
2) Los templates que contendrán la forma de comunicación con la API externa
- Plantilla /Templates
Estas plantillas serán templates al uso de WSO2, donde incluiremos la lógica necesaria para llevar a cabo la conexión con la API. Se sitúan en el directorio <connector_home>/src/main/resources/config/
<template xmlns="http://ws.apache.org/ns/synapse" name="message">
<parameter name="text" />
<parameter name="chatId" />
<sequence>
<property name="uri.var.botApiToken" expression="wso2:vault-lookup('botApiToken')" scope="default" type="STRING"/>
<property name="uri.var.chatId" expression="$func:chatId" />
<property name="uri.var.msg" expression="$func:text" />
<call>
<endpoint>
<http method="post" uri-template="https://api.telegram.org/bot{uri.var.botApiToken}/sendMessage?chat_id={uri.var.chatId}&text={uri.var.msg}" />
</endpoint>
</call>
</sequence>
</template>
En esta plantilla podemos ver como enviar un mensaje a un chat de Telegram. Los pasos principales para habilitar un chat y que nos permita enviarle mensajes son:
- Crear un bot de Telegram.
- Crear un chat o canal público.
- Añadir al bot como administrador.
- Asociar a la llamada a la API de Telegram: el identificador del bot, del chat y el propio mensaje.
Instalación del conector
Una vez que hemos diseñado todos los componentes deberemos empaquetar nuestro proyecto a través del comando maven:
mvn package |
El siguiente paso será acceder a la consola de gestión del carbon e incluir el zip generado. Para poder incluir el conector debemos acceder a la opción de menú Main > Connectors > Add. Y por último habilitar el conector instalado.
Ejecución
Ya solo nos quedaría la invocación del conector. Para ello crearemos por ejemplo un proxy Service que recibirá un mensaje y lo enviará al chat de Telegram en su secuencia de entrada.
<sequence name="basicSequence" xmlns="http://ws.apache.org/ns/synapse">
<property expression="$body/content" name="content"/>
<telegramConnector.message>
<chatId>@WSO2ConnectorExample</chatId>
<text>{$ctx:content}</text>
</telegramConnector.message>
<respond/>
</sequence>
Como podéis ver, el conector se llama ‘telegramConnector’ tal y como indicamos en el fichero de configuración principal. Y la operación que nos permite enviar el mensaje es ‘message’ tal y como indicamos en el fichero de configuración del componente.
Conclusión
Los conectores, como podéis ver, son otra buena herramienta que nos permite habilitar conexiones con otras APIs, encapsular todo el código referente a dichas conexiones y además reutilizarlo de forma sencilla.
