Als je een directe verbinding wilt maken tussen je bronssystemen en de OneStream omgeving zonder ingewikkelde netwerkconfiguraties of onderhoudsgevoelige IP whitelisting, dan is de REST API je beste keuze. Steeds meer klanten gebruiken REST API technologie om hun data-integratie te automatiseren, waardoor processen sneller en eenvoudiger worden. De RESTful API, of REST API, gebruikt HTTP requests om direct te communiceren met andere webdiensten zonder extra aanpassingen aan het netwerk. Deze verbinding werkt dus direct, zonder extra infrastructuurwijzigingen!
Om gebruik te maken van de RESTful API technologie binnen het OneStream platform, kan een Extensibility Business Rule gemaakt worden die deze requests uitvoert.
REST verzoek
Zie het volgende codefragment dat een voorbeeld laat zien van een geparametriseerd REST API POST verzoek:
Using client As New HttpClient()
‘ Set authorization header
client.DefaultRequestHeaders.Add("Authorization", "Bearer " & sBearerToken)
' Create request body
Dim dRestAPIParameters As New Dictionary(Of String, Object)()
dRestAPIParameters.Add("Period", "2024M10")
dRestAPIParameters.Add("Entity", "Groningen")
' Convert the request body to the correct format, application/json in UTF8
Dim jsonRestAPIParameters As String = JsonConvert.SerializeObject(dRestAPIParameters)
Dim content As New StringContent(jsonRestAPIParameters, Encoding.UTF8, "application/json")
'Send POST request
Try
Dim response As HttpResponseMessage = client.PostAsync(url, content).Result
'If the request is successful
If response.IsSuccessStatusCode Then
Dim responseBody As String = response.Content.ReadAsStringAsync().Result
If responseBody.Length > 0 Then
Return JObject.Parse(responseBody)("Status")
Else 'responseBody.Length > 0
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'responseBody.Length > 0
'If the request fails
Else 'response.IsSuccessStatusCode
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'response.IsSuccessStatusCode
Catch ex As Exception
Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
End Try
End Using 'client As New HttpClient()
De POST request kan fungeren als trigger om een bepaalde dataset te genereren op basis van de parameters die in het request zijn meegeleverd. Nadat deze dataset is gegenereerd, kan een GET REST API worden gebruikt om de daadwerkelijke dataset op te halen in JSON formaat en deze direct te importeren in de OneStream Import steps van je workflows.
Beveiliging
Het voor de hand liggende nadeel van deze REST API is dat het direct toegankelijk is via het internet, waardoor een beveiligde verbinding cruciaal is. Een eenvoudige combinatie van een native gebruikersnaam en wachtwoord (Basic Authentication header) is niet langer voldoende. Voor onze klanten hebben we OneStream geconfigureerd om betere authenticatiemethoden te gebruiken om REST API verzoeken te verifiëren.
Een voorbeeld van een van deze methoden is het OAUTH 2.0 protocol. Dit maakt gebruik van een zogenaamd authenticatietoken, waarmee gebruikers toegang kunnen krijgen tot API's zonder telkens opnieuw hun inloggegevens in te voeren. Om het OAuth authenticatie token te verkrijgen, kan dezelfde Extensibility Business Rule worden gebruikt, waarin een basis gebruikersnaam en wachtwoord worden doorgegeven om uiteindelijk een token te ontvangen. Deze tokenstring kan dan worden gebruikt als een Bearer Token eigenschap in de Authorization header van het oorspronkelijke verzoek.
Het onderstaande codefragment toont een voorbeeld van een REST API POST-verzoek, waarbij de respons het gegenereerde OAuth-toegangstoken bevat.
' Define basic credential header for request
Dim sUsername As String = "JWisAwesome"
Dim sPassword As String = "S@nd3r1sG3k"
Dim credentials As String = Convert.ToBase64String(Encoding.ASCII.GetBytes(sUsername & ":" & sPassword))
' Create OAuth token request
Using client As New HttpClient()
'Create the Header of the request
client.DefaultRequestHeaders.Add("Authorization", "Basic " & credentials)
'Create the Body of the request
Dim postbody As String = "grant_type=" + "client_credentials" + "&scope=" + "https://graph.microsoft.com/.default"
Dim content As New StringContent(postbody, Encoding.UTF8, "application/x-www-form-urlencoded")
' Send POST request to Oracle Cloud
Try
Dim response As HttpResponseMessage = client.PostAsync(url, content).Result
'If the request is successful
If response.IsSuccessStatusCode Then
Dim responseBody As String = response.Content.ReadAsStringAsync().Result
If responseBody.Length > 0 Then
Return JObject.Parse(responseBody)("access_token")
Else 'responseBody.Length > 0
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'responseBody.Length > 0
'If the request failed
Else 'response.IsSuccessStatusCode
Throw New XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Return Nothing
End If 'response.IsSuccessStatusCode
Catch ex As Exception
Throw ErrorHandler.LogWrite(si, New XFException(si, ex))
End Try
End Using 'client As New HttpClient()
Dit is slechts één voorbeeld van een REST API binnen OneStream. De mogelijkheden voor het integreren van RESTful technologie binnen het OneStream platform zijn eindeloos.
Conclusie
Als je genoeg hebt van het handmatig overzetten van CSV-bestanden van het ene systeem naar het andere en meer wilt weten over de potentie van REST API in combinatie met OneStream voor het automatiseren van integratie, neem dan gerust contact op met mij of mijn collega's.
