Enumerar personas

Artículo
10/30/2023

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.People.GetAsync();

Importante

Los SDK de Microsoft Graph usan la versión v1.0 de la API de manera predeterminada y no admiten todos los tipos, propiedades y API disponibles en la versión beta. Para obtener más información sobre cómo acceder a la API beta con el SDK, consulte Uso de los SDK de Microsoft Graph con la API beta.

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.



mgc-beta users people list --user-id {user-id}

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
people, err := graphClient.Me().People().Get(context.Background(), nil)

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

PersonCollectionResponse result = graphClient.me().people().get();

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.


const options = {
	authProvider,
};

const client = Client.init(options);

let people = await client.api('/me/people')
	.version('beta')
	.get();

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->people()->get()->wait();

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.


Import-Module Microsoft.Graph.Beta.People

# A UPN can also be used as -UserId.
Get-MgBetaUserPerson -UserId $userId

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.me.people.get()

Importante

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

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"

Realizando una búsqueda aproximada

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/

Compartir a través de

Enumerar personas

Permissions

Solicitud HTTP

Parámetros de consulta opcionales

Encabezados de solicitud

Cuerpo de la solicitud

Respuesta

Ejemplos

Navegación

Solicitud

Respuesta

Solicitando una página posterior de personas

Ordenar la respuesta

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

Seleccionando los campos a devolver

Usando un filtro para limitar la respuesta

Selección de los campos que se devolverán en una respuesta filtrada

Buscar contactos

Uso de la búsqueda para seleccionar personas

Usar la búsqueda para especificar un tema relevante

Realizando una búsqueda aproximada

Comentarios

Recursos adicionales

Compartir a través de

Enumerar personas

Permissions

Solicitud HTTP

Parámetros de consulta opcionales

Encabezados de solicitud

Cuerpo de la solicitud

Respuesta

Ejemplos

Navegación

Solicitud

Respuesta

Solicitando una página posterior de personas

Ordenar la respuesta

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

Seleccionando los campos a devolver

Usando un filtro para limitar la respuesta

Selección de los campos que se devolverán en una respuesta filtrada

Buscar contactos

Uso de la búsqueda para seleccionar personas

Usar la búsqueda para especificar un tema relevante

Realizando una búsqueda aproximada

Personas relacionadas

Comentarios

Recursos adicionales