Zugriff auf Salesforce-Daten über REST-APIs

Lernziele

Nachdem Sie diese Lektion abgeschlossen haben, sind Sie in der Lage, die folgenden Aufgaben auszuführen:

Instanziieren einer REST-Anforderung mit der RestClient-Klasse
Ausgeben einer asynchronen REST-Anforderung mit den Klassen RestClient und RestRequest
Empfangen und Verarbeiten einer REST-Antwort mit der RestResponse-Klasse

Verwenden von REST APIs

Wenn Sie soweit sind, dass Sie in Ihrer Anwendung auf die Salesforce-Daten zugreifen können, rufen Sie Salesforce REST APIs auf. REST APIs sind in der Regel auf einer niedrigen Ebene angesiedelt, auf der ein Entwickler über rudimentäre Netzwerkaufrufe manuell darauf zugreifen kann. Das brauchen Sie jedoch nicht zu tun – Sie haben ja das Mobile SDK, das den Wust von Arbeit für Sie erledigt.

Hier eine Übersicht der Klassen, die REST API-Aufrufe verarbeiten. All diese Klassen sind im com.salesforce.androidsdk.rest-Paket zu Hause.

ClientManager: Dient als Factory für RestClient-Instanzen. Verarbeitet darüber hinaus Account-Anmeldungen und Handshakes mit dem Salesforce-Server.
RestClient: Verwaltet das Protokoll für das Senden von REST-API-Anforderungen an den Salesforce-Server.
Erstellen Sie keine Instanzen von RestClient direkt. Rufen Sie stattdessen die ClientManager.getRestClient()-Methode auf.
RestRequest: Stellt REST-API-Anforderungen dar, die anhand der von Ihnen bereitgestellten Daten formatiert wurden. Dient auch als Factory für Instanzen von sich selbst.

Wichtig

Erstellen Sie keine Instanzen von RestRequest direkt. Rufen Sie stattdessen eine geeignete statische RestRequest-Getter-Funktion wie RestRequest.getRequestForCreate() auf.
RestResponse: Enthält den Inhalt der Antwort im angeforderten Format. Die RestRequest-Klasse erstellt RestResponse-Instanzen und gibt sie über Ihre Implementierung der RestClient.AsyncRequestCallback-Schnittstelle an Ihre Anwendung zurück.

Das folgende animierte Diagramm zeigt den Flow in Aktion.

Die Anwendung ruft eine statische Methode in der RestRequest-Klasse auf, um eine konfigurierte RestRequest-Instanz zu erstellen.
Die Anwendung übergibt die neue RestRequest-Instanz und eine Instanz der AsyncRequestCallback-Schnittstelle an die RestClient.sendAsync()-Methode.
Das Mobile SDK sendet die REST-Anforderung, die im RestRequest-Objekt angegeben wurde, an den Salesforce-Cloud-Service.
Salesforce verarbeitet die Anforderung und gibt eine JSON-Antwort an die Anwendung zurück.
Das Mobile SDK packt die JSON-Antwort in ein neues RestResponse-Objekt.
Das Mobile SDK übergibt das neue RestResponse-Objekt an die AsyncRequestCallback-Implementierung der Anwendung weiter, wo es genutzt werden kann.

Noch wach? Gehen wir doch mal über die begriffliche Ebene hinaus und schauen uns diese Informationen bei der Arbeit in der Praxis Ihrer Anwendung an.

Die sendRequest()-Methode

Ihre MainActivity-Klasse sendet REST-Anforderungen und nutzt dann die REST-Antworten zum Auffüllen ihrer Listenansicht. Jetzt tauchen wir nochmal ein in den MainActivity-Code, um diesen Flow zu verfolgen.

Erweitern Sie in Android Studio im Fenster "Project" app | src | com.mytrail.android.
Doppelklicken Sie auf MainActivityMainActivity.
Suchen Sie nach der Methode onFetchContactsClick. Beachten Sie, dass diese unscheinbare Methode eine sendRequest()-Methode mit einer SOQL-Anweisung aufruft.
```
public void onFetchContactsClick(View v) throws UnsupportedEncodingException {
    sendRequest("SELECT Name FROM Contact");
} 
```
Klicken Sie mit der rechten Maustaste auf "sendRequest" und wählen Sie Go To | Implementation(s) aus. Wie Sie feststellen können, ist sendRequest() eine private Methode in Ihrer MainActivity-Klasse. Gut, dass diese Ihnen gehört, denn wir wollen sie später ändern.

Die sendRequest()-Methode ist diejenige, bei der Sie die Mobile SDK-REST-Klassen bei der Arbeit beobachten können. Und das sind hier die Hauptakteure:

client – eine private, auf die Klasse begrenzte Instanz von RestClient. Dieses Objekt wird während der Initialisierung der Anwendung automatisch instanziiert.
restRequest – eine neue RestRequest-Instanz.
RestRequest.getRequestForQuery() – eine statische RestRequest-Factory-Methode, aus der die RestRequest-Instanz hervorgeht.
AsyncRequestCallback – die Implementierung der Oberfläche mit den REST-Antwortrückmeldungen für Ihre Anwendung.

Erstellen der REST-Anforderung

In sendRequest() verwendet die Factory-Methode die RestRequest.getRequestForQuery() eine SOQL-Zeichenfolge und umschließt diese mit einem RestRequest-Objekt:

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

Der Vorteil der Verwendung von RestRequest-Factory-Methoden ist, dass das generierte Objekt netzwerkfähig ist – es kennt bereits die HTTP-Einstellungen, die der Salesforce-Server erwartet.

Senden der REST-Anforderung

Zum Senden der Anforderung an Salesforce übergeben Sie das RestRequest-Objekt an die RestClient.sendAsync()-Methode.

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

Der Mobile SDK-Code erzeugt das client Objekt für Sie, während er Ihre Aktivität initialisiert. Der zweite Parameter (Typ: AsyncRequestCallback) ist eine Instanz einer virtuellen Oberfläche, die auf den Empfang von REST-Antworten ausgelegt ist. In diesem Beispiel wird AsyncRequestCallback inline implementiert und instanziiert.

Das Präfix "async" wird hier immer noch angezeigt. Das muss wohl irgendeine Bedeutung haben, oder? Wenn Sie eine Anforderung asynchron senden, bedeutet dies, dass der Code Ihrer Anwendung keine Pause einlegt, um auf die Antwort zu warten. Sobald die Antwort eintrifft, ruft das Mobile SDK eine Ihrer Rückmeldungsmethoden auf, und die Anwendung setzt jeden laufenden Prozess aus, um die Antwort zu verarbeiten. Wenn die Ausführung Ihres Codes auf dem Haupt- (UI-) Thread erfolgt, müssen Sie die Anforderungen asynchron senden.

Erfassen und Verarbeiten der REST-Antwort

Wenn Salesforce die REST-Antwort zurück gibt, leitet das RestClient-Objekt diese an Ihre AsyncRequestCallback-Implementierung weiter. In der AsyncRequestCallback-Oberfläche legen Sie fest, wie Ihre Anwendung die REST-Antwort von Salesforce verarbeiten soll. Erfolgreiche REST-Antworten verarbeiten Sie in der onSuccess()-Methode:

@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);
             }
        }
    });
}

Fehlgeschlagene Anforderungen in der onError()-Methode werden glücklicherweise wiederhergestellt.

@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();
        }
    });
}

Beachten Sie, dass die REST-Antwort im JSON-Format eingeht, weshalb Programmierer sie einfach analysieren können. Ist die Anforderung erfolgreich, extrahiert die Anwendung Werte aus dem Feld "Name" zum Auffüllen der Listenansicht. Schlägt die Abfrage fehl, blendet die Anwendung eine Fehlermeldung ein.