Simployer Analytics API
Analytics API är ett REST API som gör det möjligt för våra kunder att läsa och analysera sina Simployer HRM-data. Analytics API implementerar OData öppen standard. Det kan nås via olika tredjepartsverktyg som Excel, Power BI, samt användas i kundens interna system.
Hur man använder Analytics API
URL
Dokumentation/testsite (se Swagger UI-avsnittet senare i dokumentet):
Användning i Self-Service BI-verktyg
För specifika SSBI-verktyg bör användaren kontrollera om det stödjer OData Feed. Alternativt kan API:et behandlas som vanliga REST-endpunkter, men notera att API:et har pagineringsmekanism och begränsning på antal resultat per förfrågan (se FAQ avsnittet för mer info).
Autentiseringsmetod
Analytics API stödjer SimplAuth autentiseringsprotokoll.
Se denna sida för mer detaljer: SimplAuth.
Excel, Power BI
Nedan finns exempel på hur man autentiserar och ansluter till Analytics API med Excel. För Power BI är det liknande eftersom båda använder Power Query.
Detta är ett bra sätt att börja interagera med Analytics API. Det finns en mer detaljerad guide för hur man ställer in Power Query för autentisering och datahämtning här: Connect API through Power Query.
Gå till Data > Hämta data > Från andra källor > Från webben
I popup-fönstret väljer du "Avancerat" och anger nödvändig info som nedan:
Nytt fönster öppnas med hämtade data:
Därefter kan du borra ner och konvertera svaret till tabell.
OData-standard
Analytics API är ett REST API baserat på öppen dataprotoKoll OData V4. Protokollet tillåter flera funktioner:
$filter - begränsar mängden returnerade objekt. Max 100 uttryck.
$orderby - specificerar ordningen på returnerade objekt.
$top - begränsar antalet returnerade objekt.
$skip - exkluderar angivet antal objekt från resultatet.
$count - anger om totalantal objekt i samlingen ska returneras.
$expand - inkluderar relaterade entiteter inline. Max djup är 2.
$select - begränsar vilka egenskaper som returneras.
Alla funktioner beskrivs i OData-dokumentationen här: https://
ChatGPT said:
www.odata.org/getting-started/basic-tutorial/. Se nedan för vanliga användningsområden.
Swagger UI
Lösningen har integrerad Swagger UI som låter användaren testa API:et innan anslutning i valfritt BI-verktyg.
Översikt över Swagger UI
Alla tillgängliga endpoints visas i Swagger UI, inklusive tillhörande scheman. Exempel med begränsade entiteter:
När ett schema expanderas visas detaljer om varje egenskap. Referenser till andra entiteter är också expanderbara – se t.ex. absences, immediateSupervisor, affiliationUnit, employees och directReports nedan. Dessa kan användas med OData $expand för att inkludera relaterade entiteter i resultatet.
Användning av Swagger UI
För att använda Swagger UI måste användaren vara auktoriserad. Detta görs med knappen Authorize över endpoint-listan. Du ombeds då att autentisera dig.
När du är auktoriserad kan du testa endpoints med knappen Try it out. Exempel:
I exemplet vill vi hämta en Person (sk = 1) inklusive Affiliation Unit-detaljer. För båda entiteterna begränsas de returnerade egenskaperna. Exempel på svar
FAQ
Jag får Unauthorized (401) fel när jag försöker ansluta till OData-endpunkt.
Följ instruktioner för ditt verktyg:
Webbläsare: Kan inte användas för OData-endpunkt. Använd endast i specialiserade appar (Excel, Power BI osv.). För datamodell i webbläsare, använd Swagger UI (se URL ovan).
BI-verktyg: Kontrollera inställningarna som beskrivs i Excel, Power BI-sektionen.
Swagger UI: Kontrollera att du angav rätt token via Authorize-knappen.
Kontrollera att du använder rätt audience (https://analytics-api.simployer.com) vid generering av SimplAuth-token. Token för andra audience (t.ex. HrConnect) fungerar ikke.
Var hittar jag dokumentation för datamodellen?
Dokumentation för datamodellen finns tillgänglig i Swagger UI (avsnittet "Schemas", strax under listan med endpoints).
Hur använder man filter i en fråga?
För att använda filterfunktionen måste du använda nyckelordet "$filter" i din fråga. Du kan hänvisa till OData’s grundläggande handledning här. Till exempel, om du endast vill välja Person med förnamn "Anna", kan du använda detta filter:v1/Person?$filter=firstName eq 'Anna'
Det finns även andra logiska filteroperatorer att använda. Du hittar en lista över dessa i dokumentationen för OData URL-konventioner.
Hur inkluderar man relaterade entiteter i resultatet?
För att använda denna funktion, måste du använda nyckelordet "$expand" i din fråga. Du kan hänvisa till OData’s grundläggande handledning här. Se avsnittet Using Swagger UI ovan – samma tillvägagångssätt kan användas i vilket verktyg som helst som stödjer OData-endpoints.
När du hämtar data för en entitet som har definierade relationer (t.ex. Person som i tidigare exempel), kan du även få extra kolumner i Excel (t.ex. affiliationUnit):
URL:https://analytics-api.simployer.com/v1/person?$filter=sk eq 1
Men om du försöker expandera dem genom att klicka, kommer du att se att de inte är ifyllda:
För att åtgärda detta, inkludera nyckelordet $expand och ange vilken entitet du vill expandera:
URL:https://analytics-api.simployer.com/v1/person?$filter=sk eq 1&$expand=affiliationUnit
Mitt dataset är stort, och det verkar som om jag inte får all data från endpointen. Varför?
Vårt API använder OData’s sidindelningsmekanism (paging). Det innebär att du bara kan få ett begränsat antal poster per fråga. Denna gräns är för närvarande satt till 100 000 rader.
Generellt hanteras detta automatiskt av OData-kopplingar (t.ex. Power BI). Om du använder API:et manuellt har du två alternativ för att hämta nästa sida:
Använd fältet @odata.nextLink från svaret för att få URL till nästa sida med poster
Använd $skip i din fråga för att hämta nästa sida manuellt
Jag får svarskod 429 (Too Many Requests)
Analytics API tillämpar begränsningar i antalet anrop för att förhindra överbelastning och säkerställa god prestanda för alla våra kunder – för närvarande är gränsen 30 förfrågningar per minut.
Var artikeln till hjälp?
Toppen!
Tack för din feedback
Vi beklagar att det inte var till hjälp
Tack för din feedback
Feddback skickat
Vi uppskattar din feedback och uppdaterar artikeln vid behov