Als u een directe verbinding wilt maken tussen uw bronsystemen en de OneStream omgeving zonder ingewikkelde netwerkconfiguraties of onderhoudsgevoelige IP whitelisting, dan is de REST API uw beste keuze. Steeds meer klanten gebruiken REST API technologie om hun data integratie te automatiseren, waardoor processen sneller en eenvoudiger verlopen. De RESTful API, of REST API, gebruikt HTTP-verzoeken om rechtstreeks te communiceren met andere webservices zonder extra aanpassingen aan het netwerk. Deze verbinding werkt dus direct, zonder extra veranderingen aan de infrastructuur!
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:
Client gebruiken als nieuwe HttpClient()
' Autorisatie headerinstellen
client.DefaultRequestHeaders.Add("Autorisatie", "Bearer " & sBearerToken)
' Verzoektekst maken
Dim dRestAPIParameters Als Nieuw Woordenboek(Of String, Object)()
dRestAPIParameters.Add("Periode", "2024M10")
dRestAPIParameters.Add("Entiteit", "Groningen")
' Converteer de request body naar het juiste formaat, application/json in UTF8
Dim jsonRestAPIParameters Als String = JsonConvert.SerializeObject(dRestAPIParameters)
Dim inhoud Als Nieuwe StringContent(jsonRestAPIParameters, Encoding.UTF8, "application/json")
POST-verzoek verzenden
Probeer
Dim respons als HttpResponseMessage = client.PostAsync(url, content).Result
Als het verzoek succesvol is
Als response.IsSuccessStatusCode Dan
Dim responseBody als String = response.Content.ReadAsStringAsync().Result
Als responseBody.Length > 0
Return JObject.Parse(responseBody)("Status")
Else 'responseBody.Length > 0
Gooi een nieuwe XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Stuur niets terug
End If 'responseBody.Length > 0
Als het verzoek mislukt
Else 'response.is-successtatuscode
Gooi een nieuwe XFException($"{response.StatusCode} - {response.ReasonPhrase}")
Stuur niets terug
End If 'response.isSuccessStatusCode
Vang ex als uitzondering
Gooi ErrorHandler.LogWrite(si, New XFException(si, ex))
Einde poging
Einde Gebruik 'client Als Nieuwe HttpClient()
Het POST verzoek kan fungeren als een trigger om een bepaalde dataset te genereren op basis van de parameters in het verzoek. Nadat deze dataset is gegenereerd, kan een GET REST API worden gebruikt om de dataset in JSON formaat op te halen en direct te importeren in de OneStream Import stappen 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 moe bent van het handmatig overzetten van CSV-bestanden van het ene systeem naar het andere en meer wilt weten over de mogelijkheden van REST API in combinatie met OneStream voor het automatiseren van integratie, aarzel dan niet om contact met mij of mijn collega's op te nemen.
