GetConnector (REST/JSON)
Met een GetConnector kun je gegevens ophalen uit een Profit-omgeving. Gebruik de tools op Connect.afas.nl om de request op te bouwen. Hier kun je testen hoe je de parameters kan meegeven in de request.
Voorbereiding:
- Om een GetConnector aan te roepen moet je deze toevoegen aan een App Connector en je moet beschikken over een token voor de App connector.
- Lees de algemene toelichting bij GetConnector XML Bouwen en testen.
- Lees de informatie over de aanroep van de REST-connectoren.
Let op:
Je vindt alle endpoints voor connectoren op de centrale pagina URL's van REST Services.
|
Inhoud |
Meta-info GetConnector raadplegen
Voor elke GetConnector kun je met een Meta-info request informatie van het endpoint opvragen. De response bevat de beschikbare velden, veldtype per veld, labels en de veldlengte per veld. Voor velden met een gekoppelde codetabel zijn ook de waarden uit de codetabel beschikbaar.
Voorbereidingen:
- Je hebt de GetConnector aangemaakt en ingericht.
- Je hebt een app connector aangemaakt en de GetConnector hieraan toegevoegd.
- Je hebt een gebruikers-token van een gebruiker van de app connector.
Meta-info GetConnector raadplegen:
Door '/metainfo/get/' op te nemen in het endpoint kun je deze request uitvoeren. Een volledige metainfo request URL ziet er als volgt uit :
https://12345.rest.afas.online/ProfitRestServices/metainfo/get/Get_Connector_ID
Meta-info GetConnector raadplegen via AFAS Connect:
- Roep de Profit REST Services aan.
- Selecteer de GetConnector en klik op Metainfo om de meta-informatie op te halen.
GetConnector uitvoeren (regels ophalen)
Je voert een GetConnector uit om regels (records) op te halen uit Profit.
GetConnector uitvoeren (regels ophalen):
- Roep de Profit REST Services aan.
- Selecteer de connector.
- Klik op: Execute.
- Je ziet bovenaan de URL van de aanroep.
- Je kunt snel schakelen naar de JSON-indeling.
Regels ophalen in batches
In de request URL kun je de parameters skip en take meegeven. Deze gebruik je in de volgende situaties:
- Je haalt zeer veel data op en je blijft niet binnen de AFAS Online time-out van 15 minuten. Met skip/take haal je de data in meerdere batches op.
- Je haalt data op voor een app waarin je een beperkt aantal records toont. Als de gebruiker naar de volgende pagina gaat haal je meer data op. Hierin gebruik je skip/take als tool voor paging/pagination.
- Je haalt veel data op en je wilt een korte response tijd per request.
Let op: maximale omvang van de take
ls het aantal regels dat wordt opgehaald te groot is, kan er een "Out of Stringspace" of een "Out of memory" foutmelding ontstaan. Om dat te voorkomen, zorg je ervoor dat de Take niet te groot is. Wij adviseren deze deze regel: [Aantal kolommen] x [Aantal regels] < 150.000. Oftewel: kies de Take zo, dat het aantal velden in je GetConnector keer de Take niet groter is dan 150.000. Dit is nu een advies, geen voorschrift. Wel verzoeken we je om je requests na te lopen en waar nodig aan te passen, omdat in de toekomst een limiet aan de maximale omvang van een Get-request ingebouwd zal worden in onze software. Zodra bekend is op welke termijn dit gebeurt, zullen we dit uitgebreid communiceren naar onze klanten.
Regels ophalen in batches:
Aanroep:
<endpoint>/connectors/connectorname?skip=n&take=n
- skip: het aantal records dat moet worden overgeslagen.
- take: het aantal records dat moet worden opgehaald.
Je moet voor elk op te halen pakketje een aparte aanroep doen, tot je een pakketje terugkrijgt dat geen records meer bevat.
Let op:
Gebruik altijd een sortering bij het uitvoeren van een opdracht met skip/take. Sorteer bij voorkeur op een sleutelveld, zoals factuurnummer of medewerkercode, of een combinatie van velden.
Voorbeeld:
Je haalt verlofregels op in pakketjes van 10 regels.
<endpoint>/connectors/Profit_Employee_Leaves?skip=0&take=10&orderbyfieldids=StartDate
<endpoint>/connectors/Profit_Employee_Leaves?skip=10&take=10&orderbyfieldids=StartDate
<endpoint>/connectors/Profit_Employee_Leaves?skip=20&take=10&orderbyfieldids=StartDate
etc.
Regels sorteren
Regels oplopend of aflopend sorteren.
Regels oplopend sorteren
Aanroep:
<endpoint>/connectors/Orderbyfieldids=Field1%2CField2
Tussen de sorteren velden plaats je de code %2C, dit is een komma.
Voorbeeld:
Je haalt verlofregels op en sorteert deze oplopend op begindatum.
../ProfitRestServices/connectors/Profit_Employee_Leaves?orderbyfieldids=StartDate
Regels aflopend sorteren
Plaats een minteken voor het sorteerveld.
Aanroep:
<endpoint>/connectors/Orderbyfieldids=-Field1%2C-Field2
Voorbeeld:
Je haalt verlofregels op en sorteert deze aflopend op jaar en oplopend op medewerker.
<endpoint>/connectors/Profit_Employee_Leaves?orderbyfieldids=-Year%2CEmployeeId
Filter toepassen (algemene uitleg)
Gebruik altijd filters bij het aanroepen van een GetConnector. Dit komt de performance ten goede en je krijgt als resultaat alleen de records die je nodig hebt.
Als je altijd hetzelfde filter wilt toepassen, neem je een vast filter op in de GetConnector in Profit. Hieronder wordt besproken hoe je een filter toepast in de aanroep van de GetConnector.
Filter op één waarde:
Aanroep:
<endpoint>/connectors/connectorname?filterfieldids=[Field]&filtervalues=[Value]&operatortypes=1
- Field = de veldnaam waarop je filtert, bijvoorbeeld Artikelcode, Datum, etc.
- Value=de filterwaarde, bijvoorbeeld artikelcode 1000, de datum 2022-01-01, etc.
- Operatortypes = het
filtercriterium, bijvoorbeeld 'is gelijk aan', 'is groter dan', etc.
Filter maken in AFAS Connect:
Je filtert bijvoorbeeld op artikelcode 1000.
<endpoint>/connectors/Profit_Article?filterfieldids=ItemCode&filtervalues=1000&operatortypes=1
Stel het filter samen in AFAS Connect. De URL wordt automatisch opgebouwd:
Zitten er komma's of puntkomma's in de filterwaardes, gebruik dan een complex filter. Bijvoorbeeld wanneer je filtert op ‘Janssen, Henk’.
De puntkomma of komma in een filterwaarde worden namelijk in de URL meegestuurd als code %2C en code %3B. Je filtering kan onverwachte resultaten geven omdat de komma en puntkomma ook worden gebruikt als scheidingstekens voor EN en OF filteropdrachten. Hierdoor staan deze als %2C en code %3B in de URL.
EN-filter / OF-filter
Uitleg bij filteren op meerdere waarden.
EN-filter op meerdere velden:
Je filtert op meerdere velden en records moeten aan alle filtercriteria voldoen.
Aanroep:
<endpoint>connectors/connectorname?[Field1]%2C[Field2]&[Value1]%2C[Value2]&operatortypes=[Type1]%2C[Type2]
- De aanroep bevat achtereenvolgens de velden, filterwaarden en operatoren. Wil je bijvoorbeeld op drie waarden filteren, dan krijg je drie velden, dan drie filterwaarden en dan drie operatoren.
- Gebruik een komma (code %2C) als scheidingsteken tussen de velden en tussen de filterwaarden.
Stel het filter samen in AFAS Connect. De URL wordt automatisch opgebouwd:
<endpoint>/connectors/Profit_Article?filterfieldids=ModifiedDate%2CArtGroup&filtervalues=2019-01-01T00%3A00%2C100&operatortypes=2%2C1
Houdt er rekening mee dat Gewijzigd op een datum-/tijdveld is.
OF-filter op meerdere velden:
Je filtert op meerdere velden en records moeten minimaal één filtercriterium voldoen.
Aanroep:
<endpoint>/connectors/connectorname?[Field1]%3B[Field2]&[Value1]%3B[Value2]&operatortypes=[Type1]%3B[Type2]
- Dit is een 'is gelijk aan' filter. Het filtercriterium 'is gelijk aan' staat in het veld Operatortypes.
- Gebruik een puntkomma (code %3B) als scheidingsteken tussen de velden en tussen de filterwaarden.
Stel het filter samen in AFAS Connect. De URL wordt automatisch opgebouwd:
<endpoint>/connectors/Profit_Article?filterfieldids=ArtGroup%3BArtGroup&filtervalues=100%3B200&operatortypes=1%3B1
Filter met filtercriteria
Uitleg bij filteren met een filtercriterium, zoals 'bevat', 'groter dan', 'kleiner dan', etc. Als je een filter maakt in AFAS Connect, zie je achter het criterium een cijfer. Dit cijfer wordt in de aanroep gebruikt.
Meer informatie over de filtercriteria.
Complex filter toepassen
Met complexe filters kan je bij het uitvoeren van een GetConnector ook een EN/OF-filter combineren. Gebruik ook een complex filter ook als in de waardes waarop je filtert komma's of puntkomma's voorkomen (bijvoorbeeld de filterwaarde 'Janssen, Henk').
Toe te passen filter:
- Medewerkers met de afdeling DESGTEAM en die in Leusden wonen
- Medewerkers met de afdeling KWATEAM en die in Zeewolde wonen
JSON-filter maken:
- Start https://connect.afas.nl en log in.
- Ga naar: REST/JSON / GetConnectors.
- Vul het filter in en klik op Enable JSON filter.
- Het veld URL bevat de hele aanroep inclusief het filter:
