إرسال طلب بسيط

تعرَّف على كيفية استخدام مكتبة Cronet لإجراء عمليات الشبكة في تطبيق Android. Cronet هي حزمة شبكات Chromium المتاحة كمكتبة يمكنك استخدامها في تطبيقاتك. لمزيد من المعلومات حول ميزات المكتبة، يُرجى الاطّلاع على تنفيذ عمليات الشبكة باستخدام Cronet.

إعداد المكتبة في مشروعك

اتّبِع الخطوات التالية لإضافة تبعية إلى مكتبة Cronet في مشروعك:

1. تأكَّد من أنّ "استوديو Android" قد أدرج مرجعًا إلى مستودع Maven من Google في ملف settings.gradle الخاص بمشروعك، كما هو موضّح في المثال التالي:

   أنيق

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

   Kotlin

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

2. أضِف مرجعًا إلى مكتبة برامج "خدمات Google Play" لـ Cronet في قسم dependencies من ملف build.gradle الخاص بوحدة تطبيقك، كما هو موضّح في المثال التالي:

   أنيق

   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 objects created after you add this dependency use Cronet loaded from Google Play services. لمنع حدوث استثناءات غير متوقّعة أثناء إنشاء CronetEngine (مثل الأجهزة التي تتطلّب إصدارًا محدَّثًا من "خدمات Google Play")، يمكنك استدعاء CronetProviderInstaller.installProvider(Context) قبل إنشاء عناصر CronetEngine.

في الحالات التي يتعذّر فيها تحميل Cronet من "خدمات Google Play"، يتوفّر إصدار أقل كفاءة من واجهة برمجة تطبيقات Cronet يمكن استخدامه. لاستخدام هذه الطريقة الاحتياطية، يجب الاعتماد على 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();

ملاحظة: أنشِئ مثيلاً واحدًا فقط من CronetEngine. يمكن لمثيل واحد إرسال طلبات غير متزامنة متعددة. بالإضافة إلى ذلك، لا يتيح دليل التخزين الوصول المتزامن من خلال نُسخ متعددة من "CronetEngine". لمزيد من المعلومات، يُرجى الاطّلاع على setStoragePath().

يمكنك استخدام فئة 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.");
  }
}

ملاحظة: للتبسيط، ينشئ مثال الرمز السابق عملية تنفيذ لـ UrlRequest.Callback يكتب رسالة في السجلّ عند وقوع حدث في الشبكة. لمزيد من التفاصيل حول كيفية تنفيذ طلب معاودة الاتصال، يُرجى الاطّلاع على معالجة استجابة الشبكة.

إنشاء عنصر Executor لإدارة مهام الشبكة

يمكنك استخدام الفئة Executor لتنفيذ مهام الشبكة. للحصول على مثيل من Executor، استخدِم إحدى الطرق الثابتة لفئة Executors التي تعرض عنصر Executor. يوضّح المثال التالي كيفية إنشاء عنصر Executor باستخدام الإجراء newSingleThreadExecutor():

Kotlin

val executor: Executor = Executors.newSingleThreadExecutor()

Java

Executor executor = Executors.newSingleThreadExecutor();

إنشاء كائن UrlRequest وضبطه

لإنشاء طلب الشبكة، استدعِ الطريقة newUrlRequestBuilder() الخاصة بـ CronetEngine مع تمرير عنوان URL المقصود ومثيل لفئة رد الاتصال وعنصر المنفِّذ. تعرض الطريقة 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();

By following the instructions in this section, you can create and send a network request using Cronet. ومع ذلك، من أجل التبسيط، فإن مثال تنفيذ UrlRequest.Callback يطبع رسالة فقط في السجلّ. يوضّح القسم التالي كيفية توفير تنفيذ لعملية ردّ اتصال يتيح سيناريوهات أكثر فائدة، مثل استخراج البيانات من الاستجابة ورصد أي عطل في الطلب.

معالجة استجابة الشبكة

بعد استدعاء الإجراء start()، تبدأ Cronet مراحل نشاط الطلب. يمكنك إدارة الطلب خلال مراحل النشاط من خلال تحديد دالة استدعاء. لمزيد من المعلومات حول دورة الحياة، يُرجى الاطّلاع على دورة حياة طلب Cronet. يمكنك تحديد رد اتصال من خلال إنشاء فئة فرعية من UrlRequest.Callback وتنفيذ الطرق التالية:

onRedirectReceived()

تستدعي مكتبة Cronet هذه الطريقة عندما يُصدر الخادم رمز إعادة توجيه HTTP استجابةً للطلب الأصلي. لتتبُّع عملية إعادة التوجيه إلى الوجهة الجديدة، استخدِم طريقة 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();
}

ملاحظة: لا تُعتبر رموز الحالة 4xx و5xx أخطاءً من وجهة نظر Cronet. يجب محاولة قراءة الردّ باستخدام طريقة read() لأنّه قد يحتوي على بعض البيانات. يمكنك أيضًا إلغاء الطلب باستخدام طريقة cancel(). تضمن هذه الإجراءات وصول الطلب إلى حالة نهائية.

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

تستدعي Cronet هذه الطريقة إذا تعذّر تنفيذ الطلب لأي سبب بعد أن يستدعي تطبيقك طريقة start(). يوضّح المثال التالي كيفية تنفيذ الطريقة والحصول على معلومات عن الخطأ:

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

تستدعي Cronet هذه الطريقة إذا تم إلغاء الطلب باستخدام طريقة cancel(). بعد أن تستدعي 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.
  ...
}