Uso de la API de Microsoft Búsqueda para buscar personas
Las aplicaciones de Microsoft Graph pueden usar la API de Microsoft Búsqueda para recuperar las personas más relevantes para un usuario. La relevancia viene determinada por las relaciones empresariales y los patrones de comunicación y colaboración del usuario. Personas pueden ser contactos locales o desde el directorio de una organización o personas de comunicaciones recientes.
Junto con la generación de esta información, la búsqueda también proporciona compatibilidad con búsquedas coincidentes aproximadas y la capacidad de recuperar la lista de usuarios relevantes para otro usuario de la organización del usuario que ha iniciado sesión.
API de Personas
Puede usar las siguientes API para buscar personas dentro de una organización.
- /Búsqueda
- /Gente
Nota:
Se recomienda que los usuarios llamen al /search punto de conexión en lugar del /people punto de conexión. En el futuro, todas las inversiones futuras solo estarán disponibles en el /search punto de conexión; el punto de /people conexión está en modo de mantenimiento.
Propiedades de personas devueltas
La API people devuelve el siguiente conjunto de propiedades.
| Propiedad | Tipo |
|---|---|
| additionalOfficeLocation | Cadena |
| CompanyName | String |
| department | Cadena |
| displayName | Cadena |
| emailAddress | Cadena |
| givenName | Cadena |
| hitId | Cadena |
| imAddress | String |
| jobTitle | Cadena |
| officeLocation | String |
| personType | Cadena |
| phones | Cadena |
| rank | Entero |
| summary | Cadena |
| surname | Cadena |
| userPrincipalName | Cadena |
Tipos de persona
En la tabla siguiente se muestran los tipos y subtipos de personas admitidos en la API de personas.
| Variaciones de personas, grupos y salas admitidas | Detalles del tipo de destinatario | Mailbox | Directorio | Personas tipo | subtipo Personas | Notas |
|---|---|---|---|---|---|---|
| Usuario de la organización | UserMailbox, MailUser | v | v | Contacto | OrganizationUser | Un usuario que pertenece a la organización. |
| Usuario de la organización sin dirección de correo electrónico | Usuario | Y (desactivado de forma predeterminada) | Y (desactivado de forma predeterminada) | Contacto | OrganizationUser | Un usuario que pertenece a la organización. |
| Contacto de la organización | MailContact, Contact | N | v | Contacto | OrganizationContact | Un contacto agregado explícitamente a la lista global de direcciones (GAL) por el administrador de inquilinos, pero que no forma parte de la organización. |
| Contacto privado | Contacto | Y | N/D | Contacto | PersonalContact | Un contacto creado explícitamente por el usuario que no pertenece a la organización. Si el usuario agrega manualmente a sus contactos a alguien que forma parte de la organización, se clasificará como OrganizationUser. |
| Contacto privado sin dirección de correo electrónico | Contacto | Y (desactivado de forma predeterminada) | N/D | Contacto | PersonalContact | Un contacto creado explícitamente por el usuario que no pertenece a la organización. Si el usuario agrega manualmente a sus contactos a alguien que forma parte de la organización, se clasificará como OrganizationUser. |
| Contacto implícito del historial de comunicaciones | Contacto | Y | N/D | Contacto | ImplicitContact | Un contacto inferido del historial de comunicaciones (correo electrónico y chat) que no tenemos suficiente información sobre para determinar si es una persona, grupo, etc. En las cuentas empresariales, siempre será un contacto externo de la organización, ya que los contactos dentro de la organización que se encuentran en el historial de comunicaciones siempre se clasificarán como OrganizationUser. Para las cuentas de consumidor, todo lo que no sea un PersonalContact objeto se clasifica como ImplicitContact. |
| Contacto implícito del historial de chat | Contacto | Y | N/D | Contacto | ChatImplicitContact | Igual que ImplicitContact, pero cuando el historial de comunicación es exclusivamente del chat. |
| Sala | Rooms | v | v | Otros | Sala | |
| Guest | GuestUser | v | v | Otros | Guest | |
| Invitado oculto | GuestUser | Y (desactivado de forma predeterminada) | Y (desactivado de forma predeterminada) | Otros | Guest | |
| Grupo moderno | Group | v | v | Group | UnifiedGroup | Grupo conocido como: Grupo de Exchange 365, Grupos modernos, Grupos de Microsoft 365. Para obtener más información sobre Grupos de Microsoft 365, consulte Más información sobre Grupos de Microsoft 365. |
| Grupo de Teams | Group | v | v | Group | UnifiedGroup | Igual que Grupos de Microsoft 365, pero representa internamente un equipo de Microsoft Teams. |
| Grupo de Teams oculto | Group | Y (desactivado de forma predeterminada) | Y | Group | UnifiedGroup | Grupo de Teams oculto. |
| Lista de distribución | Group | v | v | Group | PublicDistributionList | Lista de distribución de Exchange clásica o grupo de seguridad habilitado para correo. |
| Lista de distribución personal | Contacto | Y (desactivado de forma predeterminada) | N/D | Group | PersonalDistributionList | Un grupo de distribución virtual creado por el usuario como asistente para enviar correos electrónicos a varios contactos de forma sencilla. Solo se usa para Outlook en la Web redactar como una característica de experiencia de usuario, no se devuelve para otros autores de llamadas. |
| Objeto oculto de cualquier tipo excepto invitado y grupo de Teams | N | N |
Detalles de la solicitud
Haga que los resultados de la API de personas sean más específicos proporcionando detalles adicionales al realizar una solicitud. Las siguientes son algunas maneras de hacer que las solicitudes sean más específicas.
Ejemplo 1: Solo resultados del buzón
"Provenances": ["Mailbox"]
Ejemplo 2: Resultados de ambos orígenes
"Provenances": ["Mailbox", "Directory"]
Origen de los resultados
Personas resultados proceden de dos orígenes, buzón o directorio. De forma predeterminada, los resultados procederán de ambos orígenes con conflictos que se quitan, lo que garantiza que no se devolverán los mismos valores.
Nota: En caso de conflicto, se prefieren los orígenes de directorio.
Los resultados del buzón constan de:
- Personas quién le envió un correo electrónico
- Personas a quién envió un correo electrónico
- Personas tuvo una reunión con
- Personas que tuvo un chat de Teams
- Personas en el organigrama del administrador
- Contactos públicos de las personas anteriores
Aspectos pertinentes para el caso de uso cuando un origen de directorio busca en la lista global de direcciones en Microsoft Entra ID:
- No aplicable a los usuarios consumidores
- Personas que no están en la lista global de direcciones del autor de la llamada no se devolverán
- Personas que están ocultos por IBP (protocolo de barrera de información) no se devolverán
- Personas que están ocultos en la lista de direcciones no se devolverán
Obtener más resultados
Especifique el tamaño para obtener más resultados. De forma predeterminada, se devolverán 25 resultados o menos en función de las coincidencias de consulta de búsqueda.
"Size": 25
Especificar el índice mínimo para la paginación
Establezca el índice mínimo para la paginación para especificar la página inicial de resultados. De forma predeterminada, el índice mínimo para la paginación es 0 y el primer resultado es el más relevante.
"From": 0
Seleccionar los campos que se van a devolver
La API devuelve un conjunto de propiedades predeterminadas, pero puede personalizar una solicitud para devolver un número específico de propiedades. En el ejemplo siguiente se limita la respuesta a las propiedades DisplayName, EmailAddresses y phones .
"Fields": ["DisplayName", "EmailAddresses", "phones"]
Usar un filtro para limitar la respuesta
Use el objeto Filter para limitar la respuesta a valores específicos. Los valores de filtro posibles son: PeopleType, PeopleSubType.
En los ejemplos siguientes se muestran solicitudes que usan el objeto Filter para devolver personas cuyo registro contiene los criterios especificados.
Ejemplo 1: Sugerencias de filtro a persona
En el ejemplo siguiente se limita la respuesta solo a sugerencias de personas. La respuesta contiene contactos privados y de la organización.
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
}
]
},
Ejemplo 2: Filtrar sugerencias de persona dentro de la organización
En el ejemplo siguiente se limita el reponse solo a los usuarios empresariales.
"Filter": {
"And": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
}
]
},
Ejemplo 3: Filtrar a todos los usuarios, listas de distribución o lista de distribución moderna de la organización
En el ejemplo siguiente se limita la respuesta a diferentes categorías de PeopleSubtype.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "PublicDistributionList"
}
},
{
"Term": {
"PeopleSubtype": "UnifiedGroup"
}
}
]
},
Ejemplo 4: Filtrar a usuarios de la organización y salas de reuniones
En el ejemplo siguiente se limita la respuesta a los usuarios de la organización y a las salas de reuniones.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Rooms"
}
}
]
},
Ejemplo 5: Filtrar a usuarios e invitados de la organización
En el ejemplo siguiente se limita la respuesta a usuarios e invitados de la organización.
"Filter": {
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
},
Ejemplo 6: Combinación de varios filtros
En el ejemplo siguiente se combinan varios filtros para limitar la respuesta a los criterios especificados.
"Filter": {
"And": [
{
"Or": [
{
"Term": {
"PeopleType": "Person"
}
},
{
"Term": {
"PeopleType": "Other"
}
}
]
},
{
"Or": [
{
"Term": {
"PeopleSubtype": "OrganizationUser"
}
},
{
"Term": {
"PeopleSubtype": "Guest"
}
}
]
}
]
},
Solicitud completa
Ejemplo: Búsqueda persona por nombre
La siguiente solicitud obtiene a las personas más relevantes para el usuario que ha iniciado sesión, en función de los patrones de comunicación y colaboración y las relaciones empresariales.
Solicitud
POST https://graph.microsoft.com/beta/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": [
"person"
],
"query": {
"queryString": "contoso"
},
"from": 0,
"size": 25
}
]
}
Respuesta
A continuación se muestra un ejemplo de la respuesta, que contiene un mensaje que coincide con el criterio de búsqueda.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.searchResponse",
"value": [
{
"hitsContainers": [
{
"total": 1,
"moreResultsAvailable": false,
"hits": [
{
"hitId": "fc138b85-18ac-48e0-80a4-633ae4b594e0@41f988bf-86f1-53af-91ab-2d7cd034db47",
"rank": 1,
"summary": "",
"resource": {
"@odata.type": "#microsoft.graph.person",
"displayName": "Example User",
"givenName": "User",
"surname": "User",
"department": "Finance",
"officeLocation": "London",
"userPrincipalName": "example.user@contoso.com",
"emailAddresses": [
{
"address": "example.user@contoso.com",
"rank": 1
}
],
"phones": [
{
"type": "business",
"number": "+44 (20) 12345678"
}
]
}
}
]
}
]
}
]
}