Usar la API de contactos de Microsoft Graph para obtener información sobre los contactos más relevantes para ustedUse the People API in Microsoft Graph to get information about the people most relevant to you

Las aplicaciones de Microsoft Graph usar la API de contactos para recuperar los contactos 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. Los contactos pueden ser contactos locales, contactos de las redes sociales o el directorio de la organización y contactos de comunicaciones recientes (como de correo electrónico y Skype). Además de generar esta información, la API de contactos ofrece también compatibilidad con la búsqueda de coincidencia aproximada y la posibilidad de recuperar la lista de usuarios relevantes para otro usuario de la organización del usuario que ha iniciado sesión. La API de contactos resulta especialmente útil en escenarios de selección de personas, como redactar un mensaje de correo o crear una reunión. Por ejemplo, puede usar la API de contactos en escenarios de redacción de mensajes de correo.Microsoft Graph applications can use the People API to retrieve the people who are most relevant to a user. Relevance is determined by the user’s communication and collaboration patterns and business relationships. People can be local contacts, contacts from social networking or from an organization’s directory, and people from recent communications (such as email and Skype). Along with generating this insight, the People API also provides fuzzy matching search support and the ability to retrieve the list of users relevant to another user in the signed-in user's organization. The People API is particularly useful for people picking scenarios, such as composing an email or creating a meeting. For example, you can use the People API in email compose scenarios.

AuthorizationAuthorization

Para llamar a la API de contactos de Microsoft Graph, la aplicación necesitará los permisos adecuados:To call the People API in Microsoft Graph, your app will need the appropriate permissions:

  • People.Read: úselo para realizar llamadas API de Contactos generales (por ejemplo, https://graph.microsoft.com/v1.0/me/people/). People.Read requiere el consentimiento del usuario final.People.Read - Use to make general People API calls; for example, https://graph.microsoft.com/v1.0/me/people/. People.Read requires end user consent.
  • People.Read.All: se requiere para recuperar los contactos más relevantes al usuario específico para llamadas de la organización (https://graph.microsoft.com/v1.0/users/{id}/people) del usuario que ha iniciado sesión.People.Read.All - Required to retrieve the people most relevant to a specified user in the signed-in user’s organization (https://graph.microsoft.com/v1.0/users/{id}/people) calls. People.Read.All requiere el consentimiento del administrador.People.Read.All requires admin consent.

Buscar personasBrowse people

Las solicitudes de esta sección obtienen los contactos más relevantes para el usuario que inició la sesión (/me), o bien un usuario específico en la organización del usuario que inició la sesión. Estas solicitudes necesitan el permiso People.Read o People.Read.All, respectivamente. De forma predeterminada, cada respuesta devuelve 10 registros, pero puede cambiar esto con el parámetro de consulta $top.The requests in this section get the people most relevant to the signed-in user (/me), or to a specific user in the signed-in user’s organization. These requests require the People.Read or People.Read.All permission respectively. By default, each response returns 10 records, but you can change this by using the $top query parameter.

Obtener una colección de contactos relevantesGet a collection of relevant people

La siguiente solicitud obtiene los contactos más relevantes para el usuario que ha iniciado sesión (/me), en función de las relaciones empresariales y los patrones de comunicación y colaboración del usuario.The following request gets the people most relevant to the signed-in user (/me), based on communication and collaboration patterns and business relationships.

GET https://graph.microsoft.com/v1.0/me/people/

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro de consulta $top. En este ejemplo se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this by using the $top query parameter. This example uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.onmicrosoft.com",
      "imAddress": "sip:LorrieF@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.onmicrosoft.com",
      "imAddress": "sip:MaynardD@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.onmicrosoft.com",
      "imAddress": "sip:DarrelH@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Solicitar una página posterior de contactosRequest a subsequent page of people

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.If the first response does not contain the complete list of relevant people, you can make a second request using $top and $skip to request additional pages of information. If the previous request has additional information, the following request gets the next page of people from the server.

GET https://graph.microsoft.com/v1.0/me/people/?$top=3&$skip=10

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro de consulta $top. En este ejemplo se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this by using the $top query parameter. This example uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola",
      "givenName": "Felix",
      "surname": "Coppola",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Legal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2109",
      "profession": "",
      "userPrincipalName": "FelixC@contoso.onmicrosoft.com",
      "imAddress": "sip:FelixC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0104"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland",
      "givenName": "Lenora",
      "surname": "Rowland",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/1106",
      "profession": "",
      "userPrincipalName": "LenoraR@contoso.onmicrosoft.com",
      "imAddress": "sip:LenoraR@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 954 555 0118"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette",
      "givenName": "Manuel",
      "surname": "Collette",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Accountant II",
      "companyName": null,
      "yomiCompany": "",
      "department": "Finance",
      "officeLocation": "98/2202",
      "profession": "",
      "userPrincipalName": "ManuelC@contoso.onmicrosoft.com",
      "imAddress": "sip:ManuelC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Ordenar la respuestaSort the response

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 los contactos más relevantes para usted, los ordena por su displayName y luego devuelve los 10 primeros contactos en la lista ordenada.By default, the people in the response are sorted by their relevance to your query. You can change the order of the people in the response by using the $orderby parameter. This query selects the people most relevant to you, sorts them by their displayName, and then returns the first 10 people on the sorted list.

GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro $top. En el ejemplo siguiente se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this by using the $top parameter. The following example uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos",
      "givenName": "Adriana",
      "surname": "Ramos",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/2111",
      "profession": "",
      "userPrincipalName": "AdrianaR@contoso.onmicrosoft.com",
      "imAddress": "sip:AdrianaR@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 425 555 0109"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley",
      "givenName": "Alyce",
      "surname": "Cooley",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "131/1104",
      "profession": "",
      "userPrincipalName": "AlyceC@contoso.onmicrosoft.com",
      "imAddress": "sip:AlyceC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 858 555 0110"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke",
      "givenName": "Alyssa",
      "surname": "Clarke",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Corporate Security Officer",
      "companyName": null,
      "yomiCompany": "",
      "department": "Operations",
      "officeLocation": "24/1106",
      "profession": "",
      "userPrincipalName": "AlyssaC@contoso.onmicrosoft.com",
      "imAddress": "sip:AlyssaC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 262 555 0106"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Cambiar el número de contactos y campos devueltosChange the number of people and fields returned

Puede cambiar el número de contactos devueltos en la respuesta estableciendo el parámetro $top.You can change the number of people returned in the response by setting the $top parameter.

En el siguiente ejemplo se solicitan los 1000 contactos más relevantes para /me. La solicitud limita también la cantidad de datos que se devuelven del servidor solicitando solo el displayName del contacto.The following example requests the 1,000 people most relevant to /me. The request also limits the amount of data sent back from the server by requesting only the displayName of the person.

GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName

En el ejemplo siguiente se muestra la respuesta.The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye"
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman"
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey"
    },
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Roscoe Seidel"
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke"
    },
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos"
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley"
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Wayne Leeper"
    },
    {
      "id": "E7D40AC5-0078-4575-B1F3-F738124C4BC9",
      "displayName": "Jan Travis"
    },
    {
      "id": "6F99D1CC-4FCC-49E4-9160-E8AB01BF3E83",
      "displayName": "Charlotte Delacruz"
    },
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola"
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland"
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette"
    }
  ]
}

Tipos de resultados incluidosTypes of results included

De forma predeterminada, Microsoft Graph sirve resultados solo de buzón, que no incluyen los resultados de directorio u organización.By default, Microsoft Graph serves mailbox-only results, which do not include directory/organization results. Para recuperar resultados del directorio, especifique un encabezado HTTP como se muestra.To retrieve directory results, specify an HTTP header, as shown.

"X-PeopleQuery-QuerySources: Mailbox,Directory”

Seleccionar los campos que se van a devolverSelect the fields to return

Puede limitar la cantidad de datos devueltos desde el servidor usando el parámetro $select para elegir uno o varios campos. El campo @odata.id siempre se devuelve.You can limit the amount of data returned from the server by using the $select parameter to choose one or more fields. The @odata.id field is always returned.

El ejemplo siguiente limita la respuesta al displayName y el scoredEmailAddresses de los 10 contactos más relevantes.The following example limits the response to the displayName and scoredEmailAddresses of the 10 most relevant people.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro $top. En este ejemplo se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. This example uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Usar un filtro para limitar la respuestaUse a filter to limit the response

Puede usar el parámetro $filter para limitar la respuesta a solo los contactos cuyo registro contiene los criterios especificados.You can use the $filter parameter to limit the response to only those people whose record contains the specified criteria.

La consulta siguiente limita la respuesta a las instancias de person que tienen la propiedad personType que se asigna a person como class y organizationUser como subclass.The following query limits the response to person instances with the personType property being assigned person as class and organizationUser as subclass.

GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser'

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro $top. En este ejemplo se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. This example uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.onmicrosoft.com",
      "imAddress": "sip:LorrieF@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.onmicrosoft.com",
      "imAddress": "sip:MaynardD@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.onmicrosoft.com",
      "imAddress": "sip:DarrelH@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Seleccionar los campos que se van a devolver en una respuesta filtradaSelect the fields to return in a filtered response

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.You can combine the $select and $filter parameters to create a custom list of people relevant to the user and get only the fields that your application needs.

En el ejemplo siguiente se obtiene el displayName y el scoredEmailAddresses de los contactos cuyo nombre para mostrar es igual al nombre especificado. En este ejemplo, solo se devuelven los contactos cuyo nombre para mostrar es igual a "Lorrie Frye".The following example gets the displayName and scoredEmailAddresses of people whose display name equals the specified name. In this example, only people whose display name equals "Lorrie Frye" are returned.

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses&$filter=displayName eq 'Lorrie Frye'

En el ejemplo siguiente se muestra la respuesta.The following example shows the response.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.onmicrosoft.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

Explorar los contactos relevantes de otro usuarioBrowse another user’s relevant people

La siguiente solicitud obtiene los contactos más relevantes para otro contacto de la organización del usuario que inició la sesión.The following request gets the people most relevant to another person in the signed-in user's organization. Esta solicitud necesita el permiso People.Read.All.This request requires the People.Read.All permission. Todos los parámetros de consulta descritos en las secciones anteriores también son válidos.All the query parameters described in the above sections apply as well.

En este ejemplo, se muestran los contactos relevantes de Roscoe Seidel.In this example, Roscoe Seidel's relevant people are displayed.

GET https://graph.microsoft.com/v1.0/users('roscoes@contoso.com')/people/

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro $top. En el ejemplo siguiente se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. The example below uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "56155636-703F-47F2-B657-C83F01F49BBC",
      "displayName": "Clifton Clemente",
      "givenName": "Clifton",
      "surname": "Clemente",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Director",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2106",
      "profession": "",
      "userPrincipalName": "CliftonC@contoso.onmicrosoft.com",
      "imAddress": "sip:CliftonC@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.onmicrosoft.com",
          "relevanceScore": 20
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BF27D5A-AB4F-4C43-BED0-7DAD9EB0C1C4",
      "displayName": "Sheree Mitchell",
      "givenName": "Sheree",
      "surname": "Mitchell",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/2107",
      "profession": "",
      "userPrincipalName": "ShereeM@contoso.onmicrosoft.com",
      "imAddress": "sip:ShereeM@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.onmicrosoft.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0107"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "B3E5302D-EAF0-4E8B-8C6C-A2AE64B4B163",
      "displayName": "Vincent Matney",
      "givenName": "Vincent",
      "surname": "Matney",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Engineering",
      "companyName": null,
      "yomiCompany": "",
      "department": "Engineering",
      "officeLocation": "23/2102",
      "profession": "",
      "userPrincipalName": "VincentM@contoso.onmicrosoft.com",
      "imAddress": "sip:VincentM@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.onmicrosoft.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Buscar contactosSearch people

Las solicitudes de esta sección le permiten buscar contactos relevantes para el usuario que ha iniciado sesión (/me) y otros usuarios de la organización del usuario que ha iniciado sesión. Estas solicitudes requieren el permiso People.Read, salvo que se busquen contactos relevantes para otros usuarios, que requiere People.Read.All. De manera predeterminada, cada respuesta devuelve 10 registros, pero esto se puede cambiar mediante el parámetro $top.The requests in this section allow you to search for people relevant to the signed-in user (/me) and other users in the signed-in user’s organization. These requests require the People.Read permission, with the exception of searching other users’ relevant people, which requires People.Read.All. By default, each response returns 10 records, but you can change this by using the $top parameter.

Usar la búsqueda para seleccionar contactosUse search to select people

Use el parámetro $search para seleccionar contactos que reúnan un conjunto de criterios concreto.Use the $search parameter to select people who meet a particular set of criteria.

La siguiente consulta de búsqueda devuelve contactos relevantes para /me cuyo displayName o emailAddress incluya una palabra que comience con la letra "j".The following search query returns people relevant to /me whose displayName or emailAddress has a word that begins with the letter "j".

GET https://graph.microsoft.com/v1.0/me/people/?$search=j

En el ejemplo siguiente se muestra la respuesta. De manera predeterminada, cada respuesta devuelve 10 registros. Esto se puede cambiar mediante el parámetro $top. En este ejemplo se usa $top para limitar la respuesta a tres registros.The following example shows the response. By default, each response returns 10 records. You can change this using the $top parameter. This example uses $top to limit the response to three records.

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Jan Travis",
      "givenName": "Jan",
      "surname": "Travis",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "VP Sales",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "19/3123",
      "profession": "",
      "userPrincipalName": "JanT@contoso.onmicrosoft.com",
      "imAddress": "sip:JanT@contoso.onmicrosoft.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.onmicrosoft.com",
          "relevanceScore": -12.297347783416837
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 732 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "C43BF05E-5B6B-4DCF-B2FC-0837B09E0FA9",
      "displayName": "Jacob Cazares (TAILSPIN)",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JacobC@tailspintoys.com",
          "relevanceScore": -12.298154282019846
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "PersonalContact"
      }
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Jewell Montgomery",
      "givenName": "Jewell",
      "surname": "Montgomery",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "JewellM@contoso.onmicrosoft.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.onmicrosoft.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

Las búsquedas implementan un algoritmo de coincidencia aproximada.Searches implement a fuzzy matching algorithm. Se devolverán resultados basados en una coincidencia exacta y también en inferencias sobre la intención de la búsqueda.They will return results based on an exact match and also on inferences about the intent of the search. Por ejemplo, imagine un usuario con el nombre para mostrar "Tyler Lee" y la dirección de correo tylerle@example.com que se encuentra en la colección de usuarios del usuario que inició sesión.For example, imagine a user with a display name of "Tyler Lee" and an email address of tylerle@example.com who is in the people collection of the signed-in user. Todas las búsquedas siguientes devolverán este usuario Tyler como uno de los resultados.All of the following searches will return this user Tyler as one of the results.

GET https://graph.microsoft.com/v1.0/me/people?$search="tyler"                //matches both Tyler's name and email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle"              //matches Tyler's email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle@example.com"  //matches Tyler's email. Note the quotes to enclose '@'.
GET https://graph.microsoft.com/v1.0/me/people?$search="tiler"                //fuzzy match with Tyler's name
GET https://graph.microsoft.com/v1.0/me/people?$search="tyler lee"            //matches Tyler's name. Note the quotes to enclose the space.

Trabajar con la implementación de característicasWorking with feature implementation

Debe haber una relación pública entre el propietario del perfil y los demás usuarios para que esos usuarios aparezcan en la lista del propietario del perfil.There must be a public relationship between the profile owner and the other people in order for those people to show up on the profile owner's list. La ilustración siguiente muestra un Usuario A, un índice de relaciones con otros usuarios (Usuario B) y un perfil público que muestra un subconjunto de relaciones de usuario.The following illustration shows a User A, an index of relationships with other users (User B), and a public profile showing a subset of user relationships.

Imagen de trabajo con relaciones

Los siguientes son ejemplos de relaciones públicas:The following are examples of public relationships:

  • Personas conectadas en el organigrama: administrador, subordinado, compañeros (comparten el mismo administrador)Individuals connected in the org chart: Manager, Direct report, Peers (share the same manager)
  • Miembros de una lista de distribución o un grupo público con menos de 30 personas.Members of a public group or distribution list with fewer than 30 people. Los grupos públicos tienen listas de sus miembros que están disponibles en el directorio.Public groups have membership lists that are available in the directory.

Si el propietario del perfil se comunica con alguien y no hay ninguna relación pública entre ellos, como una conexión en el organigrama de la organización o un grupo en común, el hecho de que se hayan comunicado no será visible para otros usuarios.If the profile owner communicates with someone and there is no public relationship between them, such as an org chart connection or a group in common, the fact that they've been communicating will not be visible to others.

La clasificación de personas, es decir, el orden en que aparecen en la página del propietario del perfil, depende de la comunicación pública y privada entre el propietario del perfil y la persona en la lista.The ranking of people - that is, the order in which they appear on the profile owner's page - is determined by the private and public communication between the profile owner and the person on the list.

Algunos ejemplos de comunicación privada son:Examples of private communication include:

  • Enviar correos electrónicos entre dos personas en los que el nombre de la otra persona está en la línea ParaSending emails to each other where the name of the other person is in the TO line
  • Invitar a usuarios a reuniones añadiendo su nombre en la invitación de calendarioInviting users to meetings by including their name in the calendar invite

Algunos ejemplos de interacción pública son:Examples of public interaction include:

  • Enviar o recibir mensajes de correo electrónico entre dos personas como parte de un grupo públicoSending or receiving emails to/from each other as part of a public group
  • Invitar a usuarios a reuniones como parte de un grupo o a las que están invitadas más de X personasInviting users to meetings as part of group, or where more than X people are invited

La clasificación no cambia en función de quién es el usuario A (la persona consultando la página de otra persona).The ranking doesn’t change based on who User A is (the person looking at someone else's page). La clasificación se determina mediante el nivel de interacción entre el Usuario B (propietario del perfil) y el Usuario C (persona que aparece en la lista del propietario del perfil).The ranking is determined by the interaction level between User B (profile owner) and User C (person showing up on profile owner's list).

Para que el Usuario C aparezca, el propietario del perfil debe estar en un grupo o lista de distribución relativamente pequeño con el usuario que sea público (es decir, que la lista de miembros está disponible en el directorio).In order for User C to appear, the profile owner must be in a relatively small group/DL with that user that is public (meaning the membership list is available in the directory).

Las personas externas a la organización no se mostrarán en la lista del propietario del perfil.People external to the organization will not show on the profile owner's list. Las personas con las que intercambien correo electrónico o con las que tengan reuniones, pero que no formen parte de la misma organización, no se mostrarán en la sección Trabaja con.People they email or meet with, but who are not part of the same organization, will not show up in the Working with section.