获取联系人Get contact

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

检索 contact 对象的属性和关系。Retrieve the properties and relationships of a contact object.

在以下两种情况下,应用可以在其他用户的 "联系人" 文件夹中获取联系人:There are two scenarios where an app can get a contact 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

来自用户的默认 contactFolder 中的 联系人A contact from a user's default contactFolder.

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

来自用户的顶级 contactFolder 中的 联系人A contact from a user's top level contactFolder.

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

contactFolder 的子文件夹中包含的 联系人。下面的示例显示了一个嵌套级别,但联系人可能位于子级的子级中,诸如此类。A contact contained in a child folder of a contactFolder. The example below shows one level of nesting, but a contact can be located in a child of a child and so on.

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

可选的查询参数Optional query parameters

名称Name Value 说明Description
$expand$expand stringstring 要在响应中扩展和包括的关系的列表(以逗号分隔)。请参阅支持的名称的 contact 对象的关系表。Comma-separated list of relationships to expand and include in the response. See the relationships table of the contact object for supported names.
$select$select stringstring 要在响应中包括的属性的列表(以逗号分隔)。Comma-separated list of properties to include in the response.

请求标头Request headers

标头Header Value
AuthorizationAuthorization Bearer {token}。必需。Bearer {token}. Required.

请求正文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 contact object in the response body.

示例Example

请求Request

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

GET https://graph.microsoft.com/v1.0/me/contacts/{id}
响应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: 1977

{
  "id": "AAMkAGI2THk0AAA=",
  "createdDateTime": "2014-10-19T23:08:24Z",
  "lastModifiedDateTime": "2014-10-19T23:08:24Z",
  "changeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4",
  "categories": [],
  "parentFolderId": "AAMkAGI2AAEOAAA=",
  "birthday": "1974-07-22",
  "fileAs": "Fort, Garth",
  "displayName": "Garth Fort",
  "givenName": "Garth",
  "initials": "G.F.",
  "middleName": null,
  "nickName": "Garth",
  "surname": "Fort",
  "title": null,
  "yomiGivenName": null,
  "yomiSurname": null,
  "yomiCompanyName": null,
  "generation": null,
  "emailAddresses": [
    {
      "name": "Garth",
      "address": "garth@a830edad9050849NDA1.onmicrosoft.com"
    }
  ],
  "imAddresses": [
    "sip:garthf@a830edad9050849nda1.onmicrosoft.com"
  ],
  "jobTitle": "Web Marketing Manager",
  "companyName": "Contoso, Inc.",
  "department": "Sales & Marketing",
  "officeLocation": "20/1101",
  "profession": null,
  "businessHomePage": "https://www.contoso.com",
  "assistantName": null,
  "manager": null,
  "homePhones": [],
  "mobilePhone": null,
  "businessPhones": [
    "+1 918 555 0101"
  ],
  "homeAddress": {},
  "businessAddress": {
      "street": "10 Contoso Way",
      "city": "Redmond",
      "state": "WA",
      "countryOrRegion": "USA",
      "postalCode": "98075"  
  },
  "otherAddress": {},
  "spouseName": null,
  "personalNotes": null,
  "children": []
}