此页面由 Cloud Translation API 翻译。

工作资料联系人

本开发者指南介绍了如何改进您的应用以使用联系人功能来自工作资料的数据。如果您未使用过 Android 的联系人 API 之前，请先阅读联系人提供程序，熟悉这些 API。

概览

具有工作资料的设备将联系人存储在单独的本地工作资料和个人资料的目录默认情况下，当应用在但不会显示工作联系人。不过，应用可以访问工作资料中的联系信息。例如，这是 Google 的 Android“通讯录”应用工作目录联系人。

用户通常希望将个人设备和应用用于工作。使用工作资料联系人，那么您的应用就可以成为用户日常工作的一部分。

用户体验

考虑您的应用可能会如何呈现工作资料中的联系信息。最佳方法取决于应用的性质以及用户但请考虑以下事项：

您的应用是否应默认包含工作资料联系人，还是用户应选择启用？
混合或拆分工作资料联系人和个人资料联系人对用户流？
意外点按工作资料联系人会产生什么影响？
如果工作资料联系人未开启，应用界面会发生什么情况是否有空？

您的应用应明确指明工作资料联系人。或许您可以标记使用熟悉的工作图标（例如公文包）与联系人联系。

以列表形式显示搜索结果的屏幕截图 — **图 1.** Google 通讯录应用如何分隔工作资料联系人

例如，Google 通讯录应用（如图 1 所示）会执行以下操作同时列出工作资料和个人资料联系人：

插入副标题，以分隔列表中的工作部分和个人部分。
标记工作联系人并带有公文包图标。
点按后打开工作资料中的工作联系人。

如果使用设备的用户关闭了工作资料，您的应用将无法通过工作资料或单位的遥控器查询联系信息联系人目录根据您使用工作资料联系人的方式，您可以：将这些联系人静音，或者您可能需要停用界面控件。

权限

如果您的应用已在使用用户的联系人，您将获得他们的 READ_CONTACTS（或者可能是 WRITE_CONTACTS) 权限，您在应用清单文件中因为个人资料和工作个人资料，那么无需进一步的权限即可访问工作中的联系人数据个人资料。

IT 管理员可以屏蔽与个人资料共享联系信息的工作资料。如果 IT 人员管理员禁止访问，您的联系人搜索将返回空结果。您的如果用户关闭了工作，应用无需处理特定错误个人资料。目录内容提供程序会继续返回用户的工作联系人目录（请参阅目录部分）。如需测试这些权限，请参阅开发和测试部分。

联系人搜索

您可以使用获取个人资料中的联系人。企业 URI Android 7.0（API 级别 24）或更高版本中支持联系人。您需要确保对 URI 进行以下调整：

将 content provider URI 设置为 Contacts.ENTERPRISE_CONTENT_FILTER_URI、并以查询字符串的形式提供联系人的姓名
设置要搜索的联系人目录。例如： ENTERPRISE_DEFAULT 查找工作中的联系人个人资料的本地商店

更改 URI 可以支持任何 content provider 机制，例如 CursorLoader - 非常适合将联系人数据加载到界面中，因为数据访问发生在工作线程上为简单起见，向导通话 ContentResolver.query()。您可以通过以下方式查找工作资料本地联系人目录中的联系人：

Kotlin

// First confirm the device user has given permission for the personal profile.
// There isn't a separate work permission, but an IT admin can block access.
val readContactsPermission =
  ContextCompat.checkSelfPermission(getBaseContext(), Manifest.permission.READ_CONTACTS)
if (readContactsPermission != PackageManager.PERMISSION_GRANTED) {
  return
}

// Fetch Jackie, James, & Jason (and anyone else whose names begin with "ja").
val nameQuery = Uri.encode("ja")

// Build the URI to look up work profile contacts whose name matches. Query
// the default work profile directory which is the locally-stored contacts.
val contentFilterUri =
  ContactsContract.Contacts.ENTERPRISE_CONTENT_FILTER_URI
    .buildUpon()
    .appendPath(nameQuery)
    .appendQueryParameter(
      ContactsContract.DIRECTORY_PARAM_KEY,
      ContactsContract.Directory.ENTERPRISE_DEFAULT.toString()
    )
    .build()

// Query the content provider using the generated URI.
var cursor =
  getContentResolver()
    .query(
      contentFilterUri,
      arrayOf(
        ContactsContract.Contacts._ID,
        ContactsContract.Contacts.LOOKUP_KEY,
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY
      ),
      null,
      null,
      null
    )

// Print any results found using the work profile contacts' display name.
cursor?.use {
  while (it.moveToNext()) {
    Log.i(TAG, "Work profile contact: ${it.getString(2)}")
  }
}

Java

// First confirm the device user has given permission for the personal profile.
// There isn't a separate work permission, but an IT admin can block access.
int readContactsPermission = ContextCompat.checkSelfPermission(
    getBaseContext(), Manifest.permission.READ_CONTACTS);
if (readContactsPermission != PackageManager.PERMISSION_GRANTED) {
  return;
}

// Fetch Jackie, James, & Jason (and anyone else whose names begin with "ja").
String nameQuery = Uri.encode("ja");

// Build the URI to look up work profile contacts whose name matches. Query
// the default work profile directory which is the locally stored contacts.
Uri contentFilterUri = ContactsContract.Contacts.ENTERPRISE_CONTENT_FILTER_URI
    .buildUpon()
    .appendPath(nameQuery)
    .appendQueryParameter(ContactsContract.DIRECTORY_PARAM_KEY,
        String.valueOf(ContactsContract.Directory.ENTERPRISE_DEFAULT))
    .build();

// Query the content provider using the generated URI.
Cursor cursor = getContentResolver().query(
    contentFilterUri,
    new String[] {
        ContactsContract.Contacts._ID,
        ContactsContract.Contacts.LOOKUP_KEY,
        ContactsContract.Contacts.DISPLAY_NAME_PRIMARY
    },
    null,
    null,
    null);
if (cursor == null) {
  return;
}

// Print any results found using the work profile contacts' display name.
try {
  while (cursor.moveToNext()) {
    Log.i(TAG, "Work profile contact: " + cursor.getString(2));
  }
} finally {
  cursor.close();
}

许多组织使用远程目录，例如 Microsoft Exchange 或 LDAP，包含整个组织的联系信息。您的应用可以助您一臂之力用户可与单位内的同事交流和分享目录。请注意，这些目录通常包含数千个联系人，并且您的应用还需要网络连接才能搜索它们。您可以使用 Directory content provider，用于获取用户账号，并详细了解各个目录。

查询 Directory.ENTERPRISE_CONTENT_URI content provider 从个人资料和工作同时又返回了一份个人资料。以下国家/地区支持搜索工作资料目录： Android 7.0（API 级别 24）或更高版本。您的应用仍需要用户 READ_CONTACTS 拥有与其联系人协作的权限目录。

由于 Android 会将联系信息存储在不同类型的本地远程目录下，Directory 类提供了一些方法，您可以调用关于目录：

isEnterpriseDirectoryId(): 调用此方法可确认目录是否来自工作资料账号。请注意，ENTERPRISE_CONTENT_URI 内容提供方会返回联系人将个人资料和工作资料的目录放在一起。
isRemoteDirectoryId(): 调用此方法可确定目录是否为远程目录。远程目录可能是企业联系人存储区，也可能是用户的社交网络。

以下示例展示了如何使用这些方法过滤工作资料目录：

Kotlin

// First, confirm the device user has given READ_CONTACTS permission.
// This permission is still needed for directory listings ...

// Query the content provider to get directories for BOTH the personal and
// work profiles.
val cursor =
  getContentResolver()
    .query(
      ContactsContract.Directory.ENTERPRISE_CONTENT_URI,
      arrayOf(ContactsContract.Directory._ID, ContactsContract.Directory.PACKAGE_NAME),
      null,
      null,
      null
    )

// Print the package name of the work profile's local or remote contact directories.
cursor?.use {
  while (it.moveToNext()) {
    val directoryId = it.getLong(0)
    if (ContactsContract.Directory.isEnterpriseDirectoryId(directoryId)) {
      Log.i(TAG, "Directory: ${it.getString(1)}")
    }
  }
}

Java

// First, confirm the device user has given READ_CONTACTS permission.
// This permission is still needed for directory listings ...

// Query the content provider to get directories for BOTH the personal and
// work profiles.
Cursor cursor = getContentResolver().query(
    ContactsContract.Directory.ENTERPRISE_CONTENT_URI,
    new String[]{
        ContactsContract.Directory._ID,
        ContactsContract.Directory.PACKAGE_NAME
    },
    null,
    null,
    null);
if (cursor == null) {
  return;
}

// Print the package name of the work profile's local or remote contact directories.
try {
  while (cursor.moveToNext()) {
    long directoryId = cursor.getLong(0);

    if (ContactsContract.Directory.isEnterpriseDirectoryId(directoryId)) {
      Log.i(TAG, "Directory: " + cursor.getString(1));
    }
  }
} finally {
  cursor.close();
}

该示例会提取该目录的 ID 和软件包名称。显示用户可以帮助用户选择联系人目录来源的界面，您可能需要获取有关该目录的更多信息。要查看其他元数据字段请参阅 Directory 类参考文档。

手机查询

应用可以查询 PhoneLookup.CONTENT_FILTER_URI，高效查询某个电话号码的联系人数据您可以从以下位置获得查询结果：个人资料联系人提供程序和工作资料联系人提供程序（如果您将此 URI 替换为 PhoneLookup.ENTERPRISE_CONTENT_FILTER_URI。此工作资料内容 URI 可在 Android 5.0（API 级别 21）或。

以下示例展示的应用查询工作资料内容 URI，为来电配置界面：

Kotlin

fun onCreateIncomingConnection(
  connectionManagerPhoneAccount: PhoneAccountHandle,
  request: ConnectionRequest
): Connection {
  var request = request
  // Get the telephone number from the incoming request URI.
  val phoneNumber = this.extractTelephoneNumber(request.address)

  var displayName = "Unknown caller"
  var isCallerInWorkProfile = false

  // Look up contact details for the caller in the personal and work profiles.
  val lookupUri =
    Uri.withAppendedPath(
      ContactsContract.PhoneLookup.ENTERPRISE_CONTENT_FILTER_URI,
      Uri.encode(phoneNumber)
    )
  val cursor =
    getContentResolver()
      .query(
        lookupUri,
        arrayOf(
          ContactsContract.PhoneLookup._ID,
          ContactsContract.PhoneLookup.DISPLAY_NAME,
          ContactsContract.PhoneLookup.CUSTOM_RINGTONE
        ),
        null,
        null,
        null
      )

  // Use the first contact found and check if they're from the work profile.
  cursor?.use {
    if (it.moveToFirst() == true) {
      displayName = it.getString(1)
      isCallerInWorkProfile = ContactsContract.Contacts.isEnterpriseContactId(it.getLong(0))
    }
  }

  // Return a configured connection object for the incoming call.
  val connection = MyAudioConnection()
  connection.setCallerDisplayName(displayName, TelecomManager.PRESENTATION_ALLOWED)

  // Our app's activity uses this value to decide whether to show a work badge.
  connection.setIsCallerInWorkProfile(isCallerInWorkProfile)

  // Configure the connection further ...
  return connection
}

Java

public Connection onCreateIncomingConnection (
    PhoneAccountHandle connectionManagerPhoneAccount, ConnectionRequest request) {
  // Get the telephone number from the incoming request URI.
  String phoneNumber = this.extractTelephoneNumber(request.getAddress());

  String displayName = "Unknown caller";
  boolean isCallerInWorkProfile = false;

  // Look up contact details for the caller in the personal and work profiles.
  Uri lookupUri = Uri.withAppendedPath(
      ContactsContract.PhoneLookup.ENTERPRISE_CONTENT_FILTER_URI,
      Uri.encode(phoneNumber));
  Cursor cursor = getContentResolver().query(
      lookupUri,
      new String[]{
          ContactsContract.PhoneLookup._ID,
          ContactsContract.PhoneLookup.DISPLAY_NAME,
          ContactsContract.PhoneLookup.CUSTOM_RINGTONE
      },
      null,
      null,
      null);

  // Use the first contact found and check if they're from the work profile.
  if (cursor != null) {
    try {
      if (cursor.moveToFirst() == true) {
        displayName = cursor.getString(1);
        isCallerInWorkProfile =
            ContactsContract.Contacts.isEnterpriseContactId(cursor.getLong(0));
      }
    } finally {
      cursor.close();
    }
  }

  // Return a configured connection object for the incoming call.
  MyConnection connection = new MyConnection();
  connection.setCallerDisplayName(displayName, TelecomManager.PRESENTATION_ALLOWED);

  // Our app's activity uses this value to decide whether to show a work badge.
  connection.setIsCallerInWorkProfile(isCallerInWorkProfile);

  // Configure the connection further ...
  return connection;
}

电子邮件查询次数

您的应用可以通过查询 Email.ENTERPRISE_CONTENT_LOOKUP_URI。查询此网址会先搜索个人联系人，以获取完全匹配的内容。如果该提供商与任何个人联系人均不匹配，那么提供商接着搜索工作联系人。此 URI 可在 Android 6.0（API 级别 23）中使用或更高版本。

下面介绍了如何查找电子邮件地址的联系信息：

Kotlin

// Build the URI to look up contacts from the personal and work profiles that
// are an exact (case-insensitive) match for the email address.
val emailAddress = "somebody@example.com"
val contentFilterUri =
  Uri.withAppendedPath(
    ContactsContract.CommonDataKinds.Email.ENTERPRISE_CONTENT_LOOKUP_URI,
    Uri.encode(emailAddress)
  )

// Query the content provider to first try to match personal contacts and,
// if none are found, then try to match the work contacts.
val cursor =
  contentResolver.query(
    contentFilterUri,
    arrayOf(
      ContactsContract.CommonDataKinds.Email.CONTACT_ID,
      ContactsContract.CommonDataKinds.Email.ADDRESS,
      ContactsContract.Contacts.DISPLAY_NAME
    ),
    null,
    null,
    null
  )
    ?: return

// Print the name of the matching contact. If we want to work-badge contacts,
// we can call ContactsContract.Contacts.isEnterpriseContactId() with the ID.
cursor.use {
  while (it.moveToNext()) {
    Log.i(TAG, "Matching contact: ${it.getString(2)}")
  }
}

Java

// Build the URI to look up contacts from the personal and work profiles that
// are an exact (case-insensitive) match for the email address.
String emailAddress = "somebody@example.com";
Uri contentFilterUri = Uri.withAppendedPath(
    ContactsContract.CommonDataKinds.Email.ENTERPRISE_CONTENT_LOOKUP_URI,
    Uri.encode(emailAddress));

// Query the content provider to first try to match personal contacts and,
// if none are found, then try to match the work contacts.
Cursor cursor = getContentResolver().query(
    contentFilterUri,
    new String[]{
        ContactsContract.CommonDataKinds.Email.CONTACT_ID,
        ContactsContract.CommonDataKinds.Email.ADDRESS,
        ContactsContract.Contacts.DISPLAY_NAME
    },
    null,
    null,
    null);
if (cursor == null) {
  return;
}

// Print the name of the matching contact. If we want to work-badge contacts,
// we can call ContactsContract.Contacts.isEnterpriseContactId() with the ID.
try {
  while (cursor.moveToNext()) {
    Log.i(TAG, "Matching contact: " + cursor.getString(2));
  }
} finally {
  cursor.close();
}

显示工作联系信息

在个人资料中运行的应用可以在工作资料中显示联系人卡片。致电 ContactsContract.QuickContact.showQuickContact() 英寸使用 Android 5.0 或更高版本，以在工作资料中启动“通讯录”应用并显示联系人名片

要为工作资料生成正确的 URI，您需要调用 ContactsContract.Contacts.getLookupUri()，并将联系人 ID 和查找键。以下示例展示了如何获取 URI 然后显示该卡片：

Kotlin

// Query the content provider using the ENTERPRISE_CONTENT_FILTER_URI address.
// We use the _ID and LOOKUP_KEY columns to generate a work-profile URI.
val cursor =
  getContentResolver()
    .query(
      contentFilterUri,
      arrayOf(ContactsContract.Contacts._ID, ContactsContract.Contacts.LOOKUP_KEY),
      null,
      null
    )

// Show the contact details card in the work profile's Contacts app. The URI
// must be created with getLookupUri().
cursor?.use {
  if (it.moveToFirst() == true) {
    val uri = ContactsContract.Contacts.getLookupUri(it.getLong(0), it.getString(1))
    ContactsContract.QuickContact.showQuickContact(
      activity,
      Rect(20, 20, 100, 100),
      uri,
      ContactsContract.QuickContact.MODE_LARGE,
      null
    )
  }
}

Java

// Query the content provider using the ENTERPRISE_CONTENT_FILTER_URI address.
// We use the _ID and LOOKUP_KEY columns to generate a work-profile URI.
Cursor cursor = getContentResolver().query(
    contentFilterUri,
    new String[] {
        ContactsContract.Contacts._ID,
        ContactsContract.Contacts.LOOKUP_KEY,
    },
    null,
    null,
    null);
if (cursor == null) {
  return;
}

// Show the contact details card in the work profile's Contacts app. The URI
// must be created with getLookupUri().
try {
  if (cursor.moveToFirst() == true) {
    Uri uri = ContactsContract.Contacts.getLookupUri(
        cursor.getLong(0), cursor.getString(1));
    ContactsContract.QuickContact.showQuickContact(
        getActivity(),
        new Rect(20, 20, 100, 100),
        uri,
        ContactsContract.QuickContact.MODE_LARGE,
        null);
  }
} finally {
  cursor.close();
}

可用性

下表总结了哪些 Android 版本支持工作资料个人资料中的联系人数据：

Android 版本	支持
5.0（API 级别 21）	使用 `PhoneLookup.ENTERPRISE_CONTENT_FILTER_URI` 查找电话号码的工作联系人姓名。
6.0（API 级别 23）	使用 `Email.ENTERPRISE_CONTENT_LOOKUP_URI` 查找电子邮件地址的工作联系人姓名。
7.0（API 级别 24）	使用 `Contacts.ENTERPRISE_CONTENT_FILTER_URI` 从工作目录中查询工作联系人姓名。使用 `Directory.ENTERPRISE_CONTENT_URI` 列出工作资料和个人资料中的所有目录。

开发和测试

要创建工作资料，请按以下步骤操作：

安装我们的 Test DPC 应用。
打开设置 Test DPC 应用（不是 Test DPC 应用图标）。
按照屏幕上的说明设置受管理资料。
在工作资料中，打开通讯录应用并添加一些联系人示例。

如需模拟 IT 管理员禁止访问工作资料联系人的情况，请按以下步骤操作：

在工作资料中，打开 Test DPC 应用。
搜索停用跨资料联系人搜索设置或 停用跨资料来电显示设置。
将设置切换为开启。

如需详细了解如何使用工作资料测试应用，请参阅测试应用与工作资料的兼容性。

其他资源

要详细了解联系人或工作资料，请参阅以下资源：

工作资料包含更多有关工作的最佳实践个人资料。
检索联系人列表介绍了在应用中列出联系人所需的步骤。
联系人提供程序解释了联系人数据库的结构。