Wie kann ich über die API Datensätze für einen bestimmten Zeitraum abrufen?

[Moritz]

Mit den regulären API-Routen für den Abruf von Datensätzen kann ich zwar Datensätze für unterschiedliche Versionen abrufen (und damit auch einen gewissen Zeitraum eingrenzen). Möchte ich aber gezielt Datensätzen innerhalb bestimmter Zeiträume abrufen, helfen die Standardrouten hier nicht.

Genau für diesen Fall gibt es in der sogenannten Preview-API aber die Möglichkeit, nach Datumswerten zu filtern und damit die Suche gleich auf spezifizierbare Zeiträume zu beschränken. Aber wie genau geht das?

Zunächst einmal ist es erforderlich, dass wir uns für einen Datumswert entscheiden, denn ein Datensatz hat verschiedene Zeitstempel, nach denen wir filtern können (es kann auch nach mehreren, unterschiedlichen Zeitstempeln gleichzeitig gefiltert werden):

• clientCreatedDate ist der Zeitpunkt, zu dem der Entwurf vom User auf dem Endgerät geöffnet wurde
• sendDate ist der Zeitpunkt, zu dem der Datensatz vom User abgesendet wurde
• recievedDate ist der Zeitpunkt, zu dem der Datensatz an den smapOne-Servern empfangen wurde
• completedDate ist der Zeitpunkt, zu dem der Datensatz von den smapOne-Servern verarbeitet wurde (Daten gespeichert, alle Assets hochgeladen etc.)
• lastExportDate zeigt den Zeitpunkt an, zu dem der Datensatz exportiert wurde (sofern er auch schon exportiert wurde, sonst null)

Und in der Preview-API kann ich nun nach Datensätzen suchen und hierbei den Zeitraum definieren, in dem die Datensätze liegen. Zum Beispiel im folgenden Fall einfach und simpel alle Datensätze, die nach dem 10. November um 11:05 Uhr (UTC) an der Plattform angekommen ("received") wurden. "gt" steht in hierbei für "greater than", sinngemäß "später als":

/Backend/preview/Smaps/{smapId}/Records?$filter=ReceivedDate gt 2020-11-10T11:05:00Z

Mit Hilfe dieser Filtermöglichkeiten in den API-Routen der Preview-API können also sehr gezielt Metadaten von smap-Daten gefiltert werden - in diesem Fall nach Zeitstempeln. Aber auch weitere Filtermöglichkeiten sind vorhanden. Weitere Beispiele können direkt in der Preview-API eingesehen werden.

• zur Swagger-API-Dokumentation
• zur FAQ: "Wie wähle ich in der Swagger API-Dokumentation die Preview-API aus?"

Falls ihr weitere Fragen zur Preview-API habt, haut sie gerne als Kommentare unter diesen Beitrag. Wenn es andersgeartete Fragen sind, macht gerne einen eigenen Beitrag hier im Forum auf.

[Philip Alvermann]

Diese Filter sind eine feine Sache, ich hätte das gerne auch zum löschen von Records.

Das Ziel wäre, nicht mehr benötigte Aufgaben über einen Filter zu entfernen.
z.B. der Mitarbeiter ist ausgeschieden und ein weiterleiten der Aufgaben ist nicht sinnvoll.

[Moritz]

Lieber @Philip Alvermann, das geht auch, allerdings nicht in einem Schritt/mit einer API-Route. Sie könnten wie folgt vorgehen:

1. Abruf aller betroffenen Datensätze mit dem gewünschten Filter - als Resultat gibt die API ein Array mit JSON-Objekten zurück. Ein Attribut in dem JSON-Objekt ist die Record-ID (siehe Screenshot oben in meinem Beitrag).
2. Anschließend kann über dieses Array iteriert werden und dann für jeden Iterationsdurchgang einfach die API-Route zum Löschen von Datensätzen aufgerufen und dabei die jeweilige Record-ID übergeben werden, die in der Schleife aktuell ist.

Mit welchem Instrument/Tool wollen Sie die o.g. Löschung durchführen? PowerAutomate? Script? Integrationsmiddleware?

[Philip Alvermann]

Vielen Dank, mir klar das sowas immer geht. Hier wäre dann wieder eine weitere Hürde zu nehmen:

Rate limiting
When accessing the REST API via Access Token, the rate is limited to a maximum of 60 requests per minute. If this limit is exceeded, all further requests will be rejected with HTTP status 429 ("Too Many Requests") by the server until the full minute has expired. In addition, the server informs the requesting service via "Retry-After" header when accesses are allowed again.

Da ich das löschen bisher nur zweimal benötigt habe, würde ich da nichts bauen wollen.

Das oben genannte Webinterface (Swagger) wäre für solche Sachen meine erste Wahl.

Trotzdem vielen Dank

[Moritz]

vor 3 Stunden schrieb Philip Alvermann:

Vielen Dank, mir klar das sowas immer geht.

Nur dass ich Sie richtig verstehe, @Philip Alvermann: Sie würden sich eine API-Route wünschen, in der man – ähnlich wie beim GET-Abruf – gleich über einen Filter ausgewählte Datensätze löschen kann, ohne jeweils die Single-Delete-Route ansprechen zu müssen?

Für das Problem mit dem 429er-Error (allgemeine Hinweise für alle Mitlesende finden sich übrigens in der Doku) : Ja klar, gerade wenn man hier über eine große Anzahl von Datensätzen iteriert, tritt – je nach Systemstärke und gewählter Programmiersprache – mehr oder weniger schnell dieser Fehler auf. Es hilft leiter nichts, das muss abgefangen werden, z.B. indem man das Script um die Anzahl der Sekunden (+ ggf. 1 Sekunde Sicherheitspuffer o.ä.) pausiert, die die API zusammen mit dem 429er-Error zurückgibt:

vor 3 Stunden schrieb Philip Alvermann:

In addition, the server informs the requesting service via "Retry-After" header when accesses are allowed again.

P.S. So wie ich Sie erlebt hatte, wissen Sie um diesen Trick auch schon längst. Ich habe ihn eher der Vollständigkeit halber für alle Interessierte hier einmal niedergeschrieben 😉

[Jens Mussler]

wie muss ich im Erweiterten Editor die erste Zeile umschreiben, sodass nur die Daten der letzten 45 Tage abgerufen werden?

Quelle = Json.Document(Web.Contents("https://platform.smapone.com/backend/v1/Smaps/706..../Data?accessToken=...")),

 

Bearbeitet 25. November 2022 von Jens Mussler
Token veröffentlicht

[Philip Alvermann]

Am 21.11.2022 um 14:41 schrieb Moritz:

Nur dass ich Sie richtig verstehe, @Philip Alvermann: Sie würden sich eine API-Route wünschen, in der man – ähnlich wie beim GET-Abruf – gleich über einen Filter ausgewählte Datensätze löschen kann, ohne jeweils die Single-Delete-Route ansprechen zu müssen?

Ja genau so wäre mein Wunsch.

[Moritz]

  Lieber @Jens Mussler,

Am 25.11.2022 um 11:23 schrieb Jens Mussler:

wie muss ich im Erweiterten Editor die erste Zeile umschreiben, sodass nur die Daten der letzten 45 Tage abgerufen werden?

In dem Aufruf an die Preview-API können Sie kein Intervall (z.B. "45 Tage") angeben. Sie können den Filter nur auf ein spezifisches Datum setzen und dabei alle Datensätze z.B. "älter als [Datum]" auswählen.

In Ihrem Fall müssten Sie also in Ihrem Script zunächst einen String erzeugen, der das Datum vor 45 Tagen ermittelt (idealerweise ab Mitternach, 00:00 Uhr) und dann alle Datensätze danach filtert. Vor 45 Tagen ist nach meiner Berechnung der 14. Oktober, also würde Ihr Abruf in etwa so aussehen:

/Backend/preview/Smaps/{smapId}/Records?$filter=CompletedDate gt 2022-10-14T00:00:00Z

Welche Sprache setzen Sie ein? Das sieht mir nach .NET o.ä. aus. Da gibt es doch mit Sicherheit auch einen Befehl für das aktuelle Datum minus 45 Tage...?

 

[Jens Mussler]

vor 6 Stunden schrieb Moritz:

  Lieber @Jens Mussler,

In dem Aufruf an die Preview-API können Sie kein Intervall (z.B. "45 Tage") angeben. Sie können den Filter nur auf ein spezifisches Datum setzen und dabei alle Datensätze z.B. "älter als [Datum]" auswählen.

In Ihrem Fall müssten Sie also in Ihrem Script zunächst einen String erzeugen, der das Datum vor 45 Tagen ermittelt (idealerweise ab Mitternach, 00:00 Uhr) und dann alle Datensätze danach filtert. Vor 45 Tagen ist nach meiner Berechnung der 14. Oktober, also würde Ihr Abruf in etwa so aussehen:

/Backend/preview/Smaps/{smapId}/Records?$filter=CompletedDate gt 2022-10-14T00:00:00Z

Welche Sprache setzen Sie ein? Das sieht mir nach .NET o.ä. aus. Da gibt es doch mit Sicherheit auch einen Befehl für das aktuelle Datum minus 45 Tage...?

 

Ich bin da noch totaler Anfänger und in der Lernphase. Habe mit Ihrer Anleitung https://support.smapone.com/news-releases/details/neues-zur-rest-schnittstelle/ den Datenabruf in Excel erstellt.

Habe in einer anderen Excel-Datei folgenden Quelle gefunden:

/Backend/preview/Smaps/{smapId}/Records?$filter=CompletedDate gt "&DateTime.ToText(Date.AddDays(DateTime.LocalNow(), -45), "yyyy-MM-ddT00:00:00Z")&"&accessToken={API-Token}"),

Wenn ich diesen Versuche auf die andere smapId Abfrage zu übertragen, bekomme ich allerdings einen DataSource.Error angezeigt

[Johanna Becker]

@Moritz kannst Du hier aushelfen? 🙂 

[Moritz]

@Jens Mussler eine DataSource (steht z.B. für einen Datensatzauswahlbaustein, kurz DSAB) sollte eigentlich in Ihrem Abruf keine Rolle spielen (weil sie die smap-Daten abrufen, keine Infos/Daten des DSAB). Kann es sein, dass der Fehler aus einem anderen Teil des Scripts/der Datei kommt? Rufen Sie weitere Routen an der API auf?

[Jens Mussler]

Das ist der Fehler der angezeigt wird...

Zitat

DataSource.Error: Fehler beim Abrufen von Inhalten von "https://platform.smapone.com/backend/v1/Smaps/{smapId}/Records?$filter=CompletedDate%20gt%202022-10-15T00:00:00Z&accessToken={Token}" (404) durch "Web.Contents": Not Found
Details:
    DataSourceKind=Web
    DataSourcePath=https://platform.smapone.com/backend/v1/Smaps/{smapId}/Records
    Url=https://platform.smapone.com/backend/v1/Smaps/{smapId}/Records?$filter=CompletedDate%20gt%202022-10-15T00:00:00Z&accessToken={Token}

 

[Moritz]

@Jens Mussler ein Error 404 weist darauf hin, dass es die smap (in Ihrer Subscription, also mit ihrem Token) nicht gibt. Prüfen Sie bitte einmal, ob dort die richtige smapId eingetragen ist.

Oder nochmal nachgehakt: Müssen Sie ggf. die smapId und das Token in die URL eintragen, dort wo die Platzhalter ({smapId}, {Token}) stehen? Oder werden diese dynamisch bedient?

[Jens Mussler]

@Moritz sowohl die smapId als auch der Token sind korrekt eingetragen.

Was mir nun noch aufgefallen ist. In dem Abruf der funktioniert ist ein Abruf1 erstellt wurden. Kann es damit was auf sich haben?

[Moritz]

@Jens Mussler es ist außerordentlich schwierig, den Fehler "von außen" zu identifizieren — in etwa vergleichbar mit einem Anruf beim Arzt: "Ich habe Schmerzen"; ohne weitere Diagnose wird der Arzt die Ursache nicht feststellen können.

Was ich Ihnen gerne anbieten kann: wenn Sie mir die Excel-Datei zuschicken, kann ich einmal einen Blick auf die Datei werfen. Aber bitte beachten Sie: wenn die Excel-Datei das Token enthält, erhalte ich dieses auch. Sind Sie damit einverstanden, dann schicken Sie mir die Datei gerne so zu. Sie könnten sich z.B. nach Lösung des Problems ein neues Token ausstellen lassen (über die Profileinstellungen in Ihrem Account), das devalidiert dann Ihr altes Token. Alternativ können Sie das Token in der Excel auch entfernen und mir dann die Datei zukommen lassen. Ich schreibe Sie hierzu per Direktnachricht an.