Einfache Anfrage senden

Hier erfahren Sie, wie Sie mit der Cronet-Bibliothek Netzwerkvorgänge in Ihrer Android-App ausführen. Cronet ist der Chromium-Netzwerk-Stack, den Sie als Bibliothek in Ihren Apps verwenden können. Weitere Informationen zu den Bibliotheksfunktionen finden Sie unter Netzwerkvorgänge mit Cronet durchführen.

Bibliothek in Ihrem Projekt einrichten

So fügen Sie der Cronet-Bibliothek in Ihrem Projekt eine Abhängigkeit hinzu:

1. Prüfen Sie, ob Android Studio in der Datei settings.gradle Ihres Projekts einen Verweis auf das Maven-Repository von Google eingefügt hat, wie im folgenden Beispiel gezeigt:

   Groovig

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

   Kotlin

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

2. Fügen Sie im Abschnitt dependencies der Datei build.gradle Ihres App-Moduls einen Verweis auf die Google Play-Dienste-Clientbibliothek für Cronet ein, wie im folgenden Beispiel gezeigt:

   Groovig

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

CronetEngine-Objekte, die nach dem Hinzufügen dieser Abhängigkeit erstellt wurden, verwenden Cronet, das aus Google Play-Diensten geladen wurde. Rufen Sie CronetProviderInstaller.installProvider(Context) auf, bevor Sie CronetEngine-Objekte erstellen, um zu verhindern, dass beim Erstellen von CronetEngine unerwartete Ausnahmen aufgrund von Fehlern wie Geräten ausgelöst werden, die eine aktualisierte Version der Google Play-Dienste erfordern.

Falls Cronet nicht aus den Google Play-Diensten geladen werden kann, gibt es eine weniger leistungsfähige Implementierung der Cronet-API, die verwendet werden kann. Wenn Sie diese Fallback-Implementierung verwenden möchten, benötigen Sie org.chromium.net:cronet-fallback und rufen new JavaCronetProvider(context).createBuilder() auf.

Netzwerkanfrage erstellen

In diesem Abschnitt wird beschrieben, wie Sie mithilfe der Cronet-Bibliothek eine Netzwerkanfrage erstellen und senden. Nach dem Senden der Netzwerkanfrage sollte Ihre App die Netzwerkantwort verarbeiten.

CronetEngine-Instanz erstellen und konfigurieren

Die Bibliothek bietet eine CronetEngine.Builder-Klasse, mit der Sie eine Instanz von CronetEngine erstellen können. Das folgende Beispiel zeigt, wie ein CronetEngine-Objekt erstellt wird:

Kotlin

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

Java

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

Hinweis :Es wird empfohlen, nur eine Instanz von CronetEngine zu erstellen. Eine einzelne Instanz kann mehrere asynchrone Anfragen senden. Außerdem unterstützt ein Speicherverzeichnis nicht den gleichzeitigen Zugriff durch mehrere CronetEngine-Instanzen. Weitere Informationen finden Sie unter setStoragePath().

Mit der Klasse Builder können Sie ein CronetEngine-Objekt konfigurieren und beispielsweise Optionen wie Caching und Datenkomprimierung bereitstellen. Weitere Informationen findest du unter CronetEngine.Builder.

Implementierung des Anfrage-Callbacks angeben

Um eine Implementierung des Callbacks bereitzustellen, musst du eine abgeleitete Klasse von UrlRequest.Callback erstellen und die erforderlichen abstrakten Methoden implementieren, wie im folgenden Beispiel gezeigt:

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

Hinweis: Der Einfachheit halber wird im vorherigen Codebeispiel eine Implementierung von UrlRequest.Callback erstellt, die eine Nachricht in das Log schreibt, wenn ein Netzwerkereignis eintritt. Weitere Informationen zum Implementieren des Callbacks findest du unter Netzwerkantwort verarbeiten.

Executor-Objekt zum Verwalten von Netzwerkaufgaben erstellen

Mit der Klasse Executor können Sie Netzwerkaufgaben ausführen. Um eine Instanz von Executor abzurufen, verwenden Sie eine der statischen Methoden der Executors-Klasse, die ein Executor-Objekt zurückgeben. Das folgende Beispiel zeigt, wie Sie mit der Methode newSingleThreadExecutor() ein Executor-Objekt erstellen:

Kotlin

val executor: Executor = Executors.newSingleThreadExecutor()

Java

Executor executor = Executors.newSingleThreadExecutor();

UrlRequest-Objekt erstellen und konfigurieren

Rufen Sie zum Erstellen der Netzwerkanfrage die Methode newUrlRequestBuilder() von CronetEngine auf und übergeben Sie die Ziel-URL, eine Instanz Ihrer Callback-Klasse und das Executor-Objekt. Die Methode newUrlRequestBuilder() gibt ein Objekt UrlRequest.Builder zurück, mit dem Sie das Objekt UrlRequest erstellen können. Hier ein Beispiel:

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

Sie können die Klasse Builder verwenden, um die Instanz von UrlRequest zu konfigurieren. Sie können beispielsweise eine Priorität oder das HTTP-Verb angeben. Weitere Informationen findest du unter UrlRequest.Builder.

Rufen Sie die Methode start() der Anfrage auf, um die Netzwerkaufgabe zu starten:

Kotlin

request.start()

Java

request.start();

Wenn Sie der Anleitung in diesem Abschnitt folgen, können Sie mit Cronet eine Netzwerkanfrage erstellen und senden. Der Einfachheit halber gibt die Beispielimplementierung von UrlRequest.Callback jedoch nur eine Nachricht im Log aus. Im folgenden Abschnitt wird gezeigt, wie Sie eine Callback-Implementierung bereitstellen, die nützlichere Szenarien unterstützt, z. B. das Extrahieren von Daten aus der Antwort und das Erkennen eines Fehlers in der Anfrage.

Netzwerkantwort verarbeiten

Nach dem Aufrufen der Methode start() wird der Lebenszyklus der Cronet-Anfrage initiiert. Die Anwendung sollte die Anfrage während des Lebenszyklus verwalten, indem sie einen Callback angibt. Weitere Informationen zum Lebenszyklus finden Sie unter Cronet-Anfragelebenszyklus. Sie können einen Callback angeben. Dazu erstellen Sie eine abgeleitete Klasse von UrlRequest.Callback und implementieren die folgenden Methoden:

onRedirectReceived()

Wird aufgerufen, wenn der Server als Antwort auf die ursprüngliche Anfrage einen HTTP-Weiterleitungscode ausgibt. Verwenden Sie die Methode followRedirect(), um der Weiterleitung zum neuen Ziel zu folgen. Verwenden Sie andernfalls die Methode cancel(). Das folgende Beispiel zeigt, wie die Methode implementiert wird:

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

Wird aufgerufen, wenn der endgültige Satz von Headern empfangen wird. Die Methode onResponseStarted() wird erst aufgerufen, wenn alle Weiterleitungen befolgt wurden. Der folgende Code zeigt eine Beispielimplementierung der Methode:

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

Hinweis: Die Statuscodes 4xx und 5xx gelten aus Cronet-Perspektive nicht als Fehler. Sie sollten dennoch versuchen, die Antwort mit der Methode read() zu lesen, da sie Daten enthalten könnte. Sie können die Anfrage auch mit der Methode cancel() abbrechen. Diese Aktionen sorgen dafür, dass die Anfrage in einen endgültigen Zustand versetzt wird.

onReadCompleted()

Wird immer dann aufgerufen, wenn ein Teil des Antworttexts gelesen wurde. Das folgende Codebeispiel zeigt, wie die Methode implementiert und der Antworttext extrahiert wird:

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

Wird aufgerufen, wenn die Netzwerkanfrage erfolgreich abgeschlossen wurde. Das folgende Beispiel zeigt, wie die Methode implementiert wird:

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

Wird aufgerufen, wenn die Anfrage nach dem Aufruf der Methode start() aus irgendeinem Grund fehlgeschlagen ist. Das folgende Beispiel zeigt, wie die Methode implementiert und Informationen zum Fehler abgerufen werden:

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

Wird aufgerufen, wenn die Anfrage mit der Methode cancel() abgebrochen wurde. Nach dem Aufruf werden keine anderen Methoden der Klasse UrlRequest.Callback aufgerufen. Mit dieser Methode können Sie Ressourcen freigeben, die zur Verarbeitung einer Anfrage zugewiesen sind. Das folgende Beispiel zeigt, wie die Methode implementiert wird:

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