Data ophalen in segmenten

Soms geven API’s niet alle regels terug, maar bijvoorbeeld alleen de eerste honderd regels. Om deze reden is het dan nodig om de data op te halen in delen totdat alle regels opgehaald zijn. Wanneer een API slechts een deel van de regels in één keer aanbiedt zal er in de response vaak een property te vinden zijn op basis waarvan een nieuw verzoek kan worden samengesteld.

In zo’n geval heeft de externe bron meestal de mogelijkheid om in de aanroep (URL) te specificeren dat je een specifiek segment/pagina wilt ophalen van de data. U-Turn Studio ondersteunt de mogelijkheid om dit bij een bron op te geven.

Vanuit het bouwblok waarmee je data op kan halen zijn twee onderdelen beschikbaar waar informatie uitgehaald kan worden. Dit kan bijvoorbeeld een bepaalde response header zijn, maar ook een property uit de response body.
Deze twee onderdelen zijn:

response → Type is System.Net.WebResponse (https://learn.microsoft.com/en-us/dotnet/api/system.net.webresponse?view=net-8.0)
responseResult → Type is dynamic

In de invoervelden van het type waarde of berekening kunnen deze onderdelen vervolgens gebruikt worden (in het berekeningen gedeelte). Voorbeelden hiervan zijn response.Headers["Content-Type"] (hierbij wordt een specifieke header uit de response uitgelezen) en responseResult.total_items (dit is de property ‘total_items’ in de response body).

Om op basis van een HTTP response statuscode (https://developer.mozilla.org/en-US/docs/Web/HTTP/Status ) te bepalen of er nog een iteratie plaats moet vinden kan de volgende check gebruikt worden:

PY

if int(response.StatusCode) == 206:
  # berekening

Vervang hierin de 206 voor de statuscode waar je op wil controleren

Voorbeeld Mailchimp data ophalen in delen.

Mailchimp heeft een API die niet standaard alle regels aanbiedt, hierbij dien je dus zelf door het resultaat heen te lopen om alle regels op te halen. De manier om bijvoorbeeld alle members uit een list op te halen ziet er als volgt uit:

https://{mailchimpServer}/3.0/lists/{listId}/members?count=10&offset=0

Hierbij is {mailchimpServer} de specifieke Mailchimp server, {listId} de ID van de lijst die je op wil halen, {number_of_rows} het aantal regels dat in één keer opgehaald wordt, en offset het paginanummer (beginnend bij 0).

Het bouwblok in U-Turn Studio ziet er als volgt uit:

Er zijn drie query parameters aanwezig, list_id, count en offset. De query parameter ‘count’ is gevuld met de koppelingsvariabele {{items_per_page}}, hierin staat het aantal per pagina:

De query parameter offset is gevuld met de volgende berekening:

PY

if 'offset' not in locals():
    offset = 0
    page_number = 0

offset

In het onderdeel ‘Ophalen in delen’ staat het tweede deel van de berekening, hiermee wordt bepaald wanneer alle beschikbare resultaten opgehaald zijn.

Het invoerveld voor Ophalen in delen is gevuld met de volgende berekening:

PY

if 'offset' not in locals():
    offset = 0
    page_number = 0

#Property in de body waar het totaal aantal items in staat
total_items = responseResult.total_items

resultIteration = False
items_per_page = {{items_per_page}}

if(total_items!=None):
    total_items_numeric = int(total_items)
    page_number+=1
    offset = page_number*int(items_per_page)

    if offset<total_items_numeric:
        resultIteration = True
    else:
        resultIteration = False

resultIteration

In deze berekening wordt verwezen naar de query parameter ‘offset’ (regel 1) en de koppelingsvariabele {{items_per_page}} (regel 7). Zorg dat je deze zo nodig aanpast naar hoe je deze onderdelen zelf genoemd hebt.

Het resultaat van de twee bovenstaande berekeningen is dat de query parameter ‘offset’ steeds opgehoogd wordt, totdat het aantal opgehaalde regels gelijk is aan total_items. Per API zal deze property mogelijk anders heten. Zorg dat je op regel 6 (responseResult.total_items) de waarde aanpast naar de property in de response die het aantal regels aangeeft.

Voorbeeld Microsoft Graph data ophalen in delen

De API voor Microsoft Graph is gebaseerd op oData. Volgens deze specificatie maken de gebruik van het veld nextLink welke door de API wordt teruggegeven. Bijvoorbeeld, een GET aanroep naar https://graph.microsoft.com/v1.0/users?$select=id levert het volgende resultaat op:

JSON

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,accountEnabled,userPrincipalName,displayName,givenName,surname,jobTitle,department,employeeId,country,mailNickname,officeLocation,employeeHireDate)",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$select=id&$skiptoken=XXNwdAoAAQAAAAAAAAAAFAAAAOzGH40ct9VKhf-XVbvCR2sBAAAAAAAAAAAAAAAAAAAXMS4yLjg0MC4xMTM1NTYuMS40LjIzMzEGAAAAAAABss7PEK4rL02gO0454kK0NwF0AAAAAQIAAAA",
    "value": [
        {
            "id": "xxb637c3-d48a-4892-8826-5e9560b17ed7",
            "accountEnabled": false,
            "userPrincipalName": "x",
            "displayName": "y",
            "givenName": null,
            "surname": null,
            "jobTitle": null,
            "department": null,
            "employeeId": null,
            "country": null,
            "mailNickname": "z",
            "officeLocation": null,
            "employeeHireDate": null
        }
    ]
}

Dit resultaat geeft de nextLink terug: https://graph.microsoft.com/v1.0/users?$select=id&$skiptoken=XXNwdAoAAQAAAAAAAAAAFAAAAOzGH40ct9VKhf-XVbvCR2sBAAAAAAAAAAAAAAAAAAAXMS4yLjg0MC4xMTM1NTYuMS40LjIzMzEGAAAAAAABss7PEK4rL02gO0454kK0NwF0AAAAAQIAAAA . Deze URL verwijst naar de volgende pagina met resultaten.

In U-Turn kunnen we niet exact deze URL overnemen in het URL veld. De query parameter “$select“ zou dan namelijk voor een tweede keer toegevoegd gaan worden. We kunnen wel de skiptoken eruit nemen en deze aan de query parameters toevoegen.

In de query parameters voegen we toe:

PY

if 'skiptoken' not in locals():
    skiptoken = ''
skiptoken

En in het script voor het ophalen in delen:

PY

def get_query_parameter(url, parameter_name):
    query_start = url.find('?')
    if query_start == -1:
        return None
    query_string = url[query_start + 1:]
    parameters = query_string.split('&')
    for param in parameters:
        key_value = param.split('=')
        if len(key_value) == 2 and key_value[0] == parameter_name:
            return key_value[1]
    return None
doPage = False
nextLink = str(responseResult['@odata.nextLink'])
skiptoken = ''
if nextLink != None and nextLink!='' :
    if 'https://graph.microsoft.com/v1.0/users' in nextLink:
        skiptoken = get_query_parameter(nextLink, '$skiptoken')
        if skiptoken != None and skiptoken!='' :
            doPage = True
doPage