EnvironmentClient

interface EnvironmentClient

العميل للوصول إلى واجهات برمجة التطبيقات ذات الصلة بالبيئة

استخدِم EnvironmentClientFactory لإنشاء مثيل.

ملخّص

الوظائف العامة
suspend Environment

تعرض Environment.
ListenableFuture<Environment>

تعرض Environment.
suspend PrepareEnvironmentResponse
prepareEnvironment(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
)

تُعِدّ هذه السمة بيئة الجهاز.
ListenableFuture<PrepareEnvironmentResponse>
prepareEnvironmentAsync(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
)

تُعِدّ هذه السمة بيئة الجهاز.

الوظائف العامة

getEnvironment

suspend fun getEnvironment(request: GetEnvironmentRequest): Environment

تعرض Environment. يساعد المتصل في معرفة ما إذا كانت البيئة جاهزة أم لا.

الرميات
com.google.android.managementapi.common.exceptions.InvalidArgumentException

في حال كانت الأدوار المطلوبة غير صالحة
com.google.android.managementapi.common.exceptions.InternalException

في حال تعذّر إجراء المكالمة بسبب خطأ داخلي
com.google.android.managementapi.common.exceptions.ApiLevelException

إذا كان مستوى واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) على الجهاز غير كافٍ لأداء أدوار معيّنة مطلوبة (قد يكون ذلك بالإضافة إلى الحد الأدنى العام لمستوى واجهة برمجة التطبيقات المطلوب لإجراء المكالمة نفسها). يتطلّب {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} المستوى 23 من واجهة برمجة التطبيقات أو مستوى أعلى. تتطلّب أي أدوار أخرى المستوى 28 من واجهة برمجة التطبيقات أو المستويات الأحدث.

getEnvironmentAsync

fun getEnvironmentAsync(request: GetEnvironmentRequest): ListenableFuture<Environment>

تعرض Environment. يساعد المتصل في معرفة ما إذا كانت البيئة جاهزة أم لا.

المرتجعات
ListenableFuture<Environment>

ListenableFuture يلتف حول النتيجة. يمكن أن يكون ذلك:

  • تمثّل هذه السمة قيمة مستقبلية ناجحة تتضمّن Environment، في حال النجاح.

  • قيمة غير صالحة في المستقبل InvalidArgumentException، إذا كانت الأدوار المطلوبة غير صالحة.

  • قيمة مستقبلية غير ناجحة تتضمّن InternalException، إذا تعذّر إجراء المكالمة بسبب خطأ داخلي
الرميات
com.google.android.managementapi.common.exceptions.ApiLevelException

إذا كان مستوى واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) على الجهاز غير كافٍ لأداء أدوار معيّنة مطلوبة (قد يكون ذلك بالإضافة إلى الحد الأدنى العام لمستوى واجهة برمجة التطبيقات المطلوب لإجراء المكالمة نفسها). يتطلّب {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} المستوى 23 من واجهة برمجة التطبيقات أو مستوى أعلى. تتطلّب أي أدوار أخرى المستوى 28 من واجهة برمجة التطبيقات أو المستويات الأحدث.

prepareEnvironment

suspend fun prepareEnvironment(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
): PrepareEnvironmentResponse

تُعِدّ هذه السمة بيئة الجهاز.

يُطلب من المستخدم تثبيت تطبيق Android Device Policy اللازم. يتم مواصلة عملية التثبيت إذا وافق المستخدم على الطلب. بعد اكتمال عملية التثبيت، ينفّذ عمليات للتأكّد من أنّ تطبيق "سياسة Android للأجهزة" جاهز.

المعلمات
notificationServiceComponentName: ComponentName?

ComponentName الخدمة التي يتم تمديدها NotificationReceiverService وفي حال توفُّرها، يجب أن تكون مكوّنًا صالحًا تابعًا لتطبيق الاتصال، ويجب تصديرها في ملف البيان. لتلقّي إشعارات بأحداث "إعداد البيئة"، عليك إجراء ما يلي:

  1. تنفيذ واجهة EnvironmentListener في تطبيقك

  2. قدِّم عملية تنفيذ لكيفية التعامل مع الأحداث التي تم تلقّيها.

  3. وسِّع NotificationReceiverService وقدِّم مثيلاً من EnvironmentListener.

  4. أضِف فئة NotificationReceiverService الموسّعة إلى ملف AndroidManifest.xml وتأكَّد من تصديرها.

على سبيل المثال:

class MyEnvironmentListener : EnvironmentListener {
  override fun onEnvironmentEvent(event: EnvironmentEvent) {
    // Handle the environment event.
  }
}

class MyNotificationReceiverService : NotificationReceiverService() {
  override fun getPrepareEnvironmentListener(): EnvironmentListener? {
    return MyEnvironmentListener()
  }
}
المرتجعات
PrepareEnvironmentResponse

PrepareEnvironmentResponse الذي يحتوي على تفاصيل حول الحالة النهائية لعملية إعداد البيئة.
الرميات
com.google.android.managementapi.common.exceptions.InvalidArgumentException

الشرط:

  • ‫[notificationServiceComponentName] ليس مكونًا صالحًا تابعًا للتطبيق الذي يتم استدعاؤه أو لم يتم تصديره في البيان.
  • تتضمّن الأدوار المطلوبة {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} ولم يتم تقديم {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} أو لا يمتد إلى {@code android.app.admin.DeviceAdminReceiver}.
  • الأدوار المطلوبة غير صالحة.
java.lang.SecurityException

إذا لم يكن لدى المتصل إذن بالاتصال بواجهة برمجة التطبيقات هذه.
com.google.android.managementapi.environment.GooglePlayServicesAppNotUpdatedException

إذا كانت "خدمات Google Play" قديمة
com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateUnrecoverableException

في حال تعذُّر تثبيت تطبيق "سياسة Android للأجهزة" أو تحديثه وكان الخطأ غير قابل للاسترداد
com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateRecoverableException

إذا تعذّر تثبيت تطبيق "سياسة أجهزة Android" أو تحديثه وكان الخطأ قابلاً للاسترداد (على سبيل المثال، تعذّر الطلب بسبب مشاكل مؤقتة في الشبكة)، يمكن إعادة محاولة الطلب.
com.google.android.managementapi.environment.AndroidDevicePolicyInstallConsentDeclinedException

إذا رفض المستخدم تثبيت تطبيق Android Device Policy
com.google.android.managementapi.environment.AndroidDevicePolicyInstallConsentDismissedException

إذا أغلق المستخدم شاشة طلب الموافقة على التثبيت
com.google.android.managementapi.common.exceptions.InternalException

في حال تعذّر إجراء المكالمة بسبب خطأ داخلي
com.google.android.managementapi.environment.PlayStoreUpdateUnrecoverableException

في حال تعذّر تحديث "متجر Play"
com.google.android.managementapi.common.exceptions.ApiLevelException

إذا كان مستوى واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) على الجهاز غير كافٍ لأدوار معيّنة مطلوبة (قد يكون هذا بالإضافة إلى الحد الأدنى العام لمستوى واجهة برمجة التطبيقات المطلوب للمكالمة نفسها)، يتطلّب {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} المستوى 23 من واجهة برمجة التطبيقات أو مستوى أعلى. تتطلّب أي أدوار أخرى المستوى 28 من واجهة برمجة التطبيقات أو المستويات الأحدث.

prepareEnvironmentAsync

fun prepareEnvironmentAsync(
    request: PrepareEnvironmentRequest,
    notificationServiceComponentName: ComponentName?
): ListenableFuture<PrepareEnvironmentResponse>

تُعِدّ هذه السمة بيئة الجهاز.

يُطلب من المستخدم تثبيت تطبيق Android Device Policy اللازم. يتم مواصلة عملية التثبيت إذا وافق المستخدم على الطلب. بعد اكتمال عملية التثبيت، ينفّذ عمليات للتأكّد من أنّ تطبيق "سياسة Android للأجهزة" جاهز.

المعلمات
notificationServiceComponentName: ComponentName?

ComponentName الخدمة التي يتم تمديدها NotificationReceiverService وفي حال توفُّرها، يجب أن تكون مكوّنًا صالحًا تابعًا لتطبيق الاتصال، ويجب تصديرها في ملف البيان. لتلقّي إشعارات بشأن أحداث إعداد البيئة، عليك إجراء ما يلي:

  1. تنفيذ واجهة EnvironmentListener في تطبيقك

  2. قدِّم عملية تنفيذ لكيفية التعامل مع الأحداث التي تم تلقّيها.

  3. وسِّع NotificationReceiverService وقدِّم مثيلاً من EnvironmentListener.

  4. أضِف فئة NotificationReceiverService الموسّعة إلى ملف AndroidManifest.xml وتأكَّد من تصديرها.

على سبيل المثال:

class MyEnvironmentListener : EnvironmentListener {
  override fun onEnvironmentEvent(event: EnvironmentEvent) {
    // Handle the environment event.
  }
}

class MyNotificationReceiverService : NotificationReceiverService() {
  override fun getPrepareEnvironmentListener(): EnvironmentListener? {
    return MyEnvironmentListener()
  }
}
المرتجعات
ListenableFuture<PrepareEnvironmentResponse>

ListenableFuture يلتف حول النتيجة. يمكن أن يكون ذلك

  • تغليف ناجح لمستقبل يحتوي على تفاصيل حول الحالة النهائية لعملية إعداد البيئةPrepareEnvironmentResponse

  • حالة مستقبل فاشل تتضمّن InvalidArgumentException إذا:

    • [notificationServiceComponentName] ليس مكوّنًا صالحًا تابعًا للتطبيق الذي تم استدعاؤه أو لم يتم تصديره في البيان.
    • الأدوار المطلوبة غير صالحة.
    • تتضمّن الأدوار المطلوبة {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} ولم يتم تقديم {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} أو لا يمتد إلى {@code android.app.admin.DeviceAdminReceiver}.

  • قيمة مستقبلية غير ناجحة تتضمّن SecurityException، إذا لم يكن مقدّم الطلب مخوّلاً بطلب البيانات من واجهة برمجة التطبيقات هذه.

  • تعذُّر تنفيذ عملية مستقبلية تتضمّن GooglePlayServicesAppNotUpdatedException إذا كانت "خدمات Google Play" غير محدَّثة

  • عنصر Future فاشل يضم AndroidDevicePolicyInstallOrUpdateUnrecoverableException إذا تعذّر تثبيت "سياسة أجهزة Android" أو تحديثها وكان الخطأ غير قابل للاسترداد.

  • يحدث خطأ في عملية التغليف المستقبلية عند تعذُّر تثبيت تطبيق "سياسة أجهزة Android" أو تحديثه، ويكون الخطأ قابلاً للاسترداد (على سبيل المثال، تعذّر تنفيذ الطلب بسبب مشاكل مؤقتة في الشبكة)، وبالتالي يمكن إعادة محاولة تنفيذ الطلب.AndroidDevicePolicyInstallOrUpdateRecoverableException

  • سيتم عرض قيمة Future غير ناجحة تتضمّن AndroidDevicePolicyInstallConsentDeclinedException إذا رفض المستخدم تثبيت تطبيق Android Device Policy.

  • عنصر Future غير ناجح يضمّ AndroidDevicePolicyInstallConsentDismissedException إذا أغلق المستخدم شاشة الموافقة على التثبيت.

  • قيمة مستقبلية غير ناجحة تتضمّن InternalException، إذا تعذّر إجراء المكالمة بسبب خطأ داخلي

  • قيمة مستقبلية فاشلة تتضمّن PlayStoreUpdateUnrecoverableException في حال تعذّر التحديث من "متجر Play".
الرميات
com.google.android.managementapi.common.exceptions.ApiLevelException

إذا كان مستوى واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) على الجهاز غير كافٍ لأدوار معيّنة مطلوبة يتطلّب {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} المستوى 23 من واجهة برمجة التطبيقات أو مستوى أعلى. تتطلّب أي أدوار أخرى المستوى 28 من واجهة برمجة التطبيقات أو المستويات الأحدث.