此页面由 Cloud Translation API 翻译。

将现有设备迁移到 AMAPI

已由自定义 DPC 管理的设备可以迁移到 Android Device Policy (ADP)，并利用 Android Management API。

前提条件

设备已由使用自定义 DPC 的 EMM 管理。
您的自定义 DPC 已与 AMAPI SDK 集成。
设备已注册 Google Play EMM API。
设备属于 Google Play 企业版账号集。
设备搭载 Android 9 或更高版本。
对于公司自有设备上的“工作资料”，设备必须搭载 Android 11 或更高版本。

在自定义 DPC 中与 AMAPI SDK 集成

迁移流程要求自定义 DPC 应用集成 AMAPI SDK。如需详细了解此库以及如何将其添加到应用中，请参阅 AMAPI SDK 集成指南。

迁移设备的步骤

设置要在设备迁移到 AMAPI 后由其使用的政策。为了提供最佳用户体验，这应与 DPC 已在设备上强制执行的政策相同。
通过调用 enterprises.migrationTokens.create 为设备创建迁移令牌。
将此迁移令牌的 value 发送到您的自定义 DPC。
使用 Play EMM API 确保设备上已安装 Android Device Policy。
使用 DpcMigrationClientFactory 创建 DpcMigrationClient
在 DpcMigrationClient 上，调用 migrateDeviceManagementToAndroidManagementApi 方法。至此，迁移便完成了。
deviceState 会更改为 ACTIVE，并且您会通过 Pub/Sub 渠道收到 STATUS_REPORT 消息。

迁移完成后，发起调用的应用会失去设备所有者或资料所有者权限，因为这些权限会转移到 Android Device Policy。此过程可用以下序列图表示：

DPC 迁移序列图

注意：设备必须连接到互联网才能开始迁移。此过程旨在能够在迁移过程中应对网络断开连接，以便在从 DPC 将设备所有者或资料所有者权限实际转移到 Android Device Policy 之前完成需要网络连接的关键操作。

迁移令牌

EMM 服务器会请求迁移令牌，以表明其打算迁移由自定义 DPC 管理的特定设备。迁移令牌在迁移成功完成或失效之前有效。

自定义 DPC 集成

首先，您需要创建一个 DpcMigrationRequest，并将令牌以及配置的 Wi-Fi 网络列表（如果有）传递给其构建器：

// Create a DpcMigrationRequest
DpcMigrationRequest request =
        DpcMigrationRequest.builder()
            .setMigrationToken(token)
            .build();

然后，您可以使用 DpcMigrationClient 获取 migrateDeviceManagementToAndroidManagementApi，并启动迁移流程：

// Create a DpcMigrationClient
DpcMigrationClient dpcMigrationClient = DpcMigrationClientFactory.create(context);
try {
  // Use helper function to retrieve Admin component name
  var adminComponentName = getAdminComponent(context);

  ListenableFuture<DpcMigrationAttempt> futureAttempt =
          dpcMigrationClient.migrateDeviceManagementToAndroidManagementApi(
              new ComponentName(context, DpcMigrationNotificationReceiver.class),
              adminComponentName,
              request);
  // handle futureAttempt
} catch (RuntimeException e) {
  // send failure feedback: "Error: " + e
}

跟踪迁移的进度

迁移过程会通过 DpcMigrationAttempt 在设备上跟踪。

您可以直接使用 migrateDeviceManagementToAndroidManagementApi 返回的 ID，也可以使用 getMigrationAttempt 和 listMigrationAttempts 方法获取和列出迁移尝试。

// Passing an empty name, we retrieve the last attempt 
var request = GetDpcMigrationAttemptRequest.builder().build();

var attempt = client.getMigrationAttempt(request);

您可以选择使用 NotificationReceiverService 设置 DpcMigrationListener，以监听 DpcMigrationAttempt 的状态更新。

// DpcMigrationNotificationReceiver for callback handling
public class DpcMigrationNotificationReceiver extends NotificationReceiverService
    implements DpcMigrationListener {

  @Override
  protected DpcMigrationListener getDpcMigrationListener() {
    // getDpcMigrationListener"
    return this;
  }

  @Override
  public void onMigrationStateChanged(DpcMigrationAttempt migrationAttempt) {
    // send success feedback
  }
}

处理 Wi-Fi 网络

如果有 Wi-Fi 网络由自定义 DPC 管理，AMAPI ONC 政策应与这些网络的配置相匹配，以便 AMAPI 能够顺利开始管理这些网络。DPC 迁移与 Wi-Fi 管理的互动因管理模式而异。

完全托管设备和公司自有设备上的“工作资料”

在迁移期间，Android 设备政策会假定在政策中配置的任何 Wi-Fi 网络与设备上已配置的 Wi-Fi 网络具有相同的 SSID 和安全类型，即与匹配的已配置 Wi-Fi 网络完全相同。因此，在迁移后，通过自定义 DPC 配置的 Wi-Fi 网络会保持不变，直到相应网络的 ONC 政策发生变化为止。但是，如果在迁移后卸载自定义 DPC，则系统会自动移除由自定义 DPC 配置的 Wi-Fi 网络。Android Device Policy 会继续强制执行政策，如果政策中配置了其中任何网络，系统会照常添加政策中配置的网络。

个人设备上的工作资料

出于技术原因，Android Device Policy 需要通过自定义 DPC 移除由自定义 DPC 配置的 Wi-Fi 网络，才能开始管理这些 Wi-Fi 网络。AMAPI SDK 会处理此问题，并在将所有权从自定义 DPC 转移到 Android 设备政策之前移除此类 Wi-Fi 网络，但它要求自定义 DPC 在 DpcMigrationRequest 中传递有关这些网络的信息。迁移后，系统会正常添加在政策中配置的网络，因此建议您也应在政策中配置自定义 DPC 添加的网络。

请注意以下几点：

如果活跃网络是由自定义 DPC 配置的 Wi-Fi 网络，则设备可能会在迁移期间短暂离线。
应仅在 DpcMigrationRequest 中传递由自定义 DPC 配置的 Wi-Fi 网络，否则，如果 AMAPI SDK 无法移除网络（例如用户添加的 Wi-Fi 网络），则迁移会失败。
只有当自定义 DPC 是个人所有设备上的资料所有者时，才应在 DpcMigrationRequest 中传递 Wi-Fi 网络，否则迁移会失败。
出于技术原因，Android 12 是一个例外情况，系统会忽略在 DpcMigrationRequest 中传入的网络，并自动移除由自定义 DPC 配置的所有 Wi-Fi 网络。此外，自定义 DPC 必须在 Android 12 上针对个人自有设备上的个人工作资料拥有 ACCESS_WIFI_STATE 权限，否则迁移将会失败。

注意事项

以下是与此功能相关的一些注意事项。

企业专用 ID

对于 Android 12 及更高版本上的工作资料，可通过 DevicePolicyManager.getEnrollmentSpecificId 访问的企业专用 ID 在迁移时不会更改。不过，如果在设备上重新创建由 Android Device Policy 管理的工作资料（例如，在删除之前的工作资料或将设备恢复出厂设置后），此时企业专用 ID 将会更改。

完全托管设备中的工作资料

完全受管理的设备上的工作资料若搭载 Android 9 或 10，则不支持此功能。不得尝试迁移此类设备，并且无论是否引发错误，此类设备都不支持 DPC 迁移。