使用配置文件卡 API 在配置文件卡添加或删除自定义属性

Microsoft 365 中的配置文件卡显示有关组织中的用户的信息。 配置文件上显示的信息卡由组织存储和维护，例如职务或 Office 位置。

组织可以使用 profileCardProperty 资源在组织中用户的配置文件卡上显示Microsoft Entra ID的更多属性：

• 使更多属性可见
• 添加自定义属性

更多属性显示在 Microsoft 365 中配置文件卡的“联系人”部分。

还可以从组织的个人资料卡 中删除 自定义属性。

注意

配置文件卡属性对应于 Microsoft Entra ID 中的属性。 将属性作为 profileCardProperty 添加到组织的 profileCardProperties 集合中将配置文件卡配置为显示属性值。 从集合中删除 profileCardProperty不会从 Microsoft Entra ID 中删除属性;它会删除配置，以便配置文件卡不再显示属性值。

注意

本文中所述的配置文件卡属性自定义不适用于 Outlook 和 Office 桌面客户端等 Win32 应用程序。 若要了解如何为组织自定义 Win32 应用程序中的配置文件卡属性，请参阅使用注册表项自定义 Win32 应用中的配置文件卡。

配置文件卡属性 API 在以下国家云部署中可用。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	✅	✅	✅

注意

对使用委派权限的 profileCardProperty 资源执行的操作要求已登录用户具有租户管理员角色。

使其他属性在配置文件上可见卡

可以从Microsoft Entra ID使以下属性在用户的个人资料卡上可见。 这些属性不区分大小写：

• UserPrincipalName
• Fax
• StreetAddress
• PostalCode
• StateOrProvince
• Alias

下表显示了 Microsoft Entra ID 属性与 Microsoft Graph 用户实体的属性的对应方式。

Microsoft Entra ID 属性	用户实体属性
UserPrincipalName	userPrincipalName
Fax	faxNumber
StreetAddress	streetAddress
PostalCode	postalCode
StateOrProvince	state
Alias	mailNickname

可以通过在 Microsoft Graph 中配置人员管理设置并将属性添加为 profileCardProperty 的 directoryPropertyName 属性，将其中任何属性添加到配置文件卡。 使这些属性可见时，必须使用 的属性名称 en-us。 不必添加本地化值。 这些属性将自动显示在用户为 Microsoft 365 指定的语言设置中。

注意： 用户实体属性值包含由组织存储和管理的用户信息。

重要

将属性添加到配置文件卡时，最多需要 24 小时才能显示添加。

使用 Microsoft Graph REST API 配置配置文件卡属性

示例

以下示例在个人资料卡片上显示 Alias 属性。

POST https://graph.microsoft.com/v1.0/admin/people/profileCardProperties
Content-Type: application/json

{
  "directoryPropertyName": "Alias"
}

注意： 该 /organization/{organizationId}/settings 路径在 beta 体验中已弃用。 今后将使用 /admin/people 路径。

如果成功，则响应在响应正文中返回 201 OK 响应代码和 profileCardProperty 对象。 属性的值Alias显示在用户的配置文件卡上。

HTTP/1.1 201 OK
Content-type: application/json

{
  "directoryPropertyName": "Alias",
  "annotations": []
}

将自定义属性添加到配置文件卡

可以通过配置组织设置并在 Microsoft Graph 中将相应值添加为 profileCardProperty，将 15 个Microsoft Entra ID自定义扩展属性中的任何一个添加到用户配置文件卡。 一次可以添加一个 profileCardProperty 资源。

所做的更改最多需要 24 小时才能显示在个人资料卡上。

自定义属性不可搜索，并且不能用于搜索跨Microsoft应用和服务的人员。

下表显示了Microsoft Entra ID自定义扩展属性名称如何与 profileCardProperty 资源的 directoryPropertyName 属性支持的值相对应。 这些Microsoft Entra ID自定义扩展属性名称不区分大小写：

Microsoft Entra ID自定义扩展属性	指定为 directoryPropertyName 的值
extensionAttribute1	CustomAttribute1
extensionAttribute2	CustomAttribute2
extensionAttribute3	CustomAttribute3
extensionAttribute4	CustomAttribute4
extensionAttribute5	CustomAttribute5
extensionAttribute6	CustomAttribute6
extensionAttribute7	CustomAttribute7
extensionAttribute8	CustomAttribute8
extensionAttribute9	CustomAttribute9
extensionAttribute10	CustomAttribute10
extensionAttribute12	CustomAttribute12
extensionAttribute11	CustomAttribute11
extensionAttribute13	CustomAttribute13
extensionAttribute14	CustomAttribute14
extensionAttribute15	CustomAttribute15

重要

为组织中的所有用户添加自定义配置文件卡属性，因此需要采取必要的预防措施，防止敏感数据意外泄露。

示例

以下示例使用显示名称“成本中心”将第一个Microsoft Entra ID自定义扩展属性添加到配置文件卡。 对于将语言设置设置为德语的用户，显示名称为 Kostenstelle。

请求

POST https://graph.microsoft.com/v1.0/admin/people/profileCardProperties
Content-Type: application/json

{
  "directoryPropertyName": "CustomAttribute1",
  "annotations": [
    {
      "displayName": "Cost center",
      "localizations": [
        {
          "languageTag": "de",
          "displayName": "Kostenstelle"
        }
      ]
    }
  ]
}

注意： 该 /organization/{organizationId}/settings 路径在 beta 体验中已弃用。 今后将使用 /admin/people 路径。

如果语言不受支持，则属性名称将显示默认值。

如果成功，则响应在响应正文中返回 201 OK 响应代码和 profileCardProperty 对象。 在此示例中，可以假定配置文件卡在配置文件卡上将其语言设置设置为德语的所有用户显示 Kostenstelle。 对于所有其他用户，成本中心显示在配置文件卡上。

响应

HTTP/1.1 201 OK
Content-type: application/json

{
  "directoryPropertyName": "CustomAttribute1",
  "annotations": [
    {
      "displayName": "Cost center",
      "localizations": [
        {
          "languageTag": "de",
          "displayName": "Kostenstelle"
        }
      ]
    }
  ]
}

从配置文件中删除自定义属性卡

按照Microsoft Entra ID自定义扩展属性和配置文件卡自定义属性 (（如 CustomAttribute1) ）之间的相同映射，如前一部分添加自定义属性中所述，可以使用删除操作删除自定义属性，如以下示例中所示。

示例

以下示例从组织设置中删除自定义属性 CustomAttribute5 。 如果成功，此方法返回 204 No Content 响应代码。

请求

DELETE https://graph.microsoft.com/v1.0/admin/people/profileCardProperties/CustomAttribute5

注意： 该 /organization/{organizationId}/settings 路径在 beta 体验中已弃用。 今后将使用 /admin/people 路径。

响应

HTTP/1.1 204 No Content

使用 PowerShell 配置配置文件卡属性

可以使用 Microsoft Graph PowerShell SDK 在组织中配置配置文件卡属性。

先决条件

• PowerShell 模块 - 安装 模块版本 1.24.0 或更高版本。
• .NET Framework - 安装 .NET Framework 4.7.2 或更高版本。

确认当前设置

若要获取组织的配置文件卡属性配置，请使用以下命令。

   Get-MgAdminPeopleProfileCardProperty

若要获取组织中的特定配置文件卡属性配置，请使用以下命令。

   Get-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId $profileCardPropertyId

注意

get 命令需要 PeopleSettings.Read.All 权限。 若要创建带特定所需范围的 Microsoft Graph 会话，请使用以下命令并同意请求的权限。

   Connect-MgGraph -Scopes "PeopleSettings.Read.All"

在组织中添加配置文件卡属性

可以使用 Microsoft Graph PowerShell 模块使Microsoft Entra ID属性和 15 个可自定义Microsoft Entra ID扩展属性在组织中可用。

注意

新命令需要 PeopleSettings.ReadWrite.All 权限。 若要创建带特定所需范围的 Microsoft Graph 会话，请使用以下命令并同意请求的权限。

   Connect-MgGraph -Scopes "PeopleSettings.ReadWrite.All","PeopleSettings.Read.All"

使用以下命令。

$params = @{
	directoryPropertyName = "CustomAttribute1"
	annotations = @(
		@{
			displayName = "Cost Center"
			localizations = @(
				@{
					languageTag = "ru"
					displayName = "центр затрат"
				}
			)
		}
	)
}

New-MgAdminPeopleProfileCardProperty -BodyParameter $params

更新组织中的配置文件卡属性

可以使用 Microsoft Graph PowerShell 模块更新配置文件卡组织中可用的属性。

注意

update 命令需要 PeopleSettings.ReadWrite.All 权限。 若要创建带特定所需范围的 Microsoft Graph 会话，请使用以下命令并同意请求的权限。

   Connect-MgGraph -Scopes "PeopleSettings.ReadWrite.All","PeopleSettings.Read.All"

使用以下命令，其中将 替换为 $profileCardPropertyId 要更新的属性的 ID。

$params = @{
	annotations = @(
		@{
      displayName = "Cost Center"
			localizations = @(
				@{
					languageTag = "no"
					displayName = "Kostnads Senter"
				}
			)
		}
	)
}

Update-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId $profileCardPropertyId -BodyParameter $params

删除组织中的配置文件卡属性

可以使用 Microsoft Graph PowerShell 模块从组织中删除配置文件卡属性。

注意

remove 命令需要 PeopleSettings.ReadWrite.All 权限。 若要创建带特定所需范围的 Microsoft Graph 会话，请使用以下命令并同意请求的权限。

   Connect-MgGraph -Scopes "PeopleSettings.ReadWrite.All","PeopleSettings.Read.All"

使用以下命令，其中将 替换为 $profileCardPropertyId 要删除的属性的 ID。

 Remove-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId $profileCardPropertyId

相关内容

• onPremisesExtensionAttributes 资源类型
• 用户资源类型
• Graph 浏览器
• Get profileCardProperty
• 针对 GDPR 和 CCPA 的 Azure 数据主体请求
• 配置文件卡提供哪些语言？