Erkunden der Planview AgilePlace APIs mit Postman

Durch die Nutzung der Planview AgilePlace Application Programming Interface (API) steht jedem Planview AgilePlace-Benutzer eine Fülle von Informationen zur Verfügung. Die API kann verwendet werden, um Statusinformationen für einen benutzerdefinierten Bericht zu extrahieren, Routineaufgaben wie das Verschieben oder Aktualisieren einer Karte zu automatisieren, Daten mit einem anderen System zu synchronisieren und viele andere nützliche Aufgaben durchzuführen.

Wenn Sie jedoch noch nie mit einer API gearbeitet haben, können die ersten Schritte ein wenig überwältigend sein. Zum Glück gibt es großartige Tools, die Ihnen die Arbeit erleichtern. In diesem Artikel werden wir uns eines meiner Lieblings-API-Tools ansehen, Postman.

Postbote holen

Wenn Sie Google Chrome haben, können Sie Postman als Chrome-Erweiterung erhalten. Wenn Sie einen Mac verwenden, können Sie Postman als Desktop-Anwendung erhalten. Ich erwarte, dass Postman in Zukunft eine Windows-Desktop-Anwendung herausbringen wird.

Nach der Installation sollten Sie den Anforderungsbildschirm "Builder" sehen.

Ihre erste API-Anfrage stellen

Für Ihre erste API-Anfrage werden wir eine Liste von Boards von Ihrem Konto abrufen.

Geben Sie Ihre Konto-URL und Ihre Anmeldedaten ein

Geben Sie die URL für die Anfrage ein. In diesem Beispiel lautet die URL https://demoarea.leankit.com/kanban/api/boards. Wir müssen demoarea durch den Namen unseres Planview AgilePlace-Kontos ersetzen.
Klicken Sie auf die Registerkarte Autorisierung, falls sie nicht bereits ausgewählt ist.
Ändern Sie "Keine Autorisierung" in "Einfache Autorisierung".
Geben Sie die E-Mail-Adresse Ihres Kontos und Ihr Passwort ein.
Klicken Sie auf die Schaltfläche "Anfrage aktualisieren".

Aktualisieren Sie die Kopfzeilen der Anfrage

Klicken Sie auf die Registerkarte Kopfzeilen.
Fügen Sie zwei Kopfzeilen hinzu: Content-Type und Accept mit dem Wert application/json.

Wenn Sie die Header Content-Type und Accept setzen, weiß die API, dass alle von uns gesendeten Daten im Format JavaScript Object Notation (JSON) vorliegen und dass alle zurückgegebenen Daten ebenfalls im JSON-Format vorliegen sollten.

Senden Sie die Anfrage

Wir sind jetzt bereit, den Antrag zu stellen! Klicken Sie auf die Schaltfläche "Senden". Solange die URL und die Kontoinformationen korrekt sind, sollten wir etwas wie das folgende Bild sehen.

Eine Antwort von der API hat fast immer das folgende Format:

Wir sollten nun eine Liste der Boards haben, die die Id, Title, Description, CreationDate (Datum, an dem das Board erstellt wurde) und andere grundlegende Informationen enthält.

Eine einzelne Karte anfordern

Jetzt, da wir unsere Liste der Boards haben, können wir die Id eines Boards verwenden, um ein einzelnes Board mit all seinen Details wie Benutzern, Lanes und Karten zu erhalten.

Aus der Liste der Boards in der vorherigen Anfrage kopieren wir die Id eines Boards. Aktualisieren Sie die Anfrage-URL, indem Sie am Ende einen Schrägstrich (/) und die Id der kopierten Karte hinzufügen. Unsere Anfrage-URL sollte etwa so aussehen: https://myaccount.leankit.com/kanban/api/boards/1234.
Klicken Sie auf die Schaltfläche "Senden".

Datenblöcke komprimieren

Postman formatiert die JSON-Daten nicht nur, um sie besser lesbar zu machen, sondern erleichtert auch das Zusammenfassen von Datenabschnitten, so dass Sie sich auf die Informationen konzentrieren können, die Ihnen wichtig sind. Um Datenblöcke zu komprimieren oder zu erweitern, klicken Sie auf den Pfeil auf der linken Seite.

Speichern Sie die Anfrage

Eine der schönen Funktionen von Postman ist die Möglichkeit, Anfragen zu speichern, so dass wir sie später wiederverwenden können. Lassen Sie uns die Anfrage für den Vorstand speichern, damit wir in Zukunft nicht mehr all diese Schritte durchlaufen müssen.

Klicken Sie auf die Schaltfläche Speichern.
Wählen Sie eine Sammlung aus oder erstellen Sie eine neue Sammlung. Eine Sammlung ist wie ein Ordner zum Speichern Ihrer Anfragen. Wir können eine neue Sammlung erstellen, indem wir einen Namen unter "...oder eine neue Sammlung erstellen" eingeben.
Geben Sie einen beschreibenden Namen für die Anfrage ein.
Klicken Sie auf die Schaltfläche "Zur Sammlung hinzufügen".

Suche nach Karten

Für unseren nächsten Trick werden wir auf nach Karten suchen.

Ändern Sie den Anfragetyp von GET in POST.
Aktualisieren Sie die URL der Anfrage und ändern Sie myaccount in unseren Kontonamen und 1234 in unsere Board-ID.
https://myaccount.leankit.com/kanban/api/board/1234/searchcards
Anmerkung:/board/ in dieser URL ist Singular statt Plural, wie in früheren Anfragen.
Klicken Sie auf die Registerkarte "Körper".
Wählen Sie das Format "Rohdaten".
Aktualisieren Sie den Body mit dem folgenden JSON:
{ "searchOptions": { "SearchTerm": "Verkauf", "Seite": 1 } }
Hinweis: Ändern Sie den Suchbegriff in einen beliebigen Text, der mit dem Titel oder der Beschreibung einer Karte auf Ihrem Board übereinstimmen würde. Eine Liste aller Such- und Filteroptionen finden Sie in der Dokumentation Search Cards.
Klicken Sie auf "Senden", um die Anfrage abzuschicken.

Suchergebnisse

Es ist wichtig, darauf hinzuweisen, dass das von der Kartensuche zurückgegebene JSON die folgenden Informationen enthält.

Eigentum	Wert
TotalResults	Die Gesamtzahl der Karten, die der Suche entsprechen.
Page	Die aktuelle "Seite" oder Ergebnisse.
MaxResults	Die maximale Anzahl von Karten, die von der Suchanfrage zurückgegeben werden.

Wenn die Anzahl der Karten, die mit Ihrer Suche übereinstimmen, den Wert MaxResults übersteigt, werden Ihre Ergebnisse in "Seiten" aufgeteilt, die separate Anfragen erfordern.

Wenn unsere Suche zum Beispiel 33 Karten gefunden hat (" TotalResults": 33), werden nur die ersten 20 Karten zurückgegeben. Um die anderen 13 Karten zu erhalten, müssen wir den Text der Anfrage wie folgt ändern und erneut abschicken.

Wie man eine Karte aktualisiert

Für das nächste Beispiel werden wir eine Karte aktualisieren. Wir können die meisten Informationen auf einer Karte ändern, wie z.B. den Titel, die Beschreibung, das geplante Startdatum, das geplante Enddatum und die zugewiesenen Benutzer, um nur einige zu nennen.

Zumindest müssen wir die ID der Karte kennen. Wir können diese ID auf verschiedene Weise erhalten. Wir können die API verwenden, um die Karte abzurufen oder nach Karten zu suchen, wie in den vorherigen Beispielen, oder wir können die Karten-ID auf der Karte selbst in der unteren, rechten Ecke finden.

Als nächstes aktualisieren wir unsere Anfrage.

Ändern Sie den Anfragetyp in POST.
Aktualisieren Sie die URL der Anfrage und ändern Sie myaccount in den Namen unseres Kontos.
https://myaccount.leankit.com/kanban/api/card/update
Klicken Sie auf die Registerkarte "Körper".
Wählen Sie das Format "Rohdaten".
Aktualisieren Sie den Body mit dem folgenden JSON:
{ "CardId": 123456, "Titel": "Aktualisiert über die API" }
Hinweis: Ändern Sie den Wert CardId entsprechend der ID der Karte, die Sie aktualisieren, und Title in den gewünschten Text. Oder aktualisieren Sie ein anderes Feld. Eine Liste aller aktualisierbaren Felder finden Sie in der Dokumentation Update Card.
Klicken Sie auf "Senden", um die Anfrage abzuschicken.

Bei Erfolg enthält die API-Antwort die aktualisierten Karteninformationen.

Geschrieben von Planview Blog

Planview Blog