列出联系人List contacts

命名空间:microsoft.graphNamespace: microsoft.graph

从已登录用户的默认联系人文件夹中获取联系人集合。Get a contact collection from the default contacts folder of the signed-in user.

在以下两种情况下,应用可以获取其他用户的联系人文件夹中的联系人:There are two scenarios where an app can get contacts in another user's contact folder:

  • 如果该应用程序具有应用程序权限,或者If the app has application permissions, or,
  • 如果应用程序具有来自某个用户的相应委派权限,而另一个用户与该用户共享了联系人文件夹,或者已为该用户授予委派的访问权限。If the app has the appropriate delegated permissions from one user, and another user has shared a contact folder with that user, or, has given delegated access to that user. 请参阅详细信息和示例See details and an example.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) Contacts.Read、Contacts.ReadWriteContacts.Read, Contacts.ReadWrite
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) Contacts.Read、Contacts.ReadWriteContacts.Read, Contacts.ReadWrite
应用程序Application Contacts.Read、Contacts.ReadWriteContacts.Read, Contacts.ReadWrite

HTTP 请求HTTP request

若要获取用户邮箱中的所有联系人,请执行以下操作:To get all the contacts in a user's mailbox:

GET /me/contacts
GET /users/{id | userPrincipalName}/contacts

若要获取用户邮箱中特定文件夹中的联系人,请执行以下操作:To get contacts in a specific folder in the user's mailbox:

GET /me/contactfolders/{Id}/contacts
GET /users/{id | userPrincipalName}/contactfolders/{id}/contacts

GET /me/contactFolder/{id}/childFolders/{id}/.../contacts
GET /users/{id | userPrincipalName}/contactFolders/{id}/childFolders/{id}/contacts

可选的查询参数Optional query parameters

可以使用 $filter 查询参数根据联系人的电子邮件地址来筛选联系人:You can use the $filter query parameter to filter contacts based on their email addresses:

GET https://graph.microsoft.com/v1.0/me/contacts?$filter=emailAddresses/any(a:a/address eq 'garth@contoso.com')

请注意,可以仅针对 emailAddresses 集合的实例的 address 子属性使用 $filteranyeq 运算符。Note that you can use $filter, any, and the eq operator on only the address sub-property of instances in an emailAddresses collection. 也就是说,不能筛选 emailAddresses 的实例的 name 或其他子属性,也不能对 filter 应用任何其他运算符或函数,例如 nelestartswith()That is, you cannot filter on the name or any other sub-property of an instance of emailAddresses, nor can you apply any other operator or function with filter, such as ne, le, and startswith().

有关 $filter 查询参数的一般信息,请参阅 OData 查询参数For general information on the $filter query parameter, see OData query parameters.

请求标头Request headers

标头Header Value
AuthorizationAuthorization Bearer {token}。必需。Bearer {token}. Required.
Content-TypeContent-Type application/jsonapplication/json

请求正文Request body

请勿提供此方法的请求正文。Do not supply a request body for this method.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 Contact 对象集合。If successful, this method returns a 200 OK response code and collection of Contact objects in the response body.

示例Example

请求Request

下面是一个请求示例。Here is an example of the request.

GET https://graph.microsoft.com/v1.0/me/contacts
响应Response

下面是一个响应示例。注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

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

{
  "value": [
    {
      "parentFolderId": "parentFolderId-value",
      "birthday": "datetime-value",
      "fileAs": "fileAs-value",
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "initials": "initials-value"
    }
  ]
}