此页面由 Cloud Translation API 翻译。

EnvironmentClient

Kotlin |Java

interface EnvironmentClient

用于访问环境相关 API 的客户端。

使用 EnvironmentClientFactory 创建实例。

摘要

公共函数
`suspend Environment`	`getEnvironment(request: GetEnvironmentRequest)` 返回 `Environment`。
`ListenableFuture<Environment>`	`getEnvironmentAsync(request: GetEnvironmentRequest)` 返回 `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 API 级别不足以满足某些请求的角色（这可能除了调用本身的一般最低 API 级别要求之外）。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 需要 API 级别 23 或更高级别。任何其他角色都需要 API 级别 28 或更高级别。

getEnvironmentAsync

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

返回 Environment。它有助于来电者了解环境是否已准备就绪。

返回
`ListenableFuture<Environment>`	封装结果的 `ListenableFuture`。这个身份可以是以下任一项：一个成功完成的 future，封装了 `Environment`（如果成功）。如果所请求的角色无效，则返回封装了 `InvalidArgumentException` 的失败 future。如果因内部错误而导致调用失败，则为封装 `InternalException` 的失败 future。

ListenableFuture<Environment>

封装结果的 ListenableFuture。这个身份可以是以下任一项：

一个成功完成的 future，封装了 Environment（如果成功）。
如果所请求的角色无效，则返回封装了 InvalidArgumentException 的失败 future。
如果因内部错误而导致调用失败，则为封装 InternalException 的失败 future。

抛出
`com.google.android.managementapi.common.exceptions.ApiLevelException`	如果设备的 SDK API 级别不足以满足某些请求的角色（这可能除了调用本身的一般最低 API 级别要求之外）。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 需要 API 级别 23 或更高级别。任何其他角色都需要 API 级别 28 或更高级别。

prepareEnvironment

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

准备设备环境。

提示用户安装必需的 Android Device Policy 应用。如果用户接受提示，则继续安装。成功安装后，它会执行操作以确保 Android Device Policy 应用已准备就绪。

参数

参数
`notificationServiceComponentName: ComponentName?`	扩展 `NotificationReceiverService` 的服务的 `ComponentName`。如果提供，则必须是调用应用的有效组件，并且已在清单中导出。如需接收有关环境准备事件的通知，您需要执行以下操作：在应用中实现 `EnvironmentListener` 接口。提供有关如何处理接收到的事件的实现。扩展 NotificationReceiverService 并提供 `EnvironmentListener` 实例。将扩展的 NotificationReceiverService 类添加到 AndroidManifest.xml，并确保已导出该类。例如： class MyEnvironmentListener : EnvironmentListener { override fun onEnvironmentEvent(event: EnvironmentEvent) { // Handle the environment event. } } class MyNotificationReceiverService : NotificationReceiverService() { override fun getPrepareEnvironmentListener(): EnvironmentListener? { return MyEnvironmentListener() } }

notificationServiceComponentName: ComponentName?

扩展 NotificationReceiverService 的服务的 ComponentName。如果提供，则必须是调用应用的有效组件，并且已在清单中导出。如需接收有关环境准备事件的通知，您需要执行以下操作：

在应用中实现 EnvironmentListener 接口。
提供有关如何处理接收到的事件的实现。
扩展 NotificationReceiverService 并提供 EnvironmentListener 实例。
将扩展的 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 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 服务不是最新版本。
`com.google.android.managementapi.environment.AndroidDevicePolicyInstallOrUpdateUnrecoverableException`	如果 Android Device Policy 无法安装或更新，且错误无法恢复。
`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 API 级别不足以支持某些请求的角色（这可能是在调用本身的一般最低 API 级别要求之外）。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 需要 API 级别 23 或更高级别。任何其他角色都需要 API 级别 28 或更高级别。

prepareEnvironmentAsync

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

准备设备环境。

提示用户安装必需的 Android Device Policy 应用。如果用户接受提示，则继续安装。成功安装后，它会执行操作以确保 Android Device Policy 应用已准备就绪。

参数

参数
`notificationServiceComponentName: ComponentName?`	扩展 `NotificationReceiverService` 的服务的 `ComponentName`。如果提供，则必须是调用应用的有效组件，并且已在清单中导出。如需接收有关环境准备事件的通知，您需要执行以下操作：在应用中实现 `EnvironmentListener` 接口。提供有关如何处理接收到的事件的实现。扩展 NotificationReceiverService 并提供 `EnvironmentListener` 实例。将扩展的 NotificationReceiverService 类添加到 AndroidManifest.xml，并确保已导出该类。例如： class MyEnvironmentListener : EnvironmentListener { override fun onEnvironmentEvent(event: EnvironmentEvent) { // Handle the environment event. } } class MyNotificationReceiverService : NotificationReceiverService() { override fun getPrepareEnvironmentListener(): EnvironmentListener? { return MyEnvironmentListener() } }

notificationServiceComponentName: ComponentName?

在应用中实现 EnvironmentListener 接口。
提供有关如何处理接收到的事件的实现。
扩展 NotificationReceiverService 并提供 EnvironmentListener 实例。
将扩展的 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`。这可能是一个成功完成的 future，封装了一个 `PrepareEnvironmentResponse`，其中包含有关环境准备最终状态的详细信息。如果出现以下情况，则为封装 `InvalidArgumentException` 的失败 future： [notificationServiceComponentName] 不是调用应用所属的有效组件，或者未在清单中导出。所请求的角色无效。所请求的角色包含 {@code Role.RoleType.DEVICE_POLICY_CONTROLLER}，并且未提供 {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} 或所提供的 {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} 未扩展 {@code android.app.admin.DeviceAdminReceiver}。如果调用方无权调用此 API，则返回封装了 `SecurityException` 的失败 future。如果 Google Play 服务不是最新版本，则封装 `GooglePlayServicesAppNotUpdatedException` 的失败 future。如果 Android 设备政策无法安装或更新，且错误无法恢复，则包含 `AndroidDevicePolicyInstallOrUpdateUnrecoverableException` 的 future 会失败。如果 Android 设备政策应用未能安装或更新，且错误可恢复（例如，请求因暂时性网络问题而失败），则包含 `AndroidDevicePolicyInstallOrUpdateRecoverableException` 的失败 future。因此，可以重试请求。如果用户拒绝安装 Android Device Policy 应用，则包含 `AndroidDevicePolicyInstallConsentDeclinedException` 的失败 future。如果用户关闭安装同意屏幕，则包装 `AndroidDevicePolicyInstallConsentDismissedException` 的失败 future。如果因内部错误而导致调用失败，则为封装 `InternalException` 的失败 future。如果 Play 商店更新失败，则包含 `PlayStoreUpdateUnrecoverableException` 的失败 future。

ListenableFuture<PrepareEnvironmentResponse>

封装结果的 ListenableFuture。这可能是

一个成功完成的 future，封装了一个 PrepareEnvironmentResponse，其中包含有关环境准备最终状态的详细信息。
如果出现以下情况，则为封装 InvalidArgumentException 的失败 future：
- [notificationServiceComponentName] 不是调用应用所属的有效组件，或者未在清单中导出。
- 所请求的角色无效。
- 所请求的角色包含 {@code Role.RoleType.DEVICE_POLICY_CONTROLLER}，并且未提供 {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} 或所提供的 {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin} 未扩展 {@code android.app.admin.DeviceAdminReceiver}。
如果调用方无权调用此 API，则返回封装了 SecurityException 的失败 future。
如果 Google Play 服务不是最新版本，则封装 GooglePlayServicesAppNotUpdatedException 的失败 future。
如果 Android 设备政策无法安装或更新，且错误无法恢复，则包含 AndroidDevicePolicyInstallOrUpdateUnrecoverableException 的 future 会失败。
如果 Android 设备政策应用未能安装或更新，且错误可恢复（例如，请求因暂时性网络问题而失败），则包含 AndroidDevicePolicyInstallOrUpdateRecoverableException 的失败 future。因此，可以重试请求。
如果用户拒绝安装 Android Device Policy 应用，则包含 AndroidDevicePolicyInstallConsentDeclinedException 的失败 future。
如果用户关闭安装同意屏幕，则包装 AndroidDevicePolicyInstallConsentDismissedException 的失败 future。
如果因内部错误而导致调用失败，则为封装 InternalException 的失败 future。
如果 Play 商店更新失败，则包含 PlayStoreUpdateUnrecoverableException 的失败 future。

抛出
`com.google.android.managementapi.common.exceptions.ApiLevelException`	如果设备的 SDK API 级别不足以满足某些请求的角色。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 需要 API 级别 23 或更高级别。任何其他角色都需要 API 级别 28 或更高级别。