یک درخواست ساده ارسال کنید

با نحوه استفاده از کتابخانه Cronet برای انجام عملیات شبکه در برنامه Android خود آشنا شوید. Cronet پشته شبکه Chromium است که به عنوان یک کتابخانه برای استفاده در برنامه های خود در دسترس شما قرار گرفته است. برای اطلاعات بیشتر در مورد ویژگی های کتابخانه، به انجام عملیات شبکه با استفاده از Cronet مراجعه کنید.

کتابخانه را در پروژه خود راه اندازی کنید

برای افزودن یک وابستگی به کتابخانه Cronet در پروژه خود این مراحل را دنبال کنید:

1. همانطور که در مثال زیر نشان داده شده است، بررسی کنید که Android Studio یک مرجع به مخزن Maven Google در فایل settings.gradle پروژه شما داشته باشد:

   شیار

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

   کاتلین

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

2. همانطور که در مثال زیر نشان داده شده است، یک مرجع به کتابخانه سرویس‌های Google Play برای Cronet در بخش dependencies فایل build.gradle ماژول برنامه خود اضافه کنید:

   شیار

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

   کاتلین

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

اشیاء CronetEngine که پس از اضافه شدن این وابستگی ایجاد می شوند، از Cronet بارگیری شده از سرویس های Google Play استفاده می کنند. قبل از ایجاد اشیاء CronetEngine با CronetProviderInstaller.installProvider(Context) تماس بگیرید تا از ایجاد استثناهای غیرمنتظره در حین ایجاد CronetEngine به دلیل خطاهایی مانند دستگاه‌هایی که به نسخه به‌روزشده خدمات Google Play نیاز دارند، جلوگیری کنید.

در مواردی که Cronet را نمی توان از سرویس های Google Play بارگیری کرد، یک پیاده سازی با عملکرد کمتر از Cronet's API وجود دارد که می توان از آن استفاده کرد. برای استفاده از این پیاده‌سازی بازگشتی، به org.chromium.net:cronet-fallback وابسته باشید و new JavaCronetProvider(context).createBuilder() را فراخوانی کنید.

درخواست شبکه ایجاد کنید

این بخش نحوه ایجاد و ارسال درخواست شبکه با استفاده از کتابخانه Cronet را نشان می دهد. پس از ارسال درخواست شبکه، برنامه شما باید پاسخ شبکه را پردازش کند .

یک نمونه از CronetEngine ایجاد و پیکربندی کنید

این کتابخانه یک کلاس CronetEngine.Builder ارائه می دهد که می توانید از آن برای ایجاد یک نمونه از CronetEngine استفاده کنید. مثال زیر نحوه ایجاد یک شیء CronetEngine را نشان می دهد:

کاتلین

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

جاوا

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

توجه: توصیه می شود فقط یک نمونه از CronetEngine ایجاد کنید. یک نمونه می تواند چندین درخواست ناهمزمان ارسال کند. علاوه بر این، دایرکتوری ذخیره سازی از دسترسی همزمان توسط چندین نمونه CronetEngine پشتیبانی نمی کند. برای اطلاعات بیشتر، setStoragePath() را ببینید.

شما می توانید از کلاس Builder برای پیکربندی یک شی CronetEngine استفاده کنید، به عنوان مثال می توانید گزینه هایی مانند کش و فشرده سازی داده ها را ارائه دهید. برای اطلاعات بیشتر، CronetEngine.Builder را ببینید.

اجرای درخواست پاسخ به تماس را ارائه دهید

برای ارائه یک پیاده سازی callback، یک زیر کلاس از UrlRequest.Callback ایجاد کنید و روش های انتزاعی مورد نیاز را مانند مثال زیر پیاده سازی کنید:

کاتلین

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

جاوا

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() نشان می دهد:

کاتلین

val executor: Executor = Executors.newSingleThreadExecutor()

جاوا

Executor executor = Executors.newSingleThreadExecutor();

یک شی UrlRequest ایجاد و پیکربندی کنید

برای ایجاد درخواست شبکه، متد newUrlRequestBuilder() CronetEngine را فراخوانی کنید تا URL مقصد، نمونه‌ای از کلاس برگشت تماس شما و شی اجراکننده را ارسال کند. متد newUrlRequestBuilder() یک شی UrlRequest.Builder را برمی گرداند که می توانید از آن برای ایجاد شی UrlRequest استفاده کنید، همانطور که در مثال زیر نشان داده شده است:

کاتلین

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

val request: UrlRequest = requestBuilder.build()

جاوا

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

UrlRequest request = requestBuilder.build();

می توانید از کلاس Builder برای پیکربندی نمونه UrlRequest استفاده کنید. به عنوان مثال، می توانید یک اولویت یا فعل HTTP را مشخص کنید. برای اطلاعات بیشتر، به UrlRequest.Builder مراجعه کنید.

برای شروع کار شبکه، متد start() درخواست را فراخوانی کنید:

کاتلین

request.start()

جاوا

request.start();

با پیروی از دستورالعمل های این قسمت می توانید با استفاده از کرونت درخواست شبکه ایجاد و ارسال کنید. با این حال، برای سادگی، اجرای مثال UrlRequest.Callback فقط یک پیام را در گزارش چاپ می کند. بخش زیر نشان می‌دهد که چگونه می‌توان یک پیاده‌سازی بازگشت به تماس را ارائه کرد که از سناریوهای مفیدتر مانند استخراج داده‌ها از پاسخ و تشخیص شکست در درخواست پشتیبانی می‌کند.

پاسخ شبکه را پردازش کنید

هنگامی که متد start() فراخوانی کردید، چرخه حیات درخواست Cronet آغاز می شود. برنامه شما باید درخواست را در طول چرخه عمر با تعیین یک تماس پاسخ مدیریت کند. برای کسب اطلاعات بیشتر در مورد چرخه حیات، به چرخه عمر درخواست Cronet مراجعه کنید. می توانید با ایجاد یک زیر کلاس از UrlRequest.Callback و پیاده سازی روش های زیر، یک callback تعیین کنید:

onRedirectReceived()

زمانی فراخوانی می شود که سرور در پاسخ به درخواست اصلی، کد تغییر مسیر HTTP را صادر می کند. برای دنبال کردن تغییر مسیر به مقصد جدید، از متد followRedirect() استفاده کنید. در غیر این صورت از روش cancel() استفاده کنید. مثال زیر نحوه پیاده سازی متد را نشان می دهد:

کاتلین

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

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

جاوا

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

هنگام دریافت مجموعه نهایی سرصفحه ها فراخوانی می شود. متد onResponseStarted() فقط پس از دنبال کردن همه تغییر مسیرها فراخوانی می شود. کد زیر نمونه ای از پیاده سازی متد را نشان می دهد:

کاتلین

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
}

جاوا

@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 از دیدگاه کرونت خطا محسوب نمی شوند. همچنان باید سعی کنید پاسخ را با استفاده از متد read() بخوانید زیرا ممکن است حاوی مقداری داده باشد. همچنین می توانید درخواست را با استفاده از متد cancel() لغو کنید. این اقدامات تضمین می کند که درخواست به حالت نهایی می رسد.

onReadCompleted()

هر زمان که بخشی از بدنه پاسخ خوانده شده باشد فراخوانی می شود. مثال کد زیر نحوه پیاده سازی متد و استخراج بدنه پاسخ را نشان می دهد:

کاتلین

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

جاوا

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

هنگامی که درخواست شبکه با موفقیت تکمیل شد فراخوانی می شود. مثال زیر نحوه پیاده سازی متد را نشان می دهد:

کاتلین

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

جاوا

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

onFailed()

اگر درخواست به هر دلیلی پس از فراخوانی متد start() ناموفق باشد، فراخوانی می شود. مثال زیر نحوه پیاده سازی متد و دریافت اطلاعات مربوط به خطا را نشان می دهد:

کاتلین

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

جاوا

@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() لغو شده باشد، فراخوانی می شود. پس از فراخوانی، هیچ روش دیگری از کلاس UrlRequest.Callback فراخوانی نمی شود. می توانید از این روش برای آزادسازی منابع اختصاص داده شده برای پردازش درخواست استفاده کنید. مثال زیر نحوه پیاده سازی متد را نشان می دهد:

کاتلین

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

جاوا

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