Adición o eliminación de atributos personalizados en una tarjeta de perfil mediante la API de tarjeta de perfil

  • Artículo

La tarjeta de perfil de Microsoft 365 muestra información sobre un usuario de una organización. La organización almacena y mantiene la información que se muestra en la tarjeta de perfil, por ejemplo, el puesto de trabajo o la ubicación de Office.

Las organizaciones pueden usar el recurso profileCardProperty para mostrar más propiedades de Microsoft Entra ID en la tarjeta de perfil de un usuario de una organización mediante:

  • Hacer más atributos visibles
  • Agregar atributos personalizados.

Se muestran más propiedades en la sección Contacto de la tarjeta de perfil de Microsoft 365.

También puede quitar atributos personalizados de las tarjetas de perfil de la organización.

Nota:

Las propiedades de la tarjeta de perfil corresponden a los atributos de Microsoft Entra ID. Al agregar un atributo como profileCardProperty a la colección profileCardProperties de una organización, se configuran tarjetas de perfil para mostrar el valor del atributo. La eliminación de profileCardProperty de la colección no elimina el atributo de Microsoft Entra ID; elimina la configuración para que las tarjetas de perfil ya no muestren el valor del atributo.

Las API de propiedades de tarjeta de perfil están disponibles en las siguientes implementaciones nacionales en la nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Nota:

Las operaciones en el recurso profileCardProperty que usan permisos delegados requieren que el usuario que ha iniciado sesión tenga un rol administrador de inquilinos o administrador global.

Hacer que otros atributos sean visibles en la tarjeta de perfil

Puede hacer que los siguientes atributos de Microsoft Entra ID sean visibles en las tarjetas de perfil de los usuarios. Estos atributos no distinguen mayúsculas de minúsculas:

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

En la tabla siguiente se muestra cómo se corresponden los atributos de Microsoft Entra ID con las propiedades de la entidad de usuario de Microsoft Graph.

atributo Microsoft Entra ID Propiedad de entidad del usuario
UserPrincipalName userPrincipalName
Fax faxNumber
StreetAddress streetAddress
PostalCode postalCode
StateOrProvince state
Alias mailNickname

Puede agregar cualquiera de estos atributos a la tarjeta de perfil configurando la configuración de administrador de personas y agregando el atributo como la propiedad directoryPropertyName de un profileCardProperty en Microsoft Graph. Al hacer visibles estos atributos, debe usar los nombres de propiedad para en-us. No es necesario que agregue valores traducidos. Estas propiedades se muestran automáticamente en la configuración de idioma que el usuario especifica para Microsoft 365.

Nota: Los valores de propiedad de entidad de usuario contienen información de usuario almacenada y administrada por la organización.

Importante

Al agregar un atributo a una tarjeta de perfil, la adición tarda hasta 24 horas en mostrarse.

Configuración de las propiedades de la tarjeta de perfil mediante la API REST de Microsoft Graph

Ejemplo

El siguiente ejemplo muestra el Alias atributo en la tarjeta de perfil.

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

{
  "directoryPropertyName": "Alias"
}

Nota: La /organization/{organizationId}/settings ruta de acceso está en desuso en la experiencia beta. En el futuro, utilice la ruta de acceso /admin/people.

Si se ejecuta correctamente, esta respuesta devuelve un código de respuesta 201 OK y el objeto profileCardProperty en el cuerpo de la respuesta. El valor del atributo se muestra en la Alias tarjeta de perfil de un usuario.

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

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

Adición de un atributo personalizado a la tarjeta de perfil

Puede agregar cualquiera de los 15 atributos de extensión Microsoft Entra ID personalizados a las tarjetas de perfil de los usuarios configurando la configuración de la organización y agregando el valor correspondiente como profileCardProperty en Microsoft Graph. Puede agregar un recurso profileCardProperty cada vez.

Los cambios tardan hasta 24 horas en mostrarse en las tarjetas de perfil.

Las propiedades personalizadas no se pueden buscar y no se pueden usar para buscar personas en aplicaciones y servicios de Microsoft.

En la tabla siguiente se muestra cómo los Microsoft Entra ID nombres de atributos de extensión personalizados corresponden a los valores admitidos para la propiedad directoryPropertyName del recurso profileCardProperty. Estos Microsoft Entra ID nombres de atributos de extensión personalizados no distinguen mayúsculas de minúsculas:

Microsoft Entra ID atributo de extensión personalizada Valor que se especifica como 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

Importante

Se agregan atributos de tarjeta de perfil personalizados para todos los usuarios de la organización, lo que requiere las precauciones necesarias para evitar la exposición accidental de datos confidenciales.

Ejemplo

En el ejemplo siguiente se agrega el primer atributo de extensión personalizada Microsoft Entra ID a la tarjeta de perfil, con el nombre para mostrar Centro de costos. Para los usuarios que establecen su configuración de idioma en alemán, el nombre para mostrar es Kostenstelle.

Solicitud

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"
        }
      ]
    }
  ]
}

Nota: La /organization/{organizationId}/settings ruta de acceso está en desuso en la experiencia beta. En el futuro, utilice la ruta de acceso /admin/people.

Si no se admite un idioma, el nombre de la propiedad se muestra con el valor predeterminado.

Si se ejecuta correctamente, esta respuesta devuelve un código de respuesta 201 OK y el objeto profileCardProperty en el cuerpo de la respuesta. En este ejemplo, puede suponer que la tarjeta de perfil muestra Kostenstelle para todos los usuarios que establecen su configuración de idioma en alemán en la tarjeta de perfil. Para todos los demás usuarios, el Centro de costos se muestra en la tarjeta de perfil.

Respuesta

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

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

Quitar un atributo personalizado de la tarjeta de perfil

Después de la misma asignación entre Microsoft Entra ID atributos de extensión personalizados y atributos personalizados de tarjeta de perfil (como CustomAttribute1) como se describe en la sección anterior Adición de un atributo personalizado, puede quitar un atributo personalizado mediante la operación de eliminación, como se muestra en el ejemplo siguiente.

Ejemplo

En el ejemplo siguiente se quita el atributo CustomAttribute5 personalizado de la configuración de la organización. Si se ejecuta correctamente, este método devuelve un código de respuesta 204 No Content.

Solicitud

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

Nota: La /organization/{organizationId}/settings ruta de acceso está en desuso en la experiencia beta. En el futuro, utilice la ruta de acceso /admin/people.

Respuesta

HTTP/1.1 204 No Content

Configuración de las propiedades de la tarjeta de perfil mediante PowerShell

Puede usar el SDK de PowerShell de Microsoft Graph para configurar las propiedades de la tarjeta de perfil en su organización.

Requisitos previos

Confirmación de la configuración actual

Para obtener la configuración de propiedades de la tarjeta de perfil para una organización, use el siguiente comando.

   Get-MgAdminPeopleProfileCardProperty

Para obtener una configuración de propiedad de tarjeta de perfil específica en una organización, use el siguiente comando.

   Get-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId $profileCardPropertyId

Nota:

Los comandos get requieren el PeopleSettings.Read.All permiso . Para crear una sesión de Microsoft Graph con un alcance requerido específico, use el siguiente comando y acepte los permisos solicitados.

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

Adición de propiedades de tarjeta de perfil en la organización

Puede usar el módulo de PowerShell de Microsoft Graph para que ambos atributos de Microsoft Entra ID y los 15 atributos de extensión de Microsoft Entra ID personalizables estén disponibles en su organización.

Nota:

El nuevo comando requiere el PeopleSettings.ReadWrite.All permiso . Para crear una sesión de Microsoft Graph con un alcance requerido específico, use el siguiente comando y acepte los permisos solicitados.

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

Use el siguiente comando.

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

New-MgAdminPeopleProfileCardProperty -BodyParameter $params

Actualización de las propiedades de la tarjeta de perfil en la organización

Puede usar el módulo de PowerShell de Microsoft Graph para actualizar las propiedades de la tarjeta de perfil disponibles en su organización.

Nota:

El comando update requiere el PeopleSettings.ReadWrite.All permiso . Para crear una sesión de Microsoft Graph con un alcance requerido específico, use el siguiente comando y acepte los permisos solicitados.

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

Use el siguiente comando, donde reemplazará $profileCardPropertyId por el identificador de la propiedad que se va a actualizar.

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

Update-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId $profileCardPropertyId -BodyParameter $params

Eliminación de las propiedades de la tarjeta de perfil en la organización

Puede usar el módulo de PowerShell de Microsoft Graph para quitar las propiedades de la tarjeta de perfil de su organización.

Nota:

El comando remove requiere el PeopleSettings.ReadWrite.All permiso . Para crear una sesión de Microsoft Graph con un alcance requerido específico, use el siguiente comando y acepte los permisos solicitados.

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

Use el siguiente comando, donde reemplazará $profileCardPropertyId por el identificador de la propiedad que se va a quitar.

 Remove-MgAdminPeopleProfileCardProperty -ProfileCardPropertyId $profileCardPropertyId

Contenido relacionado