Enumerar personas

Espacio de nombres: microsoft.graph

Importante

Las API de la /beta versión 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 versiones .

Recupera 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 del usuario, y las relaciones empresariales.

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) People.Read, People.Read.All
Delegado (cuenta personal de Microsoft) People.Read
Aplicación People.Read.All

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 forma predeterminada, las personas de la respuesta se ordenan por su relevancia para la consulta. Puede cambiar el orden de las personas en la respuesta utilizando 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 información y ejemplos, consulte la sección Realizar una búsqueda parcial en Obtener información relevante sobre personas.
$select string Lista separada por comas de las propiedades que se van a incluir en la respuesta. Para un rendimiento óptimo, seleccione solo el subconjunto de propiedades necesarias.
$skip int Se omiten los primeros resultados n, útil para la paginación. Esta opción no se admite cuando se usa $search.
$top int Número de resultados que se van a devolver.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio.
Aceptar application/json

Cuerpo de solicitud

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

Respuesta

Si se realiza correctamente, este método devuelve un código 200 OK de respuesta y una colección de objetos person en el cuerpo de la respuesta.

Ejemplos

Examinar

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

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

Solicitud

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

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

Respuesta

Aquí tiene un ejemplo de 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 contactos relevantes, puede realizar una segunda solicitud mediante $top y $skip para solicitar páginas adicionales de información. Si la anterior solicitud tiene información adicional, la siguiente solicitud obtiene la siguiente página de contactos 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 ejemplo siguiente se solicitan las 1.000 personas más relevantes para /me . La solicitud también limita la cantidad de datos enviados desde el servidor solicitando solo 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 desde el servidor mediante el parámetro $select para elegir uno o varios campos. El campo @odata.id siempre se devuelve.

En el ejemplo siguiente se limita la respuesta a 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 las personas con el origen "Directory".

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

Selección de los campos que se devolverán 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 obtiene el DisplayName y EmailAddress de 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 que ha iniciado sesión ( /me ). Las solicitudes de búsqueda requieren el permiso People.Read.

Uso de 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 a cuyo /me Nombre Dado 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 a cuyo /me nombre contiene "ma" y que tienen una asociación con "planeación de características".

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

La siguiente solicitud realiza una búsqueda de una persona denominada "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 el permiso User.ReadBasic.All para People.Read.All. En este ejemplo, se muestran las personas relevantes de Nestor Kellum.

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