In de vorige blog (de Micro Integrator verbinden met de Mastodon API – Deel 1) heb ik gekeken naar de API die Mastodon beschikbaar stelt om bijvoorbeeld het plaatsen van nieuwe toots (de naam van een bericht op Mastodon) te automatiseren. Waarom is dit belangrijk? Welnu, dit soort services wordt, net als Twitter voorheen, ook een communicatiekanaal voor bedrijven. En waar een browsergebaseerde interface voor reguliere gebruikers ok is, is integratie in het IT-landschap best aantrekkelijk voor organisaties.
Processen kunnen worden gestroomlijnd door berichten te automatiseren (zowel lezen als verzenden) en in dit tweede deel laat ik de aanpak zien voor het creëren van een dergelijke integratie met behulp van de Connector-functie van WSO2 Micro Integrator.
De connector maken
Een connector is een reeks gebundelde services die kunnen worden geïntegreerd in de Micro Integrator. Het is een zip-bestand dat wordt geparseerd. De afzonderlijke services worden toegevoegd aan de server, zodat u de functionaliteit ervan kunt gebruiken, zoals het automatisch verzenden van berichten.
Vanuit de ontwikkelingshoek gezien kan dezelfde connector in Integration Studio worden gebruikt om nieuwe artefacten te ontwikkelen met de nieuwe functionaliteit, zoals je later in dit artikel ziet.
Het creëren van een complete connector is veel werk en wat ik je nu ga laten zien, is hoe je de structuur opzet en een eenvoudige implementatie uitvoert. Een van de redenen is dat de blog anders heel groot zou worden.
Dus als parameter neem ik het toegangstoken dat we hebben gekregen bij de laatste API-aanroep in de vorige blog. Dit token wordt gedefinieerd als een parameter en vervolgens als een header naar de back-end-API verzonden.
Het opzetten van een structuur voor een connector voor de micro-integrator is vrij eenvoudig. Wat je moet doen, is een maven-archetype gebruiken en dit zo configureren dat het de API bevat die je wilt openstellen.
Dit is de maven-opdracht:
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.esb.connector -DartifactId=org.wso2.carbon.esb.connector.mastodon -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/
Hier zie je een deel van de structuur:
Een connector kan bestaan uit synapsconfiguraties, maar ook uit Java- en Soap-services, afhankelijk van wat nodig is.
src/main/resources is de map waarin we op een zeer eenvoudige en lichtgewicht manier de nodige wijzigingen gaan aanbrengen. Wanneer ik de map Source/Main/Resources open, zul je zien dat er twee submappen zijn, Sample en Config. In het connectorbestand wordt naar deze beide verwezen.
We maken een nieuwe submap maken met de naam Statusses waarin we de statussjabloon definiëren waarmee we een status op ons gebruikersaccount op Mastodon kunnen plaatsen.
Verwijder de map Sample en maak de map Statusses. Vergeet niet om ook het connectorbestand bij tee werken. Ik heb een pictogram-submap gemaakt waarin ik twee Mastodon-pictogrammen heb geplaatst (25×25 en 72×80 png). De documentatie is nogal vaag in die zin, dat in sommige voorbeelden naar de pictogrammen wordt verwezen in het connectorbestand in de root en in sommige niet; de map is er gewoon.
Ik verwees er niet naar, maar plaatste ze gewoon op de juiste plaats met de juiste namen.
De API-aanroep is eenvoudig vast te leggen. Dit is de synapscode van de bron. Zoals je ziet, stellen we dit open als een API. Voor de connector ga ik geen API gebruiken, maar een reekssjabloon met een parameter, in dit geval de status die we ontvangen van de API-aanroep en naar het HTTP-eindpunt sturen.
<?xml version="1.0" encoding="UTF-8"?>
<api context="/mastodon" name="Status" xmlns="http://ws.apache.org/ns/synapse">
<resource methods="POST" url-mapping="/status">
<inSequence>
<property expression="json-eval($.status)" name="uri.var.status"/>
<header name="Authorization" scope="transport" value="Bearer IfC08KP8LtDT9I1bofk-yhoZ9zgswn6CRK23okW42Gk"/>
<call>
<endpoint>
<http method="post" uri-template="https://mastodon.nl/api/v1/statuses?status={uri.var.status}">
<suspendOnFailure>
<initialDuration>-1</initialDuration>
<progressionFactor>-1</progressionFactor>
<maximumDuration>0</maximumDuration>
</suspendOnFailure>
<markForSuspension>
<retriesBeforeSuspension>0</retriesBeforeSuspension>
</markForSuspension>
</http>
</endpoint>
</call>
<respond/>
</inSequence>
<outSequence/>
<faultSequence/>
</resource>
</api>
Hier zie je ook dat de API-aanroep is geslaagd en dat de statusupdate beschikbaar is in Mastodon.
Wat we nu gaan doen, is de API aanpassen om de wijzigingen weer te geven. Dus in plaats van tijdens de aanroep van de API gaan we de sjabloon met de parameter aanroepen.
In plaats van de API-aanroep roepen we nu een sjabloon aan die de statusupdate naar Mastodon verzendt.
<?xml version="1.0" encoding="UTF-8"?>
<template name="write-status" xmlns="http://ws.apache.org/ns/synapse">
<parameter isMandatory="false" name="status"/>
<sequence>
<property expression="$func:status" name="uri.var.status" scope="default" type="STRING"/>
<header name="Authorization" scope="transport" value="Bearer IfC08KP8LtDT9I1bofk-yhoZ9zgswn6CRK23okW42Gk"/>
<call>
<endpoint>
<http method="post" uri-template="https://mastodon.nl/api/v1/statuses?status={uri.var.status}">
<suspendOnFailure>
<initialDuration>-1</initialDuration>
<progressionFactor>-1</progressionFactor>
<maximumDuration>0</maximumDuration>
</suspendOnFailure>
<markForSuspension>
<retriesBeforeSuspension>0</retriesBeforeSuspension>
</markForSuspension>
</http>
</endpoint>
</call>
</sequence>
</template>
And
<?xml version="1.0" encoding="UTF-8"?>
<component name="statuses" type="synapse/template" >
<subComponents>
<component name="write-status" >
<file>write-status.xml</file>
<description>mastodon simple connection</description>
</component>
</subComponents>
</component>
Ik doe een mvn build (mvn clean install) die in een connector resulteert.
Voeg deze toe aan de Integration Studio in mijn project.
En daar is het, een Mastodon-connector met onze geïmplementeerde handelingen.
Ik kan nu beginnen met het ontwikkelen van artefacten met behulp van de Mastodon-connector. Ik maak een proxy die eenvoudigweg een bericht dat in de payload komt, naar ons Mastodon-account pusht.
De configuratie is een eenvoudig Soap-bericht dat een XML als payload neemt en het bericht uit de payload (//incoming) haalt en naar de sjabloon stuurt om te worden doorgestuurd naar Mastodon.
In een grafisch overzicht ziet het er zo uit:
In de bronweergave als volgt:
<?xml version="1.0" encoding="UTF-8"?>
<proxy name="MProxy" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
<target>
<inSequence>
<mastodon.write-status>
<status>{//incoming}</status>
</mastodon.write-status>
<respond/>
</inSequence>
<outSequence/>
<faultSequence/>
</target>
</proxy>
Ik heb een Soap-project gemaakt in SoapUI waar ik een heel eenvoudige body heb gebouwd. De tag <incoming> bevat het bericht dat wordt opgehaald door de Xpath-opdracht //incoming in de bovenstaande code.
Je ziet het bericht naar Mastodon komen. Omdat ik in dit geval het antwoord van Mastodon neem en het terugstuur naar de client, zie je in SoapUI het originele antwoord van de API.
HTTP/1.1 200 OK
[ … ]{“id”:”109823997802502951″,”created_at”:”2023-02-07T14:46:56.499Z”,”in_reply_to_id”:null,”in_reply_to_account_id”:null,”sensitive”:false,”spoiler_text”:””,”visibility”:”public”,”language”:”en”,”uri”:”https://mastodon.nl/users/yenlo/statuses/109823997802502951″,”url”:”https://mastodon.nl/@yenlo/109823997802502951″,”replies_count”:0,”reblogs_count”:0,”favourites_count”:0,”edited_at”:null,”favourited”:false,”reblogged”:false,”muted”:false,”bookmarked”:false,”pinned”:false,”content”:”\u003cp\u003ethis is mymessage\u003c/p\u003e”,”filtered”:[],”reblog”:null,”application”:{“name”:”yenlo-app”,”website”:null},”account”:{“id”:”109703822406851413″,”username”:”yenlo”,”acct”:”yenlo”,”display_name”:”yenlo”,”locked”:false,”bot”:false,”discoverable”:false,”group”:false
[ … ]}
In Mastodon zie je natuurlijk alleen het bericht.
Resultaat
In redelijk korte tijd heb ik een heel simpele connector gemaakt die een verbinding maakt met een service. Ik heb eerder gezegd dat als je dit op een manier wilt doen dat het bruikbaar is buiten een simpele blog als deze, het je veel tijd kost om de juiste API uit te zoeken en alle beschikbare API’s en services te implementeren. De configuratie met een hardgecodeerd toegangstoken naar de mastodon-API is iets dat in de praktijk natuurlijk nooit wordt gedaan. Als ik dit in een echt scenario zou ontwikkelen, zou ik de geheime tokens en codes van de clientsleutel-client coderen en ze in een soort kluis opslaan om ze op te halen wanneer ik ze nodig heb.
Het grote voordeel van het werken met connectoren is dat veel van het werk al is gedaan. En wat je nog moet doen, is maar een klein stukje: verbinding maken met de service die je referenties ergens opslaat en of ophaalt. Daarna kun je op een heel eenvoudige manier beginnen met het bouwen van integraties door ze te slepen naar een grafische weergave terwijl je de details in de bronweergave invult.