Verwendung der öffentlichen API Timeular
Wir haben kürzlich unsere öffentliche API v3 unter developers.timeular.com veröffentlicht. Diese neueste Version bietet die Möglichkeit, mit unserer neuen Spaces-API zu arbeiten.
Spaces ermöglicht Teams die Zusammenarbeit und die gemeinsame Zeiterfassung. Die Aufnahme in die öffentliche API war daher ein wichtiger Schritt, um unseren Nutzern die Anpassung und Verbesserung ihrer Arbeitsabläufe zu erleichtern.
Mit unserer öffentlichen API können Benutzer ihre eigenen Integrationen von Drittanbietern, benutzerdefinierte Automatisierungswerkzeuge und Berichte erstellen, die genau auf ihre Bedürfnisse zugeschnitten sind.
Eine weitere aufregende neue Funktion innerhalb unserer öffentlichen API sind Webhooks, die wir in einem zukünftigen Beitrag behandeln werden. Webhooks ermöglichen endlich eine Zwei-Wege-Kommunikation mit unserer API und öffnen die Tür für viel umfangreichere Automatisierungen und von der Community entwickelte Integrationen.
Webhooks ermöglichen uns auch die Integration mit Tools wie Zapier.
In diesem Beitrag werden wir uns ansehen, wie wir unsere öffentliche API für einfache Datenabrufe und -manipulationen nutzen können. Wir werden Rust als Sprache für die Erstellung des Beispiels verwenden. Die zugrundeliegenden Ideen und die Struktur des Beispiels funktionieren jedoch für jede andere Sprache genauso.
Da wir Postman für die Veröffentlichung unserer API-Dokumente verwenden, können Sie auch die Sprache der Beispiele über die Sprachauswahl oben auf der Seite developers.timeular.com umschalten. Auf diese Weise können Sie sehen, wie Sie Anfragen an unsere API in vielen verschiedenen von Postman unterstützten Sprachen stellen können.
Alles, was Sie in einer beliebigen Sprache benötigen, ist eine HTTP-Client-Bibliothek, die HTTPS unterstützt, und ein Timeular Konto.
Fangen wir an!
Grundlegende Einrichtung
Zunächst fügen wir einige Abhängigkeiten in ein neues Projekt ein, das wir mit "cargo init" erstellen.
Wir verwenden die reqwest-Bibliothek für die Erstellung von HTTP-Anfragen. Wir werden die async-API verwenden, die die Tokio-Laufzeitumgebung nutzt. Außerdem benötigen wir serde und serde_json für die Serialisierung und Deserialisierung von Anfragen und Antworten in und aus JSON.
Die once_cell-Kiste ist nur ein Helfer, den wir hier verwenden, um einen trägen statischen HTTP-Client zu erstellen, damit wir ihn nicht an jede Methode übergeben müssen.
In diesem Beispiel werden wir mehrere Schritte unter Verwendung der öffentlichen API Timeular ausführen:
- Authentifizieren Sie
- Abrufen unseres Benutzerprofils
- Holen Sie unsere Räume
- Aktivitäten abrufen
- Starten Sie eine neue Verfolgung
- Beenden Sie die Verfolgung
- Erzeugen eines Berichts und Speichern in einer lokalen Datei
Lassen Sie uns zunächst einige Pakete importieren und einige Konstanten definieren:
Der Einfachheit halber erstellen wir einen "catch-all"-Fehlertyp, da wir uns in diesem kleinen Beispiel nicht mit der Fehlerbehandlung befassen werden.
Dann verwenden wir, wie oben erwähnt, once_cell, um einen lazy request::Client zu erstellen, auf den wir global zugreifen können.
Schließlich definieren wir Konstanten für die BASE_URL der öffentlichen API Timeular und für den Dateinamen des Berichts, den wir später speichern werden.
Da nun die gesamte Infrastruktur vorhanden ist, sollten wir mit der Authentifizierung beginnen.
Authentifizierung
Wenn Sie noch kein Konto haben, müssen Sie hier ein Konto erstellen und es aktivieren.
Erstellen Sie dann über das Dashboard Ihre API-Anmeldedaten und kopieren Sie das API-Geheimnis an einen sicheren Ort, da es Ihnen nicht mehr angezeigt wird.
Für diese kleine Anwendung halten wir es mit den Anmeldeinformationen einfach und erwarten nur zwei Umgebungsvariablen:
- TMLR_API_KEY - Der TImeular API-Schlüssel
- TMLR_API_SECRET - Das Timeular API-Geheimnis
Mit diesen Anmeldedaten können wir unter developers.timeular.com nachsehen, wie wir uns anmelden können.
Verwenden Sie die als "AKTUELL" gekennzeichnete API-Version (API v3 zum Zeitpunkt der Erstellung dieses Artikels) und navigieren Sie zu "Authentifizierung" und dann zu "Anmeldung mit API-Schlüssel und API-Geheimnis".
In der Dokumentation steht, dass wir eine POST-Anfrage mit den Anmeldeinformationen senden sollen und ein Token zurückbekommen, das wir dann in einer Kopfzeile für die Autorisierung verwenden können.
Um dies zu erreichen, holen wir uns zunächst die Umgebungsvariablen und übergeben sie an eine Anforderungsfunktion in main:
Die Funktion sign_in sieht wie folgt aus:
Gehen wir es Schritt für Schritt durch. Wir verwenden std::env, um die erwarteten Umgebungsvariablen zu lesen, und wenn eine von ihnen nicht gesetzt ist, geben wir eine Fehlermeldung aus. So weit, so gut.
Dann definieren wir SignInRequest als serialisierbare Struktur, die die Anmeldedaten enthält. Wir müssen hier die rename_all-Funktionalität von Serde verwenden, damit das tatsächliche JSON camelCase-Namen verwendet, was die API erwartet.
Innerhalb der sign_in-Funktion erstellen wir den JSON-Body aus dem angegebenen Token und dem Geheimnis und verwenden unseren gemeinsamen CLIENT (die reqwest::Client-Instanz), um eine POST-Anfrage zu senden.
Der url helper verkettet einfach die am Anfang definierte BASE_URL mit dem Pfad, der uns interessiert:
Wir setzen den JSON-Body in die Anfrage und senden sie ab. Da wir die asynchrone Version von reqwest verwenden, müssen wir auf die Antwort warten.
Dann können wir den json-Helper auf die Antwort anwenden, um sie in die oben definierte SignInResponse-Struktur zu deserialisieren, die einfach das Authentifizierungs-Token enthält. Auch diesen Schritt müssen wir abwarten, da er den Body asynchron liest.
Wir behandeln alle Fehler, indem wir sie mit dem Operator ? in der Kette nach oben propagieren. Das bedeutet, dass das Programm abstürzt, wenn hier ein Fehler auftritt - z. B. weil das JSON ungültig ist -, da wir die Fehler bis zu main weiterleiten, das ein Ergebnis mit dem von uns definierten Catch-All-Fehlertyp zurückgibt.
Wenn alles geklappt hat, geben wir einfach das Token zurück, das wir nun für authentifizierte Anfragen verwenden können.
Benutzerdaten
Unser nächstes Ziel ist es, einige Daten über uns selbst abzurufen, zum Beispiel unser Benutzerprofil und unsere Räume.
Zu diesem Zweck erstellen wir zwei weitere Funktionen - fetch_me und fetch_spaces. Jeder dieser Funktionen wird unser neu erstelltes Authentifizierungstoken übergeben.
Sehen wir uns zunächst fetch_me an, das den Endpunkt Me verwendet, der unter Benutzerprofil -> Benutzer -> Me zu finden ist.
Wir definieren ein Antwortobjekt, das unsere Benutzerkennung, unseren Namen, unsere E-Mail-Adresse und die Kennung unseres Standardbereichs enthält.
In der Funktion fetch_me rufen wir einfach den HTTP-Client mit einem get in Richtung /me auf, setzen den Authorization-Header auf unser Auth-Token mit dem Präfix "Bearer" und senden ihn ab, wobei wir die Antwort in eine MeResponse parsen.
Dies ist im Wesentlichen die ganze Magie, die wir tun müssen, um authentifizierte Anfragen an die Timeular API zu stellen - setzen Sie den Authorization-Header mit den richtigen Werten.
In diesem Sinne ist das Abrufen unserer Räume einfach:
Wir machen das Gleiche noch einmal. Der einzige Unterschied besteht darin, dass wir eine andere URL aufrufen, die Sie unter Benutzerprofil -> Raum -> Räume mit Mitgliedern auf developers.timeular.com finden.
Da die Antwort in diesem Fall eine Liste mit einigen verschachtelten Objekten ist, müssen wir ein paar weitere Typen erstellen, aber alles in allem ist der Prozess derselbe, und wir haben am Ende eine vollständig ausgefüllte Liste unserer Räume und ihrer Mitglieder.
Denken Sie daran, dass Sie die Daten anderer Mitglieder nur sehen, wenn Sie der Administrator eines Bereichs sind, ansonsten sehen Sie nur sich selbst und die Administratoren in der Antwort.
Das war's mit den Profildaten, jetzt können wir mit der Zeiterfassung beginnen!
Daten der Zeiterfassung
Um die Zeit zu erfassen, brauchen wir zunächst Aktivitäten, also holen wir diese ab.
Die Funktion fetch_activities folgt dem Stil der beiden vorherigen Aufrufe. Wir definieren zunächst die Datenmodelle für die Verarbeitung der Antwort und senden dann eine authentifizierte Anfrage an /activities. Die Endpunkte für die Zeiterfassung finden Sie unter Zeiterfassung in den öffentlichen API-Dokumenten.
Vergewissern Sie sich, dass mindestens eine Aktivität vorhanden ist, andernfalls erstellen Sie eine neue Aktivität über die API oder eine unserer Anwendungen.
Der nächste Schritt besteht darin, eine neue Verfolgung zu starten und sie wieder zu stoppen. Wir werden dafür fest kodierte Zeitstempel verwenden, aber Sie können auch die aktuelle Uhrzeit verwenden. Achten Sie nur darauf, dass der Zeiteintrag mindestens eine Minute lang ist, da dies zum Zeitpunkt der Erstellung dieses Artikels in API v3 die untere Grenze ist.
Wir prüfen, ob unsere Aktivitätenliste Werte enthält, und wenn ja, rufen wir die start_tracking-Methode mit der ersten Aktivität in der Liste und unserem Authentifizierungstoken auf.
Die Nutzdaten sind, wie in den öffentlichen API-Dokumenten zu sehen ist, recht einfach - wir senden einfach einen Zeitstempel "started_at", der wie folgt formatiert ist: "2020-08-03T04:00:00.000″. Wichtig ist, dass die API immer UTC-Zeitstempel erwartet. Stellen Sie also sicher, dass Sie Ihre lokale Zeit in UTC konvertieren, bevor Sie sie senden, um sicherzustellen, dass die Zeiten korrekt sind.
Wir erhalten ein TrackingResponse-Objekt zurück:
Die Tracking-Antwort enthält eine Tracking-ID, eine Aktivitäts-ID, die Startzeit, die wir gesendet haben, und eine Notiz. Diese Notiz besteht aus einem Textelement und einer Liste von Tags bzw. Erwähnungen. Wir werden hier nicht näher auf die Tags bzw. Erwähnungen eingehen, aber Sie sollten sich die öffentlichen API-Dokumente zu diesem Thema ansehen.
Tags und Erwähnungen sind eine Möglichkeit, Ihre Zeiteinträge weiter zu kategorisieren und zu kennzeichnen, so dass Sie sie schneller finden und Ihre Flexibilität in Bezug auf Analysen verbessern können.
Sobald die Datentypen eingerichtet sind, senden wir eine POST-Anfrage an die Start-URL für die Verfolgung, wobei wir die Aktivitäts-ID als Pfadvariable festlegen, damit unsere API weiß, welche Aktivität mit der Verfolgung beginnen soll.
Das Beenden der Verfolgung ist dem Starten sehr ähnlich, nur dass wir diesmal ein stopped_at-Datum senden und die Aktivitäts-ID nicht in der URL angeben müssen, da es zu jedem Zeitpunkt nur eine aktive Verfolgung geben kann.
Die StopTrackingResponse enthält einen vollständigen TimeEntry, der einem Tracking ähnelt, mit dem Unterschied, dass er auch ein Duration-Objekt enthält, das das Von- und Bis-Datum des beendeten Zeiteintrags enthält.
Super! Jetzt können wir also Zeiteinträge erstellen. Lassen Sie uns zum Abschluss dieses Tutorials einen Bericht von der API abrufen.
Berichte
Es gibt mehrere Möglichkeiten, mit der öffentlichen API Timeular einen Bericht zu erstellen. Wenn wir zu Zeiterfassung -> Berichte gehen, können wir zwei Endpunkte sehen.
Eine davon ist die Erstellung eines Dateiberichts, bei dem entweder eine CSV- oder eine XLSX-Datei erstellt wird. Die andere Option ist ein JSON-Bericht.
In diesem Fall entscheiden wir uns für einen einfachen CSV-Bericht, den wir dann zur Analyse verwenden können. Hier ist zu beachten, dass Dateiberichte eine Pro-Funktion in Timeular sind. Wenn Sie jedoch gerade erst ein Konto erstellt haben, können Sie in der App einfach ein Probeabonnement starten, mit dem Sie einen Monat lang kostenlos Pro erhalten.
Wir erstellen die Funktion generate_report, die den Bericht abruft und ihn in der in der Variablen REPORT_FILE definierten Datei speichert.
Wie bei den vorherigen API-Aufrufen erhalten wir ein Authentifizierungstoken und senden eine GET-Anfrage an den Endpunkt. In diesem Fall müssen wir die Daten von und bis als Pfadparameter in die URL eingeben. Wir kodieren diese Werte hier fest, aber wenn Sie sie dynamisch generieren wollen, müssen Sie sicherstellen, dass sie in UTC und im oben gezeigten Format vorliegen.
Für diesen speziellen Endpunkt müssen wir auch die Zeitzone festlegen, und der Bericht wird in die von uns angegebene Zeitzone konvertiert. Dies erleichtert Ihre eigene Analyse, da Sie die Zeiten nicht manuell in Ihre Zeitzone umrechnen müssen.
Sobald wir eine erfolgreiche Antwort erhalten, verwenden wir Tokio's fs::write, um die zurückgegebenen Bytes in die Datei zu schreiben.
Das war's! Jetzt können wir die Datei öffnen und sehen, ob alles so ist, wie wir es erwarten.
Sie können es mit ausführen:
Der gesamte Code für dieses Beispiel ist hier zu finden.
Schlussfolgerung
Dies ist der Abschluss unserer ersten Reise in die Welt der öffentlichen API Timeular . Ich hoffe, wir konnten Ihnen einen kleinen Einblick in die vielen Möglichkeiten geben, die die API eröffnet.
In diesem Artikel haben wir uns angeschaut, wie man mit der Timeular API Daten abrufen kann. Im nächsten Artikel werden wir uns unsere brandneue Webhooks-API ansehen, die eine Zwei-Wege-Kommunikation ermöglicht und Ihnen noch mehr Möglichkeiten zur Erstellung von Automatisierungstools mit Timeular bietet.
Bleiben Sie dran. 🙂