Uso de la API de Microsoft Búsqueda para buscar personas

Artículo
03/26/2023

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"
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Pasos siguientes

Empleo de la API de Búsqueda de Microsoft para consultar datos