Enumerar personas

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Recuperar una lista de objetos de persona ordenados por su relevancia para el usuario, que viene determinada por los patrones de comunicación y colaboración y las relaciones comerciales del usuario.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Servicio global Administración pública de EE. UU. Gobierno de EE. UU. L5 (DOD) China operado por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) People.Read People.Read.All
Delegado (cuenta personal de Microsoft) People.Read No disponible.
Aplicación People.Read.All No disponible.

Solicitud HTTP

GET /me/people
GET /users/{id | userPrincipalName}/people

Parámetros de consulta opcionales

Este método admite los siguientes parámetros de consulta OData para ayudar a personalizar la respuesta.

Nombre Valor Descripción
$filter string Limita la respuesta a solo los contactos cuyo registro contiene los criterios especificados.
$orderby cadena De manera predeterminada, los contactos de la respuesta se ordenan por su relevancia para la consulta. Puede cambiar el orden de los contactos en la respuesta con el parámetro $orderby.
$search string Busca contactos por nombre o alias. Admite la coincidencia aproximada. Parámetro solo funciona para buscar los contactos relevantes del usuario que haya iniciado sesión, no para buscar contactos relevantes para otros usuarios. También es compatible con la palabra clave topic para encontrar contactos basados en temas extraídos de conversaciones de correo electrónico con esa persona. Para obtener información y ejemplos, vea la sección Realizar una búsqueda aproximada en Use la API de People para obtener información sobre las personas más relevantes para usted.
$select string Lista separada por comas de las propiedades para incluir en la respuesta. Para obtener un rendimiento óptimo, seleccione solo el subconjunto de propiedades necesarias.
$skip int Omita los primeros n resultados, útil para paginar. No se admite omitir cuando se usa $search.
$top int El número máximo de resultados que se devolverán en una página de resultados. Para obtener más información, consulte el parámetro top.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización.
Aceptar application/json

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si tiene éxito, este método devuelve un 200 OKcódigo de respuesta y una colección de objetos person en el cuerpo de la respuesta.

Ejemplos

Navegación

Las solicitudes de esta sección obtienen las personas más relevantes para el usuario que ha iniciado sesión (/me), en función de la comunicación, la colaboración y las relaciones comerciales.

De forma predeterminada, cada respuesta devuelve 10 registros, pero usted puedecambiar esto utilizando el parámetro $top. Estas solicitudes requieren el People. Permiso de lectura.

Solicitud

A continuación se puede ver un ejemplo de la solicitud predeterminada.

GET https://graph.microsoft.com/beta/me/people

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

Solicitando una página posterior de personas

Si la primera respuesta no contiene la lista completa de personas relevantes, puede realizar una segunda solicitud mediante $top y $skip para solicitar más páginas de información. Si la solicitud previa tiene información adicional, la siguiente solicitud obtiene la siguiente página de personas del servidor.

GET https://graph.microsoft.com/beta/me/people/?$top=10&$skip=10

Ordenar la respuesta

De manera predeterminada, los contactos de la respuesta se ordenan por su relevancia para la consulta. Puede cambiar el orden de los contactos en la respuesta con el parámetro $orderby. Esta consulta selecciona a las personas más relevantes para usted, las ordena por su nombre para mostrar, y luego devuelve las 10 primeras personas de la lista ordenada.

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

Cambiar el número de personas devueltas y los campos devueltos

Puede cambiar el número de contactos devueltos en la respuesta estableciendo el parámetro $top.

En el siguiente ejemplo se solicita a las 1000 personas más relevantes para ./me La solicitud también limita la cantidad de datos enviados desde el servidor, ya que solo solicita el nombre para mostrar de la persona.

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

Seleccionando los campos a devolver

Puede limitar la cantidad de datos devueltos por el servidor usando el parámetro $select para elegir uno o varios campos. El campo @odata.idsiempre se devuelve.

En el ejemplo siguiente se limita la respuesta al valor DisplayName y EmailAddress de las 10 personas más relevantes.

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

Usando un filtro para limitar la respuesta

Puede usar el parámetro $filter para limitar la respuesta a solo los contactos cuyo registro contiene los criterios especificados.

La siguiente consulta limita la respuesta a los usuarios con el origen "Directorio".

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

Seleccionar los campos para devolver en una respuesta filtrada

Puede combinar los parámetros $select y $filter para crear una lista personalizada de contactos relevantes para el usuario y obtener solo los campos que la aplicación necesita.

En el ejemplo siguiente se obtienen el DisplayName y el EmailAddress de las personas cuyo nombre para mostrar es igual al nombre especificado. En este ejemplo, solo se devuelven las personas cuyo nombre para mostrar es igual a "Nestor Kellum".

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

Buscar contactos

Las solicitudes de esta sección también obtienen las personas más relevantes para el usuario con la sesión iniciada (/me). Las solicitudes de búsqueda requieren el People. Permiso de lectura.

Usar la búsqueda para seleccionar personas

Use el parámetro $search para seleccionar contactos que reúnan un conjunto de criterios concreto.

La siguiente consulta de búsqueda devuelve personas relevantes para /me cuyo nombre o apellido comienza con la letra "j".

GET https://graph.microsoft.com/beta/me/people/?$search=j

Usar la búsqueda para especificar un tema relevante

La siguiente solicitud devuelve personas relevantes para /me cuyo nombre contenga "ma" y que tengan una asociación con la "planificación de características".

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

La siguiente solicitud hace una búsqueda de una persona llamada "Hermaini Hall". Dado que hay una persona llamada "Herminia Hull" relevante para el usuario que ha iniciado sesión, se devuelve la información de "Herminia Hull".

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

La siguiente solicitud obtiene las personas más relevantes para otra persona de la organización del usuario. Esta solicitud requiere User.ReadBasic.All for People. Read.All permiso. En este ejemplo, se muestran las personas relevantes de Nestor Kellum.

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/
  • Last updated on