Trello per Rest-API steuern

Möchtest Du den gesamten Artikel lesen? Und vielleicht sogar den Artikel im PDF-Format und die Beispieldateien herunterladen? Dann hole Dir den Artikel gleich hier - völlig kostenlos!

Trello ist eines der bekanntesten Projektmanagement-Tools. Damit lassen sich Projekte, Aufgaben und ToDos im Kanban-Style verwalten. Die Basisfunktionen sind bereits mächtig und dabei aber nicht unübersichtlich und man kann über sogenannte PowerUps viele zusätzliche Funktionen integrieren. Nicht zu reden von den Automationen – viele sind interne Automationen, die innerhalb von Trello genutzt werden köknnen und natürlich gibt es auch einige Möglichkeiten, Trello und die enthaltenen Elemente über Werkzeuge wie Zapier oder Make von anderen Tools zu steuern und umgekehrt. Aber wir wären keine VB/VBA-Entwickler, wenn wir nicht per Code auf die in Trello angelegten Boards, Karten und Eigenschaften zugreifen wollten, um diese zu lesen oder zu schreiben. Die Weboberflächen vieler noch so guter Tools bieten letztlich nicht immer alle nötigen Funktionen, die man aber abbilden kann, wenn das Tool eine Rest-API anbietet und man sich mit der Steuerung solcher APIs unter VB/VBA auskennt. Dann können wir beispielsweise schnell die Projekte oder Aufgaben aus einer Excel- oder Access-Tabelle in Trello anlegen oder auch auf die in Trello enthaltenen Daten zugreifen, um diese mit den Daten in unserer Datenbankwendung abzugleichen. In diesem Artikel zeigen wir, wie dies gelingt.

Voraussetzungen für die Nutzung der Trello-Rest-API

Voraussetzung ist, dass wir einen Trello-Account angelegt haben.

Im Gegensatz zu verschiedenen anderen Anbietern gibt es bei Trello keine grundsätzlichen Einschränkungen in Abhängigkeit vom Zahlungsplan, den man gewählt hat – die Rest-API können wir immer nutzen.

Allerdings sind bestimmte Funktionen erst mit den höheren, kostenpflichtigen Plänen verfügbar. So können wir beispielsweise mit den höheren Plänen eine höhere Anzahl von Aufrufen pro Zeiteinheit absetzen oder auch erweiterte Funktonen nutzen. Benutzerdefinierte Felder beispielsweise können wir mit dem kostenlosen Plan noch nicht bearbeiten oder nutzen.

Erste Schritte für die Trello-Rest-API

Wann immer wir eine Rest-API verwenden wollen, benötigen wir einen Key, mit dem wir uns bei der Rest-API für unseren Account referenzieren können.

Das bedeutet, dass wir irgendwo in unserem Trello-Kundenkonto eine solche Zeichenfolge finden oder anlegen können sollten. Die grundlegenden Informationen finden wir unter dieser URL:

https://developer.atlassian.com/cloud/trello/guides/rest-api/api-introduction/

Power-Up/Integration anlegen

Um auf die Rest-API zugreifen zu können, müssen wir eine neue Integration erstellen. Dazu gehen wir zur folgenden URL, wobei wir für die folgenden Schritte bereits mit unserem Benutzerkonto angemeldet sein müssen:

https://trello.com/power-ups/admin

Hier finden wir eine Schaltfläche namens Neu, die wir gleich einmal betätigen (siehe Bild 1).

Bild 1: Seite zum Anlegen eines Power-Ups oder einer Integration

Auf der anschließend erscheinenden Seite geben wir die für das Anlegen eines Power-Up beziehungsweise einer Integration benötigten Informationen an (siehe Bild 2).

Bild 2: Eingabe der notwendigen Informationen

Die nächste Seite lädt uns nun direkt dazu ein, einen API-Schlüssel zu erstellen.

Um das zu erledigen, klicken wir auf den Befehl Einen neuen API-Schlüssel generieren (siehe Bild 3).

Bild 3: Anlegen des neuen Schlüssels

Eine Bestätigung später sehen wir auf der gleichen Seite bereits unsere API-Schlüssel. Diesen kopieren wir in die Zwischenablage und speichern ihn an einer sicheren Stelle zwischen, zum Beispiel in einer Textdatei.

Außerdem finden wir, etwas versteckt, den Link zum manuellen Erstellen eines Tokens für unsere Anwendung (in Bild 4 hervorgehoben).

Bild 4: Der neue Schlüssel auf der Webseite von Trello

Hier weist der Text explizit darauf hin, dass wir ein hier manuell erstelltes Token nutzen können, um eine Anwendung selbst zu erstellen oder lokal zu testen. Wir haben an dieser Stelle nicht vor, eine Anwendung zu programmieren, mit der wir auf die Boards anderer Benutzer zugreifen wollen.

Wir möchten allein auf unser eigenes Board zugreifen und die dort enthaltenen Elemente einlesen und bearbeiten können.

Durch das Anklicken des Links mit dem Text Token gelangen wir zu einer weiteren Seite, die wir in Bild 5 sehen.

Bild 5: Anlegen eines Tokens für die Authentifizierung

Dies ist der Dialog, der auch auftauchen würde, wenn wir einer Anwendung den Zugriff auf die Boards anderer Benutzer erlauben wollten. In diesem Fall wollen wir allerdings nur ein Token für den Zugriff auf unser eigenes Board erhalten. Nach einer Prüfung, ob die Benutzerdaten, mit denen wir angemeldet sind, mit den hier angezeigten Benutzerdaten übereinstimmen, können wir uns den unteren Bereich des Dialogs ansehen.

Hier finden wir die Angabe der Berechtigungen, die wir mit dem zu erstellenden Token erhalten.

Beispielsweise der Zugriff auf Name und Benutzername, Einfügen von Kommentaren, aber vor allem Zugriff auf alle Boards und Arbeitsbereiche und das Erstellen und Aktualisieren von Karten, Listen, Boards und Arbeitsbereichen.

Hier klicken wir nun die Schaltfläche Erlauben an. Dies liefert uns als Ergebnis eine neue Seite, mit dem Token, das uns noch für den Zugriff auf die Rest-API fehlte (siehe Bild 6).

Bild 6: Das Token für den Zugriff auf unser Trello-Konto

Diese Token kopieren wir ebenfalls in die Zwischenanlage und fügen es zu der Textdatei hinzu, in der wir bereits den API-Key gespeichert haben.

Erste Schritte für den Trello-Zugriff in VBA

Wenn wir nun per VBA auf Trello zugreifen wollen, benötigen wir für unser VBA-Projekt einen Verweis auf die Bibliothek Microsoft XML, v6.0. Diesen legen wir an, indem wir im VBA-Editor den Menübefehl Extras|Verweise betätigen und hier den entsprechenden Eintrag selektieren (siehe Bild 7). Hier fügen wir gleich noch einen weiteren Eintrag hinzu, nämlich den namens Microsoft Scripting Runtime. Diesen benötigen wir für die Verwendung der nachfolgend vorgestellten Module, die intensiven Gebrauch des Dictionary-Objekts machen, das sich in diesem Verweis verbirgt.

Bild 7: Hinzufügen eines Verweises auf die XML-Bibliothek

Diese Module sind in anderen Artikel bereits zum Einsatz gekommen und heißen mdlJSON und mdlJSONDOM. Mehr dazu erfährst Du in den Artikeln Mit JSON arbeiten (www.vbentwickler.de/361) und JSON-Dokumente per Objektmodell zusammenstellen (www.vbentwickler.de/412).

Referenz der Rest-API

Bevor wir mit der Programmierung der Rest-API beginnen, hier noch der Hinweis auf die Referenz der Rest-API von Trello. Dies finden wir unter dieser URL:

https://developer.atlassian.com/cloud/trello/rest

Hier finden wir auf der linken Seite alle bereits bekannten Elemente wieder – beispielsweise Boards, Cards, Checklists, CustomFields, Labels, Lists, Members und so weiter. Für jedes dieser Elemente finden wir alle denkbaren API-Befehle – hier wurde wirklich an alles gedacht.

Vorbereiten der Zugriffsdaten

Weiter oben haben wir den API-Key sowie das Token ausgelesen und in einer Textdatei zwischengespeichert. Diese holen wir nun hervor und speichern diese in zwei öffentlich deklarierten Konstanten. Diese legen wir in einem neuen, leeren VBA-Standardmodul an:

Public Const cStrApiKey_Trello As String = "1c16ba94e18e2xxxxxxxxx734f08c6345"
Public Const cStrToken_Trello As String = "ATTA6467f2ee3c81c6fa0xxxxxxxxxxacbfe587dc3c15eb30f19a61db195b311e1CBC464D1"

Außerdem platzieren wir in einer weiteren Konstanten die Basis-URL, die wir für alle Zugriffe als Grundlage verwenden:

Public Const cStrUrl_Trello As String = "https://api.trello.com/1"

Abfragen von Informationen zum aktuellen Benutzer

Weiter oben haben wir schon hervorgehoben, dass wir uns bei der in diesem Artikel beschriebenen Lösung auf den Rest-API-Zugriff auf die Daten unseres eigenen Benutzerkontos bei Trello beschränken würden. Wenn wir nun Informationen zu diesem Konto abrufen wollen, benötigen wir dementsprechend keine ID für unser Kundenkonto, die wir als Parameter übergeben, sondern lediglich das Schlüsselwort me als Referenz. Die Ausgabe der Details zu unserem Kundenkonto nutzen wir auch als Beispiel für die Einführung der wenigen benötigten Codezeilen für den Zugriff auf die Trello-Rest-API.

Die Basis für all unsere Zugriffe auf die Rest-API ist die Funktion HTTPRequestTrello aus Listing 1.

Public Function HTTPRequestTrello(strURL As String, Optional strMethod As String = "POST", _
         Optional strRequest As String, Optional strResponse As String) As Integer
     Dim objHTTP As ServerXMLHTTP60
     Set objHTTP = New MSXML2.ServerXMLHTTP60
     With objHTTP
         If InStr(1, strURL, "?") = 0 Then
             strURL = strURL & "?key=" & cStrApiKey_Trello & "&token=" & cStrToken_Trello
         Else
             strURL = strURL & "&key=" & cStrApiKey_Trello & "&token=" & cStrToken_Trello
         End If
         .Open strMethod, strURL, False
         .setRequestHeader "Content-Type", "application/json"
         If Not Len(strRequest) = 0 Then
             .setRequestHeader "Body", strRequest
         End If
         .send
         strResponse = .responseText
         HTTPRequestTrello = .status
     End With
End Function

Listing 1: Funktion für den Zugriff auf die Rest-API von Trello

Diese Funktion nimmt die URL, die Methode (POST, GET, PUT oder DELETE) sowie gegebenenfalls eine im JSON-Format gelieferte Anfrage entgegen. Ein weiterer Parameter namens strResponse liefert ein eventuell im JSON-Format erhaltenes Ergebnis zurück. Die Funktion selbst ist als Integer deklariert und sie soll einen Zahlenwert zurückliefern, der Auskunft über die Art des Ergebnisses liefert. Der Wert 200 beispielsweise steht für einen erfolgreichen Aufruf.

Die Funktion deklariert und erstellt ein Objekt des Typs ServerXMLHTTP60, mit dem wir den Zugriff auf die Rest-API durchführen können. Dazu prüfen wir kurz die URL aus strURL. Es kann sein, dass wir hier in der aufrufenden Prozedur bereits einen oder mehrere Parameter hinzugefügt haben. Der Teil der URL mit den Parametern wird immer mit dem Fragezeichen eingeleitet (?) und die einzelnen Name-Wert-Paare für die Parameter werden durch das Kaufmanns-Und miteinander verbunden (&).

Wenn bereits ein & vorhanden ist, hängen wir Key und Token mit einem führenden Fragezeichen an, sonst mit einem Kaufmanns-Und. Zur Überprüfung nutzen wir eine If…Then-Bedingung und ergänzen darin die URL um die beiden Werte der Konstanten cStrApiKey_Trello und cStrToken_Trello, die wir für die Parameter key und token anhängen.

Dann rufen wir die Open-Methode auf und übergeben dieser die Zugriffsart aus strMethod sowie die URL aus strURL.

Als Request-Header geben wir nur die Art des Content-Types an (JSON). Wenn die Variable strRequest einen Request im JSON-Format enthält, setzen wir den Inhalt dieser Variablen für einen weiteren Header namens Body.

Schließlich schicken wir die Anfrage mit der send-Methode ab und speichern die Antwort aus der Eigenschaft responseText im Rückgabeparameter strResponse und legen den Status als Rückgabewert der Funktion fest.

Um die Benutzerinformationen für unseren eigenen Benutzer abzurufen, benötigen wir eine recht kleine Prozedur namens GetProfileTrello zum Aufruf von HTTPRequestTrello (siehe Listing 2). Diese schreibt die um /members/me ergänzte Basis-URL in die Variable strURL, die auch an HTTPRequestTrello übergeben wird – nebst der Methode GET und der Variablen strResponse zum Holen der Antwort.

Public Sub GetProfileTrello()
     Dim intResult As Integer
     Dim strURL As String
     Dim strResponse As String
     strURL = cStrUrl_Trello
     strURL = strURL & "/members/me"
     intResult = HTTPRequestTrello(strURL, "GET", , _
         strResponse)
     Select Case intResult
         Case 200
             Debug.Print GetJSONDOM(strResponse, True)
         Case Else
             Debug.Print intResult, _
                 GetJSONDOM(strResponse, True)
     End Select
End Sub

Listing 2: Auslesen eines Profils über die Trello-Rest-API

Nach dem Ausführen der Funktion prüfen wir ihren Rückgabewert. Lautet dieser 200, war der Aufruf erfolgreich. Dann geben wir das Ergebnis, das als JSON-Dokument kommt, mithilfe der Funktion GetJSONDOM so strukturiert aus, dass wir per VBA leicht auf die ausgegebenen Elemente zugreifen können:

In Bild 8 sehen wir, wie das Ergebnis im Direkbereich des VBA-Editors ausgegeben wird. Hier sehen wir nicht nur die eindeutige ID für unseren Benutzer, sondern auch seinen Namen und die E-Mail-Adresse. Außerdem sehen wir hier auch noch weitere wichtige Informationen wie die IDs der Boards dieses Benutzers.

Bild 8: Ausgabe des Zugriffs auf den eigenen Benutzer

Boards eines Benutzers ausgeben

Wir können allerdings auch noch über eine eigens dafür vorgesehene API-Funktion auf die Boards eines Benutzers zugreifen. Die benötigte Rest-API-Funktion finden wir hier beschrieben:

https://developer.atlassian.com/cloud/trello/rest/api-group-members/#api-members-id-boards-get

Dieser Aufruf liefert normalerweise einen ganzen Rutsch an Informationen zu den jeweiligen Boards zurück.

Wir wollen diese Informationen eingrenzen, indem wir in der URL mit fields=id,name auf die beiden Felder ID und Name eingrenzen (siehe Listing 3).

Public Sub GetBoardsAMemberBelongsTo()
     Dim intResult As Integer
     Dim strURL As String
     Dim strResponse As String
     strURL = cStrUrl_Trello & "/members/me/boards?fields=id,name"
     intResult = HTTPRequestTrello(strURL, "GET", , strResponse)
     Select Case intResult
         Case 200
             Debug.Print GetJSONDOM(strResponse, True)
         Case Else
             Debug.Print intResult, _
                 GetJSONDOM(strResponse, True)
     End Select
End Sub

Listing 3: Einlesen aller Boards eines Mitglieds

Hier erhalten wir eine Antwort wie die folgende:

objJSON.Item(1).Item("id"): 66eb1bc1aade0c9c5f0ca455
objJSON.Item(1).Item("name"): Access [basics]
objJSON.Item(2).Item("id"): 6640778b978d4b578d8d71
objJSON.Item(2).Item("name"): Access im Unternehmen
...
objJSON.Item(7).Item("id"): 66ec4501b8422b5893b1f0e4
objJSON.Item(7).Item("name"): VB-Entwickler

Wir finden also mit einem Index versehene Elemente einer Auflistung vor. Wenn wir diese nacheinander verarbeiten wollen, brauchen wir nicht jeweils den Index zu setzen und die Anweisungen zu wiederholen, sondern können einfach über eine Schleife auf die Elemente zugreifen. Für den ersten Versuch reicht es jedoch, sich immer mal zunächst alle Elemente mit Debug.Print GetJSONDOM(strResponse, True) ausgeben zu lassen. Dann kann man die Struktur der Antwort analysieren und die Anweisungen für die tatsächliche Verarbeitung hinzufügen. In diesem Fall sieht das wie folgt aus:

Public Sub GetBoardsAMemberBelongsTo()
     ...
     Dim objJSON As Object
     Dim i As Integer
     ...
     Select Case intResult
         Case 200
             Set objJSON = ParseJson(strResponse)
             For i = 1 To objJSON.Count
                 Debug.Print objJSON.Item(i).Item("id"), _
                     objJSON.Item(i).Item("name")
             Next i
         ...
     End Select
End Sub

Wir haben zwei Variablen namens objJSON und i hinzugefügt. Mit objJSON referenzieren wir das Ergebnis der Funktion ParseJSON für das mit strResponse gelieferte JSON-Dokument.

Ende des frei verfügbaren Teil. Wenn Du mehr lesen möchtest, hole Dir ...

den kompletten Artikel im PDF-Format mit Beispieldatenbank

diesen und alle anderen Artikel mit dem Jahresabo