Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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? )` 确保 Android Device Policy 应用已安装并准备就绪，从而为设备做好准备。
`ListenableFuture<PrepareEnvironmentResponse>`	`prepareEnvironmentAsync( request: PrepareEnvironmentRequest, notificationServiceComponentName: ComponentName? )` 确保 Android Device Policy 应用已安装并准备就绪，从而为设备做好准备。

公共函数

getEnvironment

suspend fun getEnvironment(request: GetEnvironmentRequest): Environment

返回 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

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

返回 Environment。这有助于调用方了解环境是否已准备就绪。

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

ListenableFuture<Environment>

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

如果成功，则返回封装 Environment 的成功 Future。
如果请求的角色无效，则返回封装了 InvalidArgumentException 的失败 Future。
如果调用因内部错误而失败，则返回封装了 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

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

确保 Android Device Policy 应用已安装并准备就绪，从而为设备做好准备。

具体行为取决于上下文：

设备信任流程：如果未安装 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 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

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

确保 Android Device Policy 应用已安装并准备就绪，从而为设备做好准备。

具体行为取决于上下文：

设备信任流程：如果未安装 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 android.app.admin.DeviceAdminReceiver}。如果调用方无权调用此 API，则会返回一个封装了 `SecurityException` 的失败 Future。如果 Google Play 服务不是最新版本，则会返回封装了 `GooglePlayServicesAppNotUpdatedException` 的失败 Future。如果 Android Device Policy 安装或更新失败，并且错误无法恢复，则会返回一个封装了 `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 android.app.admin.DeviceAdminReceiver}。
如果调用方无权调用此 API，则会返回一个封装了 SecurityException 的失败 Future。
如果 Google Play 服务不是最新版本，则会返回封装了 GooglePlayServicesAppNotUpdatedException 的失败 Future。
如果 Android Device Policy 安装或更新失败，并且错误无法恢复，则会返回一个封装了 AndroidDevicePolicyInstallOrUpdateUnrecoverableException 的失败 future。
如果 Android 设备政策应用无法安装或更新，并且错误可恢复（例如，由于暂时性网络问题导致请求失败），则会返回一个封装了 AndroidDevicePolicyInstallOrUpdateRecoverableException 的失败 Future，以便重试请求。
如果用户拒绝安装 Android Device Policy 应用，则会返回一个封装了 AndroidDevicePolicyInstallConsentDeclinedException 的失败 Future。
如果用户关闭安装权限请求页面，则会返回一个封装了 AndroidDevicePolicyInstallConsentDismissedException 的失败 Future。
如果调用因内部错误而失败，则返回封装了 InternalException 的失败 future。
如果 Play 商店更新失败，则会返回一个封装了 PlayStoreUpdateUnrecoverableException 的失败 future。

抛出
`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 或更高级别。