Enviar uma solicitação simples

Aprenda a usar a Biblioteca Cronet para realizar operações de rede no seu app Android. A Cronet é a pilha de rede do Chromium disponibilizada como uma biblioteca para você usar nos seus apps. Para saber mais sobre os recursos da biblioteca, consulte Realizar operações de rede usando a Cronet.

Configurar a biblioteca no projeto

Siga estas etapas para adicionar uma dependência à Biblioteca Cronet no projeto:

1. Verifique se o Android Studio incluiu uma referência ao Repositório Maven do Google no arquivo settings.gradle do projeto, conforme mostrado no exemplo a seguir:

   Groovy

   dependencyResolutionManagement {
      ...
      repositories {
          ...
          google()
      }
   }
   

   Kotlin

   dependencyResolutionManagement {
      ...
      repositories {
          ...
          google()
      }
   }
   

2. Inclua uma referência à biblioteca de cliente do Google Play Services para a Cronet na seção dependencies do arquivo build.gradle do módulo do app, conforme mostrado no exemplo a seguir:

   Groovy

   dependencies {
      implementation 'com.google.android.gms:play-services-cronet:18.0.1'
   }
   

   Kotlin

   dependencies {
      implementation("com.google.android.gms:play-services-cronet:18.0.1")
   }
   

Objetos CronetEngine criados depois que essa dependência for adicionada vão usar a Cronet carregada do Google Play Services. Chame CronetProviderInstaller.installProvider(Context) antes de criar objetos CronetEngine para evitar que exceções inesperadas sejam geradas durante a criação de CronetEngine devido a erros, como dispositivos que exigem uma versão atualizada do Google Play Services.

Nos casos em que a Cronet não pode ser carregada a partir do Google Play Services, há uma implementação de menor performance da API da Cronet que pode ser usada. Para usar essa implementação alternativa, dependa de org.chromium.net:cronet-fallback e chame new JavaCronetProvider(context).createBuilder().

Criar uma solicitação de rede

Esta seção mostra como criar e enviar uma solicitação de rede usando a Biblioteca Cronet. Depois de enviar a solicitação de rede, o app precisa processar a resposta da rede.

Criar e configurar uma instância do CronetEngine

A biblioteca fornece uma classe CronetEngine.Builder que pode ser usada para criar uma instância de CronetEngine. O exemplo a seguir mostra como criar um objeto CronetEngine:

Kotlin

val myBuilder = CronetEngine.Builder(context)
val cronetEngine: CronetEngine = myBuilder.build()

Java

CronetEngine.Builder myBuilder = new CronetEngine.Builder(context);
CronetEngine cronetEngine = myBuilder.build();

Observação: recomenda-se criar apenas uma instância de CronetEngine. Uma única instância pode enviar várias solicitações assíncronas. Além disso, um diretório de armazenamento não oferece suporte ao acesso simultâneo por várias instâncias de CronetEngine. Para mais informações, consulte setStoragePath().

Você pode usar a classe Builder para configurar um objeto CronetEngine. Por exemplo, é possível fornecer opções como armazenamento em cache e compactação de dados. Para saber mais, consulte CronetEngine.Builder.

Fornecer uma implementação do callback da solicitação

Para fornecer uma implementação do callback, crie uma subclasse de UrlRequest.Callback e implemente os métodos abstratos necessários, conforme mostrado no exemplo a seguir.

Kotlin

private const val TAG = "MyUrlRequestCallback"

class MyUrlRequestCallback : UrlRequest.Callback() {
    override fun onRedirectReceived(request: UrlRequest?, info: UrlResponseInfo?, newLocationUrl: String?) {
        Log.i(TAG, "onRedirectReceived method called.")
        // You should call the request.followRedirect() method to continue
        // processing the request.
        request?.followRedirect()
    }

    override fun onResponseStarted(request: UrlRequest?, info: UrlResponseInfo?) {
        Log.i(TAG, "onResponseStarted method called.")
        // You should call the request.read() method before the request can be
        // further processed. The following instruction provides a ByteBuffer object
        // with a capacity of 102400 bytes for the read() method. The same buffer
        // with data is passed to the onReadCompleted() method.
        request?.read(ByteBuffer.allocateDirect(102400))
    }

    override fun onReadCompleted(request: UrlRequest?, info: UrlResponseInfo?, byteBuffer: ByteBuffer?) {
        Log.i(TAG, "onReadCompleted method called.")
        // You should keep reading the request until there's no more data.
        byteBuffer.clear()
        request?.read(byteBuffer)
    }

    override fun onSucceeded(request: UrlRequest?, info: UrlResponseInfo?) {
        Log.i(TAG, "onSucceeded method called.")
    }
}

Java

class MyUrlRequestCallback extends UrlRequest.Callback {
  private static final String TAG = "MyUrlRequestCallback";

  @Override
  public void onRedirectReceived(UrlRequest request, UrlResponseInfo info, String newLocationUrl) {
    Log.i(TAG, "onRedirectReceived method called.");
    // You should call the request.followRedirect() method to continue
    // processing the request.
    request.followRedirect();
  }

  @Override
  public void onResponseStarted(UrlRequest request, UrlResponseInfo info) {
    Log.i(TAG, "onResponseStarted method called.");
    // You should call the request.read() method before the request can be
    // further processed. The following instruction provides a ByteBuffer object
    // with a capacity of 102400 bytes for the read() method. The same buffer
    // with data is passed to the onReadCompleted() method.
    request.read(ByteBuffer.allocateDirect(102400));
  }

  @Override
  public void onReadCompleted(UrlRequest request, UrlResponseInfo info, ByteBuffer byteBuffer) {
    Log.i(TAG, "onReadCompleted method called.");
    // You should keep reading the request until there's no more data.
    byteBuffer.clear();
    request.read(byteBuffer);
  }

  @Override
  public void onSucceeded(UrlRequest request, UrlResponseInfo info) {
    Log.i(TAG, "onSucceeded method called.");
  }
}

Observação: para simplificar, o exemplo de código anterior cria uma implementação de UrlRequest.Callback que grava uma mensagem no registro quando um evento de rede acontece. Para saber mais detalhes sobre como implementar o callback, consulte Processar a resposta da rede.

Criar um objeto Executor para gerenciar tarefas de rede

Você pode usar a classe Executor para executar tarefas de rede. Para receber uma instância de Executor, use um dos métodos estáticos da classe Executors que retorna um objeto Executor. O exemplo a seguir mostra como criar um objeto Executor usando o método newSingleThreadExecutor():

Kotlin

val executor: Executor = Executors.newSingleThreadExecutor()

Java

Executor executor = Executors.newSingleThreadExecutor();

Criar e configurar um objeto UrlRequest

Para criar a solicitação de rede, chame o método newUrlRequestBuilder() do CronetEngine transmitindo o URL de destino, uma instância da sua classe de callback e o objeto executor. O método newUrlRequestBuilder() retorna um objeto UrlRequest.Builder que pode ser usado para criar o objeto UrlRequest, conforme mostrado no exemplo a seguir.

Kotlin

val requestBuilder = cronetEngine.newUrlRequestBuilder(
        "https://www.example.com",
        MyUrlRequestCallback(),
        executor
)

val request: UrlRequest = requestBuilder.build()

Java

UrlRequest.Builder requestBuilder = cronetEngine.newUrlRequestBuilder(
        "https://www.example.com", new MyUrlRequestCallback(), executor);

UrlRequest request = requestBuilder.build();

Você pode usar a classe Builder para configurar a instância de UrlRequest. Por exemplo, é possível especificar uma prioridade ou o verbo HTTP. Para saber mais, consulte UrlRequest.Builder.

Para iniciar a tarefa de rede, chame o método start() da solicitação:

Kotlin

request.start()

Java

request.start();

Seguindo as instruções nesta seção, você poderá criar e enviar uma solicitação de rede usando a Cronet. No entanto, para simplificar, a implementação de exemplo de UrlRequest.Callback mostra apenas uma mensagem no registro. A seção a seguir mostra como fornecer uma implementação de callback que seja compatível com cenários mais úteis, como extrair dados da resposta e detectar uma falha na solicitação.

Processar a resposta da rede

Depois de chamar o método start(), o ciclo de vida da solicitação da Cronet é iniciado. Seu app precisa especificar um callback para gerenciar a solicitação durante o ciclo de vida. Para saber mais sobre o ciclo de vida, consulte Ciclo de vida da solicitação da Cronet. É possível especificar um callback criando uma subclasse de UrlRequest.Callback e implementando os métodos abaixo:

onRedirectReceived()

Invocado quando o servidor emite um código de redirecionamento HTTP em resposta à solicitação original. Para acompanhar o redirecionamento para o novo destino, use o método followRedirect(). Caso contrário, use o método cancel(). O exemplo a seguir mostra como implementar o método:

Kotlin

override fun onRedirectReceived(request: UrlRequest?, info: UrlResponseInfo?, newLocationUrl: String?) {
  // Determine whether you want to follow the redirect.
  ...

  if (shouldFollow) {
      request?.followRedirect()
  } else {
      request?.cancel()
  }
}

Java

@Override
public void onRedirectReceived(UrlRequest request, UrlResponseInfo info, String newLocationUrl) {
  // Determine whether you want to follow the redirect.
  …

  if (shouldFollow) {
    request.followRedirect();
  } else {
    request.cancel();
  }
}

onResponseStarted()

Invocado quando o conjunto final de cabeçalhos é recebido. O método onResponseStarted() só é invocado depois que todos os redirecionamentos são seguidos. O código abaixo mostra um exemplo de implementação do método.

Kotlin

override fun onResponseStarted(request: UrlRequest?, info: UrlResponseInfo?) {
  val httpStatusCode = info?.httpStatusCode
  if (httpStatusCode == 200) {
    // The request was fulfilled. Start reading the response.
    request?.read(myBuffer)
  } else if (httpStatusCode == 503) {
    // The service is unavailable. You should still check if the request
    // contains some data.
    request?.read(myBuffer)
  }
  responseHeaders = info?.allHeaders
}

Java

@Override
public void onResponseStarted(UrlRequest request, UrlResponseInfo info) {
  int httpStatusCode = info.getHttpStatusCode();
  if (httpStatusCode == 200) {
    // The request was fulfilled. Start reading the response.
    request.read(myBuffer);
  } else if (httpStatusCode == 503) {
    // The service is unavailable. You should still check if the request
    // contains some data.
    request.read(myBuffer);
  }
  responseHeaders = info.getAllHeaders();
}

Observação: códigos de status 4xx e 5xx não são considerados erros na perspectiva da Cronet. Ainda assim, tente ler a resposta usando o método read(), porque ela pode conter alguns dados. Também é possível cancelar a solicitação usando o método cancel(). Essas ações garantem que a solicitação seja levada a um estado final.

onReadCompleted()

Invocado sempre que parte do corpo da resposta tiver sido lida. O exemplo de código a seguir mostra como implementar o método e extrair o corpo da resposta:

Kotlin

override fun onReadCompleted(request: UrlRequest?, info: UrlResponseInfo?, byteBuffer: ByteBuffer?) {
  // The response body is available, process byteBuffer.
  ...

  // Continue reading the response body by reusing the same buffer
  // until the response has been completed.
  byteBuffer?.clear()
  request?.read(myBuffer)
}

Java

@Override
public void onReadCompleted(UrlRequest request, UrlResponseInfo info, ByteBuffer byteBuffer) {
  // The response body is available, process byteBuffer.
  …

  // Continue reading the response body by reusing the same buffer
  // until the response has been completed.
  byteBuffer.clear();
  request.read(myBuffer);
}

onSucceeded()

Invocado quando a solicitação de rede é concluída. O exemplo abaixo mostra como implementar o método:

Kotlin

override fun onSucceeded(request: UrlRequest?, info: UrlResponseInfo?) {
    // The request has completed successfully.
}

Java

@Override
public void onSucceeded(UrlRequest request, UrlResponseInfo info) {
  // The request has completed successfully.
}

onFailed()

Invocado se a solicitação falhou por qualquer motivo após a chamada do método start(). O exemplo abaixo mostra como implementar o método e receber informações sobre o erro:

Kotlin

override fun onFailed(request: UrlRequest?, info: UrlResponseInfo?, error: CronetException?) {
    // The request has failed. If possible, handle the error.
    Log.e(TAG, "The request failed.", error)
}

Java

@Override
public void onFailed(UrlRequest request, UrlResponseInfo info, CronetException error) {
  // The request has failed. If possible, handle the error.
  Log.e(TAG, "The request failed.", error);
}

onCanceled()

Invocado se a solicitação foi cancelada usando o método cancel(). Depois de invocado, nenhum outro método da classe UrlRequest.Callback é invocado. Use esse método para liberar os recursos alocados para processar uma solicitação. O exemplo a seguir mostra como implementar o método:

Kotlin

override fun onCanceled(request: UrlRequest?, info: UrlResponseInfo?) {
    // Free resources allocated to process this request.
    ...
}

Java

@Override
public void onCanceled(UrlRequest request, UrlResponseInfo info) {
  // Free resources allocated to process this request.
  …
}