Enumerar personas

  • Artículo

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.

Recupere 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.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

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

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores 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 de 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, consulte la sección Realización de una búsqueda aproximada en Uso de la API de Personas 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, útiles para la paginación. No se admite la omisión al usar $search.
$top int Número máximo de resultados que se devolverán en una página de resultados. Para obtener más información, consulte parámetro superior.

Encabezados de solicitud

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

Cuerpo de la solicitud

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

Respuesta

Si se ejecuta correctamente, este método devuelve un 200 OK có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 a 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 empresariales.

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

Solicitud

A continuación se muestra 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 ejemplo siguiente se solicita a las 1000 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.idsiempre 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 consulta siguiente limita la respuesta a las personas con el "Directorio" de origen.

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 obtienen los valores DisplayName y 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 que ha iniciado sesión (/me). Búsqueda solicitudes requieren el Personas. Permiso de lectura.

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 las personas relevantes a /me cuyo nombre o apellido given comienzan 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 contiene "ma" y que tienen una asociación con "planeamiento 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 User.ReadBasic.All para Personas. Permiso Read.All. En este ejemplo, se muestran las personas relevantes de Nestor Kellum.

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