Salesforce bevat een uitgebreide API waarmee het mogelijk is ongeveer alles op te vragen en te bewerken dat ook op te vragen is middels de web-interface. De authenticatie om de zogeheten 'Bearer'-token te krijgen is echter redelijk lastig. Dit loopt via het 'OAuth'-protocol. Deze blog is een handleiding hoe u een 'Connected'-App kan configureren en vervolgens een REST-API call uitvoert.
Salesforce App configureren
Om te beginnen moet een zogeheten 'Connected'-applicatie worden aangemaakt. Dit gaat als volgt,
1, ga naar uw Salesforce omgeving (https://test.salesforce.com/) & login
2, klik rechtsboven op het wieltje en kies 'Setup'
3, kies vervolgens onder 'PLATFORMTOOLS' => Apps => Appbeheer => 'Nieuwe verbonden app'
4, configureer vervolgens de nieuwe Connected-App zoals in het voorbeeld.
Een aantal waardes spreken voor zich, anderen hebben extra uitleg nodig,
| Naam verbonden app | willekeurige naam |
| API-naam | deze wordt automatisch gegenereerd op basis van de ingevoerde naam |
| E-mail contactpersoon | - |
| Call-back-URL | Dit veld is nodig vanwege de OAuth-authenticatie. Salesforce maakt gebruik van een zogeheten 'single-sign-on' faciliteit. Hiermee is het ook mogelijk Salesforce-authenticatie in uw webapplicatie te integreren. Hoewel dit in dit voorbeeld niet gebruikt wordt, is wel een waarde verplicht. Daarom is hier de url van de eigen website ingevoerd. |
| Beschikbare OAuth-bereiken | Waartoe de Connected-app toegang heeft middels de REST-API. Omdat dit een test/voorbeeld is, zijn alle autorisaties toegevoegd |
| Geheim vereisen voor webserverstroom | Deze hoeft niet te worden aangevinkt. In het voorbeeld is deze wel aangevinkt. Als dit is aangevinkt moet met de API-calls die straks worden uitgevoerd het veld 'client_secret' worden meegegeven. |
| ID-token opnemen | Deze waarde zorgt er voor dat we een 'Bearer'-token kunnen opvragen. Als deze niet is aangevinkt werkt dit niet. |
Na opslaan duurt het 2 tot 10 minuten voordat de Connected-App werkt. Let op, als u wijzigingen maakt kan het uren duren voordat deze wordt doorgevoerd. Zelf had ik in eerste instantie de App onjuist geconfigureerd en daarna aangepast. Na 2 uur zoeken had ik een extra Connected-App aangemaakt met exact dezelfde instellingen. Deze werkte vervolgens vrijwel direct.
Php code met REST-API call
De Salesforce REST-API werkt als volgt. Eerstens moet je je autoriseren en een zogeheten 'Bearer'-token op vragen. Zodra je geautoriseerd bent kan je met deze Bearer-token alle REST-API's aanroepen. De autorisatie aanvraag gaat middels een API call naar https://test.salesforce.com/services/oauth2/token
Hiervoor zijn de volgende gegevens nodig,
- client_id
- client_secret
- username
- password
- securityToken
De client_id & client_secret waardes hebben betrekking tot de aangemaakte app. Deze zijn op te vragen onder de 'Setup' => 'Apps' => 'Appbeheer' => Bij de App-naam op de pijl naar beneden klikken en kiezen voor 'Weergeven'. Vervolgens krijg je een overzicht van de 'verbonden app'. Onder API (OAuth-instellingen) staat,
- Consumentensleutel = client_id
- Consumentengeheim = client_secret
De username, password & securityToken hebben betrekking tot de gebruiker die zich aanmeld. De username & password zijn ongetwijfeld al bij je bekend - hiermee heb je je immers aangemeld op Salesforce. De securityToken kan (opnieuw) worden aangevraagd door rechtsboven op je profiel-icoon te klikken en de instellingen van de huidige gebruiker op te vragen. Vervolgens kies je links in het menu 'Mijn beveiligingstoken opnieuw instellen'. Hierna wordt er een (nieuwe) token per e-mail opgestuurd.
Nu je alle gegevens hebt kan je de Bearer-token opvragen van Salesforce,
$ch = curl_init('https://test.salesforce.com/services/oauth2/token');
$data = array();
$data['grant_type'] = 'password';
$data['client_id'] = '93458MSKLf_FShuiwrhwieu5._89345sfdlkjaeru34985jskldfjs_sfdakjfhu3io54yuqwyerfsafadurf';
$data['client_secret'] = '8798890534123987983';
$data['username'] = 'info@itxplain.nl';
$data['password'] = 'password-123' . 'securityToken-456';
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);
Mocht alles goed gaan krijg je een resultaat dat er als volgt uit ziet,
{
"access_token":"adfkJLSDFkDFKL_.JFJA!jsd89w4",
"instance_url":"https://YOUR-INSTANCE.salesforce.com",
"id":"https://test.salesforce.com/id/05X0E02345345345FAJ84/3904580asdf944a",
"token_type":"Bearer",
"issued_at":"1507555090842",
"signature":"YXNkZmhramFzc2RoZmJsYWJsYWJsYQ=="
}
Met deze gegevens kan je vervolgens beginnen aan de API-calls! Als volgt een voorbeeldaanvraag om Accounts op te vragen,
$q = 'select Name from Account';
$ch = curl_init('https://YOUR-INSTANCE.salesforce.com/services/data/v20.0/query/?q='.urlencode($q));
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $access_token,
'X-PrettyPrint: 1'
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$result = curl_exec($ch);
Meer informatie over de REST-API is uiteraard in de developer-documentatie te vinden.