EnvironmentClient

public interface EnvironmentClient


用戶端可存取環境相關 API。

請使用 EnvironmentClientFactory 建立執行個體。

摘要

公用方法

abstract @NonNull Environment

傳回 Environment。

abstract @NonNull ListenableFuture<@NonNull Environment>

傳回 Environment。

abstract @NonNull PrepareEnvironmentResponse
prepareEnvironment(
    @NonNull PrepareEnvironmentRequest request,
    ComponentName notificationServiceComponentName
)

確認 Android Device Policy 應用程式已安裝並準備就緒,為裝置做好準備。

abstract @NonNull ListenableFuture<@NonNull PrepareEnvironmentResponse>
prepareEnvironmentAsync(
    @NonNull PrepareEnvironmentRequest request,
    ComponentName notificationServiceComponentName
)

確認 Android Device Policy 應用程式已安裝並準備就緒,為裝置做好準備。

公用方法

getEnvironment

abstract @NonNull Environment getEnvironment(@NonNull GetEnvironmentRequest request)

傳回 Environment。呼叫端可藉此瞭解環境是否已準備就緒。

擲回
com.google.android.managementapi.common.exceptions.InvalidArgumentException

如果要求的角色無效,或有任何角色設定了 extraCapabilities,額外功能是由 IT 管理員在裝置政策中授予,應用程式無法要求。

com.google.android.managementapi.common.exceptions.InternalException

如果呼叫因內部錯誤而失敗。

com.google.android.managementapi.common.exceptions.ApiLevelException

裝置的 SDK API 級別不符合特定要求角色的條件 (除了呼叫本身的一般最低 API 級別規定外,可能還有其他規定)。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 必須使用 API 級別 23 以上版本。其他角色則需要 API 級別 28 以上。

getEnvironmentAsync

abstract @NonNull ListenableFuture<@NonNull Environment> getEnvironmentAsync(@NonNull GetEnvironmentRequest request)

傳回 Environment。這有助於呼叫端瞭解環境是否已準備就緒。

傳回
@NonNull ListenableFuture<@NonNull Environment>

包裝結果的 ListenableFuture。可能的值如下:

  • 如果成功,則傳回包裝 Environment 的成功 Future。

  • 如果要求的角色無效,則會傳回失敗的 Future,其中包含 InvalidArgumentException。

  • 如果呼叫因內部錯誤而失敗,則會傳回包裝 InternalException 的失敗 Future。

擲回
com.google.android.managementapi.common.exceptions.InvalidArgumentException

如果任何要求的角色已設定 extraCapabilities。額外功能是由 IT 管理員在裝置政策中授予,應用程式無法要求。

com.google.android.managementapi.common.exceptions.ApiLevelException

裝置的 SDK API 級別不符合特定要求角色的條件 (除了呼叫本身的一般最低 API 級別規定外,可能還有其他規定)。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 必須使用 API 級別 23 以上版本。其他角色則需要 API 級別 28 以上。

prepareEnvironment

abstract @NonNull PrepareEnvironmentResponse prepareEnvironment(
    @NonNull PrepareEnvironmentRequest request,
    ComponentName notificationServiceComponentName
)

確認 Android Device Policy 應用程式已安裝並準備就緒,為裝置做好準備。

實際行為取決於情境:

  • 裝置信任流程:如果使用者未安裝 Android Device Policy 應用程式,系統會提示使用者安裝。如果已安裝應用程式,系統會自動更新。

  • 裝置註冊流程:自動安裝 Android Device Policy 應用程式 (如果尚未安裝),並確保應用程式可供使用,使用者無須進行任何操作。

參數
ComponentName notificationServiceComponentName

擴充 NotificationReceiverService 的服務 ComponentName。如果提供,則必須是屬於通話應用程式的有效元件,並在資訊清單中匯出。如要接收環境準備事件的通知,請按照下列步驟操作:

  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()
}
}
傳回
@NonNull 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}。
  • 要求的角色無效。
  • 任何要求角色都已設定 extraCapabilities。額外功能由 IT 管理員在裝置政策中授予,應用程式無法要求。
SecurityException

呼叫端未獲授權呼叫這個 API。

GooglePlayServicesAppNotUpdatedException

Google Play 服務並非最新版本。

AndroidDevicePolicyInstallOrUpdateUnrecoverableException

Android Device Policy 無法安裝或更新,且錯誤無法復原。

AndroidDevicePolicyInstallOrUpdateRecoverableException

如果 Android Device Policy 應用程式無法安裝或更新,且錯誤可復原 (例如因暫時性網路問題導致要求失敗),則可重試要求。

AndroidDevicePolicyInstallConsentDeclinedException

使用者拒絕安裝 Android Device Policy 應用程式。

AndroidDevicePolicyInstallConsentDismissedException

如果使用者關閉安裝同意畫面。

com.google.android.managementapi.common.exceptions.InternalException

如果呼叫因內部錯誤而失敗。

PlayStoreUpdateUnrecoverableException

如果 Play 商店更新失敗。

com.google.android.managementapi.common.exceptions.ApiLevelException

如果裝置的 SDK API 級別不足以支援某些要求的角色 (除了呼叫本身的一般最低 API 級別要求外,可能還有其他要求)。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 需要 API 級別 23 以上。其他角色則需要 API 級別 28 以上。

prepareEnvironmentAsync

abstract @NonNull ListenableFuture<@NonNull PrepareEnvironmentResponse> prepareEnvironmentAsync(
    @NonNull PrepareEnvironmentRequest request,
    ComponentName notificationServiceComponentName
)

確認 Android Device Policy 應用程式已安裝並準備就緒,為裝置做好準備。

實際行為取決於情境:

  • 裝置信任流程:如果使用者未安裝 Android Device Policy 應用程式,系統會提示使用者安裝。如果已安裝應用程式,系統會自動更新。

  • 裝置註冊流程:自動安裝 Android Device Policy 應用程式 (如果尚未安裝),並確保應用程式可供使用,使用者無須進行任何操作。

參數
ComponentName notificationServiceComponentName

擴充 NotificationReceiverService 的服務 ComponentName。如果提供,則必須是屬於通話應用程式的有效元件,並在資訊清單中匯出。如要接收環境準備事件的通知,請按照下列步驟操作:

  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()
}
}
傳回
@NonNull ListenableFuture<@NonNull PrepareEnvironmentResponse>

包裝結果的 ListenableFuture。可用的值包括:

擲回
com.google.android.managementapi.common.exceptions.InvalidArgumentException

如果任何要求的角色已設定 extraCapabilities。額外功能是由 IT 管理員在裝置政策中授予,應用程式無法要求。

com.google.android.managementapi.common.exceptions.ApiLevelException

裝置的 SDK API 級別不足以支援某些要求的角色。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 必須使用 API 級別 23 以上版本。其他角色則需要 API 級別 28 以上。