Acessar dados do Salesforce por APIs REST

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

Criar uma instância da solicitação REST na classe RestClient
Emitir uma solicitação REST de forma assíncrona com as classes RestClient e RestRequest
Receber e processar uma resposta REST com a classe RestResponse

Como usar APIs REST

Quando você estiver pronto para acessar dados do Salesforce em seu aplicativo, chame as APIs REST do Salesforce. As APIs REST, em geral, são de um nível inferior o suficiente para permitir que os desenvolvedores as acessem manualmente com chamadas de rede rudimentares. No entanto, não é necessário fazer isso; o Mobile SDK pode fazer o trabalho sujo por você.

Veja um resumo das classes que tratam das chamadas à API REST. Todas essas classes residem no pacote com.salesforce.androidsdk.rest.

ClientManager – serve como fábrica para instâncias RestClient. Ela também trata de logins de conta e de handshakes com o servidor do Salesforce.
RestClient – trata do protocolo para enviar solicitações da API REST ao servidor do Salesforce.
Não crie instâncias de RestClient diretamente. Em vez disso, chame o método ClientManager.getRestClient().
RestRequest – representa as solicitações à API REST formatadas com os dados fornecidos por você. Ela também serve como fábrica para suas próprias instâncias.

Importante

Não crie instâncias de RestRequest diretamente. Em vez disso, chame uma função getter estática RestRequest adequada, como RestRequest.getRequestForCreate().
RestResponse – tem o conteúdo da resposta no formato solicitado. A classe RestRequest cria instâncias de RestResponse e as retorna ao aplicativo pela implantação da interface RestClient.AsyncRequestCallback.

Veja um diagrama animado que mostra esse fluxo na prática.

Fluxo de tempo de execução da API REST (Android)

O aplicativo chama um método estático na classe RestRequest para criar uma instância RestRequest configurada.
O aplicativo transmite a nova instância RestRequest e uma instância da interface AsyncRequestCallback para o método RestClient.sendAsync().
O Mobile SDK envia a solicitação REST apresentada no objeto RestRequest para o serviço de nuvem do Salesforce.
O Salesforce processa a solicitação e retorna uma resposta JSON para o aplicativo.
O Mobile SDK empacota a resposta JSON em um novo objeto RestResponse.
O Mobile SDK transmite o novo objeto RestResponse para a implantação AsyncRequestCallback do aplicativo para consumo.

Ainda está acordado? Vamos sair do nível conceitual e ver como essas informações funcionam no mundo real do seu aplicativo.

O método sendRequest()

Sua classe MainActivity envia solicitações REST e usa as respostas REST para preencher o modo de exibição de lista. Vamos voltar para o código MainActivity a fim de rastrear esse fluxo.

Na janela Projeto do Android Studio, expanda app src com.mytrail.android.
Clique duas vezes em MainActivity.

Encontre o método onFetchContactsClick. Observe que esse pequeno método chama um método sendRequest() com uma instrução SOQL.

public void onFetchContactsClick(View v) throws UnsupportedEncodingException {
    sendRequest("SELECT Name FROM Contact");
}

Clique com o botão direito do mouse em “sendRequest” e selecione Ir para | Implantação(ões). Ocorre que sendRequest() é um método privado na sua classe MainActivity. Que bom que é sua, pois vamos mudá-la mais tarde!

O método sendRequest() é onde se vê as classes REST do Mobile SDK funcionando. Os principais atores aqui são:

client – uma instância de escopo de classe de RestClient. Uma instância desse objeto é criada automaticamente durante a inicialização do aplicativo
restRequest – uma nova instância de RestRequest
RestRequest.getRequestForQuery() – um método de fábrica RestRequest estático que cria a instância RestRequest
AsyncRequestCallback – a implantação da interface de retorno de chamada da resposta REST de seu aplicativo

Como criar a solicitação REST

Em sendRequest(), o método de fábrica RestRequest.getRequestForQuery() usa uma sequência de caracteres SOQL e a encapsula em um objeto RestRequest.

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

A vantagem de usar métodos de fábrica RestRequest é que o objeto gerado já está pronto para a rede; ele sabe quais são as configurações HTTP esperadas pelo servidor do Salesforce.

Como enviar a solicitação REST

Para enviar a solicitação ao Salesforce, transmita o objeto RestRequest ao método RestClient.sendAsync().

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

O código do Mobile SDK cria o objeto client para você enquanto está inicializando a atividade. O segundo parâmetro, do tipo AsyncRequestCallback, é uma instância de uma interface virtual que é criada para receber respostas REST. No exemplo, AsyncRequestCallback é implementado e uma instância é criada em linha.

O prefixo “async” continua aparecendo aqui. Isso deve ser importante, não é? O envio de uma solicitação de maneira assíncrona significa que o código do seu aplicativo não pausa para aguardar a resposta. Quando a resposta chega, o Mobile SDK chama um de seus métodos de retorno de chamada e o aplicativo suspende o que estiver em andamento por um instante para processar a resposta. Você precisa enviar solicitações de maneira assíncrona quando a execução do código está ocorrendo no thread principal (IU).

Como capturar e processar a resposta REST

Quando o Salesforce retorna a resposta REST, o objeto RestClient a encaminha à implantação do AsyncRequestCallback. Na interface AsyncRequestCallback, defina como seu aplicativo trata da resposta REST vinda do Salesforce. As respostas REST bem-sucedidas são tratadas no método onSuccess():

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

e a recuperação de solicitações com falha é feita no método onError().

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

Observe que a resposta REST chega em formato JSON e, portanto, é fácil para os humanos codificadores analisá-la. Se a consulta for bem-sucedida, o aplicativo extrairá os valores do campo Nome para preencher o modo de exibição de lista da IU. Se a consulta falhar, o aplicativo exibirá uma notificação com uma mensagem de erro.