EnvironmentClient

interface EnvironmentClient

לקוח לגישה לממשקי API שקשורים לסביבה.

אפשר להשתמש ב-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

אם רמת ה-API של ערכת ה-SDK במכשיר לא מספיקה לתפקידים מסוימים שנדרשים (יכול להיות שזה בנוסף לדרישת רמת API מינימלית כללית לקריאה עצמה). ‫{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} דורש רמת API‏ 23 ומעלה. כל תפקיד אחר דורש רמת API‏ 28 ומעלה.

getEnvironmentAsync

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

הפונקציה מחזירה את הערך Environment. הוא עוזר למתקשר לדעת אם הסביבה מוכנה או לא.

החזרות
ListenableFuture<Environment>

תג ListenableFuture שמקיף את התוצאה. הסיבה יכולה להיות:

  • עתיד מוצלח שעוטף Environment, במקרה של הצלחה.

  • ‫A failed future wrapping a InvalidArgumentException, if the requested roles are not valid.

  • אובייקט Future שנכשל ועוטף InternalException, אם הקריאה נכשלה בגלל שגיאה פנימית.
זריקות
com.google.android.managementapi.common.exceptions.ApiLevelException

אם רמת ה-API של ערכת ה-SDK במכשיר לא מספיקה לתפקידים מסוימים שנדרשים (יכול להיות שזה בנוסף לדרישת רמת API מינימלית כללית לקריאה עצמה). ‫{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} דורש רמת API‏ 23 ומעלה. כל תפקיד אחר דורש רמת API‏ 28 ומעלה.

prepareEnvironment

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

הכנת סביבת המכשיר.

המשתמשים יקבלו הנחיה להתקין את אפליקציית 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

אם למתקשר אין הרשאה להתקשר ל-API הזה.
com.google.android.managementapi.environment.GooglePlayServicesAppNotUpdatedException

אם Google Play Services לא עדכני.
com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateUnrecoverableException

אם ההתקנה או העדכון של Android Device Policy נכשלים והשגיאה לא ניתנת לתיקון.
com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateRecoverableException

אם האפליקציה Android Device Policy לא מצליחה להתקין או להתעדכן והשגיאה ניתנת לתיקון (למשל, הבקשה נכשלה בגלל בעיות זמניות ברשת), אפשר לנסות שוב לשלוח את הבקשה.
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

אם רמת ה-API של ערכת ה-SDK של המכשיר לא מספיקה לתפקידים מסוימים שנדרשים (יכול להיות שזה בנוסף לדרישת רמת API מינימלית כללית לקריאה עצמה).{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} דורש רמת API ‏23 ומעלה. כל תפקיד אחר דורש רמת API‏ 28 ומעלה.

prepareEnvironmentAsync

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

הכנת סביבת המכשיר.

המשתמשים יקבלו הנחיה להתקין את אפליקציית 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 יכיל פרטים על הסטטוס הסופי של הכנת הסביבה.

  • ‫Future שנכשלת ועוטפת InvalidArgumentException אם:

    • ‫[notificationServiceComponentName] הוא לא רכיב תקין ששייך לאפליקציה שמבצעת את הקריאה או שהוא לא מיוצא במניפסט.
    • התפקידים המבוקשים לא חוקיים.
    • התפקידים המבוקשים כוללים את {@code Role.RoleType.DEVICE_POLICY_CONTROLLER} ולא סופק {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} או שהוא לא מרחיב את {@code android.app.admin.DeviceAdminReceiver}.

  • ‫Future שנכשל ועוטף SecurityException, אם הגורם ששלח את הקריאה לא מורשה לקרוא ל-API הזה.

  • העטיפה של GooglePlayServicesAppNotUpdatedException נכשלה כי Google Play Services לא עדכני.

  • ‫Future שנכשל ועוטף AndroidDevicePolicyInstallOrUpdateUnrecoverableException אם ההתקנה או העדכון של Android Device Policy נכשלים והשגיאה לא ניתנת לתיקון.

  • העטיפה העתידית שנכשלה מכילה AndroidDevicePolicyInstallOrUpdateRecoverableException אם ההתקנה או העדכון של אפליקציית Android Device Policy נכשלו והשגיאה ניתנת לתיקון (למשל, הבקשה נכשלה בגלל בעיות זמניות ברשת), כך שאפשר לנסות שוב את הבקשה.

  • הפעולה נכשלה בעתיד, ועוטפת AndroidDevicePolicyInstallConsentDeclinedException אם המשתמש מסרב להתקין את אפליקציית Android Device Policy.

  • ‫Future שנכשל ועוטף AndroidDevicePolicyInstallConsentDismissedException אם המשתמש סוגר את מסך ההסכמה להתקנה.

  • אובייקט Future שנכשל ועוטף InternalException, אם הקריאה נכשלה בגלל שגיאה פנימית.

  • ‫A failed future wrapping a PlayStoreUpdateUnrecoverableException if the Play Store update failed.
זריקות
com.google.android.managementapi.common.exceptions.ApiLevelException

אם רמת ה-API של ערכת ה-SDK במכשיר לא מספיקה לתפקידים מסוימים שנדרשים. ‫{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} דורש רמת API‏ 23 ומעלה. כל תפקיד אחר דורש רמת API‏ 28 ומעלה.