Envoyer une simple requête

Découvrez comment utiliser la bibliothèque Cronet pour effectuer des opérations réseau dans votre application Android. Cronet est la pile réseau Chromium mise à disposition sous forme de bibliothèque à utiliser dans vos applications. Pour en savoir plus sur les fonctionnalités de la bibliothèque, consultez la section Effectuer des opérations réseau à l'aide de Cronet.

Configurer la bibliothèque dans votre projet

Pour ajouter une dépendance à la bibliothèque Cronet dans votre projet, procédez comme suit:

  1. Vérifiez qu'Android Studio a inclus une référence au dépôt Maven de Google dans le fichier settings.gradle de votre projet, comme illustré dans l'exemple suivant:

    Groovy

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

    Kotlin

    dependencyResolutionManagement {
       ...
       repositories {
           ...
           google()
       }
    }
    
  2. Incluez une référence à la bibliothèque cliente des services Google Play pour Cronet dans la section dependencies du fichier build.gradle de votre module d'application, comme illustré dans l'exemple suivant:

    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")
    }
    

Les objets CronetEngine créés une fois cette dépendance ajoutés utiliseront Cronet chargé à partir des services Google Play. Appelez CronetProviderInstaller.installProvider(Context) avant de créer des objets CronetEngine pour éviter que des exceptions inattendues ne soient générées lors de la création de CronetEngine en raison d'erreurs telles que les appareils nécessitant une version mise à jour des services Google Play.

Dans les cas où Cronet ne peut pas être chargé à partir des services Google Play, une implémentation moins performante de l'API de Cronet peut être utilisée. Pour utiliser cette implémentation de remplacement, dépendez de org.chromium.net:cronet-fallback et appelez new JavaCronetProvider(context).createBuilder().

Créer une requête réseau

Cette section explique comment créer et envoyer une requête réseau à l'aide de la bibliothèque Cronet. Après avoir envoyé la requête réseau, votre application doit traiter la réponse du réseau.

Créer et configurer une instance de CronetEngine

La bibliothèque fournit une classe CronetEngine.Builder que vous pouvez utiliser pour créer une instance de CronetEngine. L'exemple suivant montre comment créer un objet CronetEngine:

Kotlin

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

Java

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

Vous pouvez utiliser la classe Builder pour configurer un objet CronetEngine. Par exemple, vous pouvez fournir des options telles que la mise en cache et la compression des données. Pour en savoir plus, consultez CronetEngine.Builder.

Fournir une implémentation du rappel de requête

Pour fournir une implémentation du rappel, créez une sous-classe de UrlRequest.Callback et implémentez les méthodes abstraites requises, comme illustré dans l'exemple suivant:

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.");
  }
}

Créer un objet Executor pour gérer les tâches réseau

Vous pouvez utiliser la classe Executor pour exécuter des tâches réseau. Pour obtenir une instance de Executor, utilisez l'une des méthodes statiques de la classe Executors qui renvoient un objet Executor. L'exemple suivant montre comment créer un objet Executor à l'aide de la méthode newSingleThreadExecutor():

Kotlin

val executor: Executor = Executors.newSingleThreadExecutor()

Java

Executor executor = Executors.newSingleThreadExecutor();

Créer et configurer un objet UrlRequest

Pour créer la requête réseau, appelez la méthode newUrlRequestBuilder() du CronetEngine en transmettant l'URL de destination, une instance de votre classe de rappel et l'objet exécuteur. La méthode newUrlRequestBuilder() renvoie un objet UrlRequest.Builder que vous pouvez utiliser pour créer l'objet UrlRequest, comme illustré dans l'exemple suivant:

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

Vous pouvez utiliser la classe Builder pour configurer l'instance de UrlRequest. Par exemple, vous pouvez spécifier une priorité ou le verbe HTTP. Pour en savoir plus, consultez UrlRequest.Builder.

Pour démarrer la tâche réseau, appelez la méthode start() de la requête:

Kotlin

request.start()

Java

request.start();

Suivez les instructions de cette section pour créer et envoyer une requête réseau à l'aide de Cronet. Toutefois, par souci de simplicité, l'exemple d'implémentation de UrlRequest.Callback n'imprime qu'un message dans le journal. La section suivante montre comment fournir une implémentation de rappel compatible avec des scénarios plus utiles, tels que l'extraction de données de la réponse et la détection d'un échec dans la requête.

Traiter la réponse du réseau

Une fois que vous avez appelé la méthode start(), le cycle de vie des requêtes Cronet est lancé. Votre application doit gérer la requête pendant le cycle de vie en spécifiant un rappel. Pour en savoir plus sur le cycle de vie, consultez la section Cycle de vie des requêtes Cron. Vous pouvez spécifier un rappel en créant une sous-classe de UrlRequest.Callback et en implémentant les méthodes suivantes:

onRedirectReceived()

Appelée lorsque le serveur émet un code de redirection HTTP en réponse à la requête d'origine. Pour suivre la redirection vers la nouvelle destination, utilisez la méthode followRedirect(). Sinon, utilisez la méthode cancel(). L'exemple suivant montre comment implémenter la méthode:

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()

Appelée lorsque l'ensemble final d'en-têtes est reçu. La méthode onResponseStarted() n'est appelée qu'une fois toutes les redirections suivies. Le code suivant montre un exemple d'implémentation de la méthode:

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

Appelée chaque fois qu'une partie du corps de la réponse a été lue. L'exemple de code suivant montre comment mettre en œuvre la méthode et extraire le corps de la réponse:

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()

Appelée lorsque la requête réseau a abouti. L'exemple suivant montre comment mettre en œuvre la méthode:

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()

Appelée si la requête échoue pour une raison quelconque après l'appel de la méthode start(). L'exemple suivant montre comment mettre en œuvre la méthode et obtenir des informations sur l'erreur:

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()

Appelée si la requête a été annulée à l'aide de la méthode cancel(). Une fois appelées, aucune autre méthode de la classe UrlRequest.Callback n'est appelée. Vous pouvez utiliser cette méthode pour libérer des ressources allouées au traitement d'une requête. L'exemple suivant montre comment implémenter la méthode:

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.
  …
}