傳送簡單的要求

瞭解如何使用 Cronet 程式庫在 Android 應用程式中執行網路作業。Cronet 是 Chromium 網路堆疊,可做為程式庫供您在應用程式中使用。如要進一步瞭解程式庫功能,請參閱「使用 Cronet 執行網路作業」。

在專案中設定程式庫

請按照下列步驟,在專案中新增 Cronet 程式庫的依附元件:

  1. 確認 Android Studio 已在專案的 settings.gradle 檔案中加入 Google Maven 存放區的參照,如以下範例所示:

    Groovy

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

    Kotlin

    dependencyResolutionManagement {
       ...
       repositories {
           ...
           google()
       }
    }
  2. 在應用程式模組 build.gradle 檔案的 dependencies 區段中,加入 Cronet 專用 Google Play 服務用戶端程式庫的參照,如以下範例所示:

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

新增這項依附元件後,建立的 CronetEngine 物件會使用從 Google Play 服務載入的 Cronet。為避免在建立 CronetEngine 時發生非預期的例外狀況 (例如裝置需要更新版本的 Google Play 服務),請在建立 CronetEngine 物件前呼叫 CronetProviderInstaller.installProvider(Context)。

如果無法從 Google Play 服務載入 Cronet,可以使用效能較低的 Cronet API 實作。如要使用這個備用實作,請依附 org.chromium.net:cronet-fallback 並呼叫 new JavaCronetProvider(context).createBuilder()。

建立網路要求

本節說明如何使用 Cronet 程式庫建立及傳送網路要求。傳送網路要求後,應用程式必須處理網路回應。

建立及設定 CronetEngine 執行個體

程式庫提供 CronetEngine.Builder 類別,可用於建立 CronetEngine 的例項。以下範例說明如何建立 CronetEngine 物件:

Kotlin

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

Java

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

您可以使用 Builder 類別設定 CronetEngine 物件。例如提供快取和資料壓縮等選項。詳情請參閱 CronetEngine.Builder。

提供要求回呼的實作

如要提供回呼的實作,請建立 UrlRequest.Callback 的子類別,並實作必要的抽象方法,如以下範例所示:

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

建立 Executor 物件來管理網路工作

您可以使用 Executor 類別執行網路工作。如要取得 Executor 的例項,請使用 Executors 類別中會傳回 Executor 物件的其中一個靜態方法。以下範例說明如何使用 newSingleThreadExecutor() 方法建立 Executor 物件:

Kotlin

val executor: Executor = Executors.newSingleThreadExecutor()

Java

Executor executor = Executors.newSingleThreadExecutor();

建立及設定 UrlRequest 物件

如要建立網路要求,請呼叫 CronetEngine 的 newUrlRequestBuilder() 方法,傳遞到達網頁網址、回呼類別的例項,以及執行程式物件。newUrlRequestBuilder() 方法會傳回 UrlRequest.Builder 物件,可用於建立 UrlRequest 物件,如以下範例所示:

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

您可以使用 Builder 類別設定 UrlRequest 的例項。例如,您可以指定優先順序或 HTTP 動詞。詳情請參閱 UrlRequest.Builder。

如要啟動網路工作,請呼叫要求的 start() 方法:

Kotlin

request.start()

Java

request.start();

按照本節中的操作說明,您可以使用 Cronet 建立及傳送網路要求。不過,為了簡單起見,UrlRequest.Callback 的實作範例只會將訊息輸出至記錄。下一節將說明如何提供回呼實作,支援更實用的情境,例如從回應中擷取資料,以及偵測要求失敗。

處理網路回應

呼叫 start() 方法後,Cronet 會啟動要求生命週期。指定回呼,在生命週期內管理要求。如要進一步瞭解生命週期,請參閱「Cronet 要求生命週期」。您可以建立 UrlRequest.Callback 的子類別,並實作下列方法,藉此指定回呼:

onRedirectReceived()

當伺服器發出 HTTP 重新導向代碼,以回應原始要求時,Cronet 會叫用這個方法。如要按照重新導向前往新目的地,請使用 followRedirect() 方法。否則,請使用 cancel() 方法。以下範例說明如何實作這個方法:

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

Cronet 收到最後一組標頭時,會叫用這個方法。Cronet 只會在追蹤所有重新導向後叫用 onResponseStarted()。以下程式碼為該方法的實作範例:

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

每當讀取部分回應內文時,Cronet 就會叫用這個方法。以下程式碼範例說明如何實作方法及擷取回應主體:

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

網路要求成功完成時,Cronet 會叫用這個方法。以下範例說明如何實作這個方法:

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

如果應用程式呼叫 start() 方法後,要求因任何原因失敗,Cronet 就會叫用這個方法。以下範例說明如何實作方法,並取得錯誤相關資訊:

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

如果使用 cancel() 方法取消要求,Cronet 會叫用這個方法。Cronet 叫用 onCanceled() 後,不會叫用 UrlRequest.Callback 類別的任何其他方法。您可以使用這個方法,釋出分配給處理要求的資源。以下範例說明如何實作這個方法:

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