Accès aux données Salesforce via les API REST

Objectifs de formation

Une fois cette unité terminée, vous pourrez :

Instancier une requête REST avec la classeRestClient
Émettre une requête REST asynchrone avec les classesRestClientetRestRequest
Recevoir et traiter une réponse REST avec la classeRestResponse

Utilisation des API REST

Lorsque vous êtes prêt à accéder aux données Salesforce dans votre application, vous appelez les Salesforce. Généralement, les API REST sont relativement accessibles. Ainsi, les développeurs peuvent y accéder manuellement via des appels réseau rudimentaires. Mais cela ne vous concerne pas : le kit de développement Mobile SDK se charge des tâches fastidieuses pour vous.

Voici un résumé des classes qui gèrent les appels des API REST. Toutes les classes résident dans le packagecom.salesforce.androidsdk.rest.

ClientManager : sert de fabrique pour les instancesRestClient. Elle gère également les connexions au compte et les liaisons avec le serveur Salesforce.
RestClient : gère le protocole permettant d’envoyer les requêtes API REST au serveur Salesforce.
Ne créez pas directement des instances deRestClient. À la place, appelez la méthodeClientManager.getRestClient().
RestRequest : représente les demandes d’API REST formatées à partir des données que vous fournissez. Elle sert également de fabrique pour ses instances.

Important :

Ne créez pas directement des instances deRestRequest. Appelez plutôt une fonction d’obtention statique appropriéeRestRequest, telle queRestRequest.getRequestForCreate().
RestResponse : contient la réponse au format demandé. La classeRestRequestcrée des instancesRestResponseet les renvoie à votre application par le biais de l’implémentation de l’interfaceRestClient.AsyncRequestCallback.

Voici un diagramme animé qui montre ce flux en action.

Flux d’exécution de l’API REST (Android)

L’application appelle une méthode statique sur la classeRestRequestpour créer une instanceRestRequestconfigurée.
L’application transmet la nouvelle instanceRestRequestet une instance de l’interfaceAsyncRequestCallbackà la méthodeRestClient.sendAsync().
Le kit de développement Mobile SDK envoie la requête REST présentée dans l’objetRestRequestau service Cloud de Salesforce.
Salesforce traite la requête et renvoie une réponse JSON à l’application.
Le kit de développement Mobile SDK insère la réponse JSON dans un nouvel objetRestResponse.
Le kit de développement Mobile SDK transmet le nouvel objetRestResponseà l’implémentationAsyncRequestCallbackde l’application pour qu’elle le consomme.

Vous suivez toujours ? Laissons de côté le niveau conceptuel pour observer l’activité de ces informations dans votre véritable application.

La méthode sendRequest()

Votre classeMainActivityenvoie des requêtes REST, puis utilise les réponses REST pour renseigner sa vue de liste. Revenons au codeMainActivitypour suivre ce flux.

Dans la fenêtre du projet Android Studio, agrandissez app | src | com.mytrail.android.
Double-cliquez sur MainActivity.
Recherchez la méthodeonFetchContactsClick. Vous remarquerez que cette petite méthode appelle une méthodesendRequest()avec une instruction SOQL.
```
public void onFetchContactsClick(View v) throws UnsupportedEncodingException {
    sendRequest("SELECT Name FROM Contact");
} 
```
Cliquez avec le bouton droit sur « sendRequest », puis sélectionnez Go To | Implementation(s). En fait,sendRequest()est une méthode privée dans votre classeMainActivity. Une bonne nouvelle, car elle vous appartient. Nous allons la modifier plus loin !

La classesendRequest()constitue l’emplacement où vous pouvez voir en action les classes REST du kit de développement Mobile SDK. Ici, les principaux acteurs sont :

client : une instance privée, délimitée par une classe, deRestClient. Cet objet est automatiquement instancié durant l’initialisation de l’application
restRequest : une nouvelle instanceRestRequest.
RestRequest.getRequestForQuery() : une méthode d’usineRestRequeststatique qui crée l’instanceRestRequest.
AsyncRequestCallback : l’implémentation au sein de votre application de l’interface de rappel de la réponse REST.

Création de la requête REST

DanssendRequest(), la méthode d’usineRestRequest.getRequestForQuery()traite une chaîne SOQL et l’enveloppe dans un objetRestRequest.

RestRequest restRequest = 
    RestRequest.getRequestForQuery(
        getString(R.string.api_version), soql);

L’avantage de l’utilisation de méthodes d’usineRestRequestest que l’objet ainsi généré est prêt à être utilisé sur le réseau : il connaît déjà les paramètres HTTP attendus par le serveur Salesforce.

Envoi de la requête REST

Pour envoyer la requête à Salesforce, vous transmettez l’objetRestRequestà la méthodeRestClient.sendAsync().

client.sendAsync(restRequest, new AsyncRequestCallback()
    { 
    ...

Le code du kit de développement Mobile SDK crée pour vous l’objetclienttout en initialisant votre activité. Le deuxième paramètre, de typeAsyncRequestCallbackest une instance d’une interface virtuelle conçue pour recevoir des réponses REST. Dans cet exemple,AsyncRequestCallbackest implémenté et instancié en ligne.

Ici, le préfixe « async » est toujours présent. Il doit avoir une importance, non ? Lorsque vous envoyez une requête de façon asynchrone, cela signifie que le code de votre application ne s’interrompt pas pour attendre la réponse. Lorsque la réponse arrive, le kit de développement Mobile SDK appelle l’une de vos méthodes de rappel, et l’application suspend brièvement son activité pour traiter la réponse. Vous devez envoyer les requêtes de façon asynchrone lorsque votre code est exécuté dans le thread principal (interface utilisateur) .

Capture et traitement de la réponse REST

Lorsque Salesforce renvoie la réponse REST, l’objetRestClientla transmet à votre implémentationAsyncRequestCallback. Dans l’interfaceAsyncRequestCallback, vous définissez comment votre application gère la réponse REST de Salesforce. Vous traitez les réponses REST réussies dans la méthodeonSuccess() :

@Override
public void onSuccess(RestRequest request,
    final RestResponse result) {
    result.consumeQuietly(); // consume before going back to main thread
    runOnUiThread(new Runnable() {
        @Override
        public void run() { 
            try {
                listAdapter.clear();
                JSONArray records = 
                    result.asJSONObject().getJSONArray("records");
                for (int i = 0; i < records.length(); i++) {
                    listAdapter.add(
                        records.getJSONObject(i).getString("Name"));
                } 
             } catch (Exception e) {
                 onError(e);
             }
        }
    });
}

Ensuite, vous vous occupez avec brio des requêtes échouées dans la méthodeonError().

@Override
public void onError(Exception exception)
{
    runOnUiThread((new Runnable() {
        @Override
        public void run() {
            Toast.makeText(MainActivity.this,
            MainActivity.this.getString(R.string.sf__generic_error, 
                exception.toString()),
            Toast.LENGTH_LONG).show();
        }
    });
}

Notez que la réponse REST arrive sous le format JSON. Par conséquent, elle est facile à analyser avec un code écrit par une personne. Si la requête réussit, l’application extrait les valeurs du champ Name et renseigne la vue de liste de l’interface utilisateur. Si la requête échoue, l’application affiche un message d'erreur flottant.