本頁面由 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` 包裝結果。以下列舉幾個合適的問題：如果成功，則為包裝 `Environment` 的成功 Future。如果要求的角色無效，則為失敗的 Future，並包裝 `InvalidArgumentException`。如果呼叫因內部錯誤而失敗，則為包裝 `InternalException` 的失敗 Future。

ListenableFuture<Environment>

以 ListenableFuture 包裝結果。以下列舉幾個合適的問題：

如果成功，則為包裝 Environment 的成功 Future。
如果要求的角色無效，則為失敗的 Future，並包裝 InvalidArgumentException。
如果呼叫因內部錯誤而失敗，則為包裝 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 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>

準備裝置環境。

參數

參數
`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()
  }
}

傳回

傳回
`ListenableFuture<PrepareEnvironmentResponse>`	以 `ListenableFuture` 包裝結果。這可以是成功包裝的 Future，其中包含環境準備的最終狀態詳細資料。`PrepareEnvironmentResponse` 如果發生下列情況，失敗的 Future 會包裝 `InvalidArgumentException`： [notificationServiceComponentName] 不是屬於呼叫應用程式的有效元件，或未在資訊清單中匯出。要求的角色無效。要求的角色包含 {@code Role.RoleType.DEVICE_POLICY_CONTROLLER}，且未提供 {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin}，或未擴充 {@code android.app.admin.DeviceAdminReceiver}。如果呼叫者未獲授權呼叫此 API，則會包裝失敗的 Future `SecurityException`。如果 Google Play 服務不是最新版本，則為失敗的 Future，並包裝 `GooglePlayServicesAppNotUpdatedException`。如果 Android 裝置政策無法安裝或更新，且錯誤無法復原，則會失敗並包裝 `AndroidDevicePolicyInstallOrUpdateUnrecoverableException`。如果 Android 裝置政策應用程式無法安裝或更新，且錯誤可復原 (例如要求因暫時性網路問題而失敗)，則失敗的 Future 會包裝 `AndroidDevicePolicyInstallOrUpdateRecoverableException`，因此可以重試要求。如果使用者拒絕安裝 Android Device Policy 應用程式，則會失敗，並包裝 `AndroidDevicePolicyInstallConsentDeclinedException`。如果使用者關閉安裝同意畫面，則失敗的 Future 會包裝 `AndroidDevicePolicyInstallConsentDismissedException`。如果呼叫因內部錯誤而失敗，則為包裝 `InternalException` 的失敗 Future。如果 Play 商店更新失敗，則為失敗的 Future，並包裝 `PlayStoreUpdateUnrecoverableException`。

ListenableFuture<PrepareEnvironmentResponse>

以 ListenableFuture 包裝結果。這可以是

成功包裝的 Future，其中包含環境準備的最終狀態詳細資料。PrepareEnvironmentResponse
如果發生下列情況，失敗的 Future 會包裝 InvalidArgumentException：
- [notificationServiceComponentName] 不是屬於呼叫應用程式的有效元件，或未在資訊清單中匯出。
- 要求的角色無效。
- 要求的角色包含 {@code Role.RoleType.DEVICE_POLICY_CONTROLLER}，且未提供 {@code com.google.android.managementapi.environment.model.PrepareEnvironmentRequest.admin}，或未擴充 {@code android.app.admin.DeviceAdminReceiver}。
如果呼叫者未獲授權呼叫此 API，則會包裝失敗的 Future SecurityException。
如果 Google Play 服務不是最新版本，則為失敗的 Future，並包裝 GooglePlayServicesAppNotUpdatedException。
如果 Android 裝置政策無法安裝或更新，且錯誤無法復原，則會失敗並包裝 AndroidDevicePolicyInstallOrUpdateUnrecoverableException。
如果 Android 裝置政策應用程式無法安裝或更新，且錯誤可復原 (例如要求因暫時性網路問題而失敗)，則失敗的 Future 會包裝 AndroidDevicePolicyInstallOrUpdateRecoverableException，因此可以重試要求。
如果使用者拒絕安裝 Android Device Policy 應用程式，則會失敗，並包裝 AndroidDevicePolicyInstallConsentDeclinedException。
如果使用者關閉安裝同意畫面，則失敗的 Future 會包裝 AndroidDevicePolicyInstallConsentDismissedException。
如果呼叫因內部錯誤而失敗，則為包裝 InternalException 的失敗 Future。
如果 Play 商店更新失敗，則為失敗的 Future，並包裝 PlayStoreUpdateUnrecoverableException。

擲回
`com.google.android.managementapi.common.exceptions.ApiLevelException`	如果裝置的 SDK API 級別不足以支援特定要求角色。{@code Role.RoleType.DEVICE_POLICY_CONTROLLER} 需要 API 級別 23 以上版本。其他角色則須為 API 級別 28 以上。