Outlook 联系人 REST API 参考（测试版）

项目
06/30/2018

备注

这个文档涵盖了预览版联系人 API 的测试版本。预览功能在最终确定之前可能会发生变化，并可能会破坏使用它们的代码。正因为如此，一般而言，生产代码中只应使用生产版本的 API。如果可用，2.0 版目前是首选版本。

Outlook Contacts API 可以提供访问 Office 365 上由 Azure Active Directory 保护的用户联系人和联系人文件夹，以及特定于以下域中的Microsoft帐户中的类似数据：Hotmail.com、Live.com、MSN.com、Outlook.com 和 Passport.com。

备注

为简便起见，本文的其余部分使用 Outlook.com 来指代这些 Microsoft 帐户域。

对 API 的 beta 版本不感兴趣？ 在左侧的目录中，转到 Office 365 REST API 参考部分，然后选择所需的版本。

所有联系人 API 操作

联系人的操作

联系人存储在联系人文件夹中。你可以获取、创建、更改和删除联系人。

获取联系人
同步联系人和联系人文件夹
创建联系人
更新联系人
删除联系人

联系人文件夹操作

联系人文件夹可包含联系人和其他联系人文件夹。你可以获取联系人文件夹并在联系人文件夹中创建联系人。

获取联系人文件夹

联系人照片操作

每个联系人都可以有可选的联系人图片。可以获取或设置联系人的照片。

获取联系人照片
设置联系人照片

另请参阅

使用联系人 REST API

身份验证

像其他 Outlook REST API 那样，对于“联系人 API”的每个请求，都应该包含有效的访问令牌。获取访问令牌需要注册和识别应用，并获得适当的授权。

你可以了解更多有关简化注册和授权选项的信息。在“联系人 API”中继续执行特定操作时，请记住这一点。

API 版本

Outlook REST API 的所有版本都支持“联系人 REST API”。功能可能因具体版本而异。

目标用户

“联系人 API”请求始终代表当前用户执行。

有关 Outlook REST API 所有子集的更多信息，请参阅使用 Outlook REST API。

获取联系人

你可以从联系人文件夹中获取联系人集合或个人联系人。

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic
获取联系人集合
获取联系人

获取联系人集合

从登录用户邮箱 (.../me/contacts) 或从指定的联系人文件夹中获取所有联系人。

GET https://outlook.office.com/api/beta/me/contacts
GET https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}/contacts

必需的参数	类型	说明
URL 参数
contact_folder_id	字符串	联系人文件夹 ID，如果你正从特定文件夹获取联系人。

备注

默认情况下，响应中的每个联系人都包含其所有属性。使用 $select 仅指定你需要的属性，以便获得最佳性能。始终返回 Id 属性。请参阅用于筛选、排序和分页参数的 OData 查询参数。

示例请求

GET https://outlook.office.com/api/beta/me/contacts?$select=EmailAddresses,GivenName,Surname

示例响应

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk3AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2THk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THkzAAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2THkzAAA=",
            "GivenName": "Janet",
            "Surname": "Schorr",
            "EmailAddresses": [
                {
                    "Name": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        }
    ]
}

响应类型

请求的联系人集合。

获取联系人

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic

使用联系人 ID 获取联系人。

GET https://outlook.office.com/api/beta/me/contacts/{contact_id}

必需的参数	类型	说明
URL 参数
contact_id	字符串	联系人 ID。

响应类型

请求的联系人。

示例请求

GET https://outlook.office.com/api/beta/me/contacts/AAMkADlkAAAMRFUEAAA=

示例响应

Status code: 200

{
    "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
    "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAAMRFUEAAA=')",
    "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAAMRdhl\"",
    "Id":"AAMkADlkAAAMRFUEAAA=",
    "CreatedDateTime":"2016-07-16T06:43:15Z",
    "LastModifiedDateTime":"2016-07-16T06:43:15Z",
    "ChangeKey":"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAAMRdhl",
    "Categories":[
    ],
    "ParentFolderId":"AAMkADlk8yAbgAAAAAAEkAAA=",
    "Birthday":null,
    "FileAs":"",
    "DisplayName":"Garret Vargas",
    "GivenName":"Garret",
    "Initials":null,
    "MiddleName":null,
    "NickName":null,
    "Surname":"Vargas",
    "Title":null,
    "YomiGivenName":null,
    "YomiSurname":null,
    "YomiCompanyName":null,
    "Generation":null,
    "EmailAddresses":[
        {
            "Name":"Garret Vargas",
            "Address":"GarretV@contoso.onmicrosoft.com"
        }
    ],
    "Websites":[
    ],
    "ImAddresses":[
        "sip:garretv@contoso.onmicrosoft.com"
    ],
    "JobTitle":"CVP Operations",
    "CompanyName":"",
    "Department":"Operations",
    "OfficeLocation":"36/2121",
    "Profession":null,
    "AssistantName":null,
    "Manager":null,
    "Phones":[
        {
            "Type":"Home",
            "Number":""
        },
        {
            "Type":"Business",
            "Number":"+1 206 555 0105"
        },
        {
            "Type":"Mobile",
            "Number":""
        }
    ],
    "PostalAddresses":[
        {
            "Type":"Business",
            "City":"Seattle"
        }
    ],
    "SpouseName":null,
    "PersonalNotes":null,
    "Children":[
    ],
    "Gender":null,
    "IsFavorite":null,
    "Flag":{
        "FlagStatus":"NotFlagged"
    }
}

备注

默认情况下，响应包含联系人的所有属性。使用 $select 仅指定你需要的属性，以便获得最佳性能。始终返回 Id 属性。请参阅用于筛选、排序和分页参数的 OData 查询参数。

以下示例显示如何使用 $select 指定在响应中只返回联系人的 EmailAddresses、GivenName 和 Surname 属性。

示例请求

GET https://outlook.office.com/api/beta/me/contacts/AAMkAGI2THk0AAA=?$select=EmailAddresses,GivenName,Surname

示例响应

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAAMRFUEAAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkADlkAAAMRFUEAAA=",
    "GivenName": "Garth",
    "Surname": "Vargas",
    "EmailAddresses": [
       {
            "Name":"Garret Vargas",
            "Address":"GarretV@contoso.onmicrosoft.com"
        }
    ]
}

同步联系人和联系人文件夹

你可以将本地联系人列表与服务器上的联系人同步。联系人同步按文件夹执行操作，例如，你可以同步根联系人文件夹中的所有联系人。如果你有其他联系人文件夹，则需要单独同步每个文件夹。

同步只支持完全同步；每个请求都返回指定文件夹中的所有联系人。

同步联系人文件夹通常需要两个或更多的 GET 请求。你提出 GET 请求与你获取联系人的方式很像，除了你添加以下请求标头。

你必须在所有同步请求中指定 Prefer: odata.track-changes 标头。
你可以指定 Prefer: odata.maxpages={n} 标头来设置每个请求中返回的联系人的最大数量。

第二个和后续的 GET 请求与第一个 GET 请求不同，不同处在于包括在之前的响应中收到一个 deltaToken 或者一个 skipToken。

对同步请求的初始响应始终返回一个 deltaToken。你应该始终使第二个 GET 请求使用 deltaToken 以确定是否有任何其他联系人。第二个请求将返回其他联系人和一个 skipToken （如果有更多的联系人可用），或者一个 deltaToken （如果发送了最后一个联系人）。

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic

GET https://outlook.office.com/api/beta/me/Contacts
GET https://outlook.office.com/api/beta/me/ContactFolders/{folderName}

必需的参数	类型	说明
标头参数
Prefer	odata.track-changes	表示该请求是一个同步请求。
Prefer	odata.maxpagesize	设置每个响应中返回的联系人数量。
URL 参数
folderName	字符串	要同步的文件夹名称。
odata.deltaLink	字符串	该令牌表示该文件夹同步的最后时间。
odata.skiptoken	字符串	表示有更多消息要下载的令牌。

响应类型

集合包含请求的联系人和一个 deltaToken，你用其请求来自服务器的其他联系人数据的页面并用其请求增量同步。如果返回的联系人数量多于 odata.maxpagesize 标头中指定的值，那该响应将以多个页面返回。

响应将包括一个 Preference-Applied: odata-trackchanges 标头。如果你尝试同步不支持的资源，则这个标头将不会在响应中返回。请在处理响应之前检查这个标头以避免错误。

备注

默认情况下，响应包含指定联系人的所有属性。使用 $select 以只指定你需要获得最佳性能的属性。始终返回 Id 属性。请不要使用 $filter、$orderby、$search 或 $top，因为它们不支持同步联系人或联系人文件夹。请参阅 OData 查询参数了解更多详情。

示例

完全同步的初始请求：

GET https://outlook.office.com/api/beta/Me/Contacts

包括以下标头：

Prefer: odata.track-changes
Prefer: odata.maxpagesize=100

在完全同步请求后向服务器发出第二次请求：

https://outlook.office.com/api/beta/Me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

包括以下标头：

Prefer: odata.track-changes
Prefer: odata.maxpagesize=100

来自服务器的第二次响应，并提供其他页面：

标头

Preference-Applied: odata.track-changes

正文

@odata.deltaLink=https://outlook.office.com/api/beta/me/Contacts/messages/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

有效负载消息

所有联系人发送后来自服务器的第二次或后续的响应：

标头

Preference-Applied: odata.track-changes

正文

@odata.deltaLink=https://outlook.office.com/api/beta/me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

有效负载消息

当提供其他页面时请求服务器：

https://outlook.office.com/api/beta/Me/Contacts/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

包括以下标头：

Prefer: odata.track-changes
Prefer: odata.maxpagesize=100

创建联系人

在指定的“联系人”文件夹中创建联系人。

创建联系人

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.readwrite
wl.contacts_create

将联系人添加到联系人根文件夹或其他联系人文件夹的 contacts 端点中。

POST https://outlook.office.com/api/beta/me/contacts
POST https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}/contacts

必需的参数	类型	说明
URL 参数
contact_folder_id	字符串	联系人文件夹 ID，如果你正在特定联系人文件夹中创建联系人。
正文参数
GivenName	字符串	联系人的名字。

在请求正文中指定 GivenName 参数和任何可写联系人的属性。

示例请求

POST https://outlook.office.com/api/beta/me/contacts
Content-Type: application/json

{
  "GivenName": "Pavel",
  "Surname": "Bansky",
  "EmailAddresses": [
    {
      "Address": "pavelb@contoso.onmicrosoft.com",
      "Name": "Pavel Bansky"
    }
  ],
  "Phones": [
    {
      "Type": "Business",
      "Number": "+1 732 555 0102"
    }
  ]
}

示例响应

Status code: 201

{
  "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
  "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAARKMK7AAA=')",
  "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia\"",
  "Id":"AAMkADlkAAARKMK7AAA=",
  "CreatedDateTime":"2016-07-20T23:59:37Z",
  "LastModifiedDateTime":"2016-07-20T23:59:38Z",
  "ChangeKey":"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia",
  "Categories":[
  ],
  "ParentFolderId":"AAMkADlk8yAbgAAAAAAEOAAA=",
  "Birthday":null,
  "FileAs":"",
  "DisplayName":"Pavel Bansky",
  "GivenName":"Pavel",
  "Initials":null,
  "MiddleName":null,
  "NickName":null,
  "Surname":"Bansky",
  "Title":null,
  "YomiGivenName":null,
  "YomiSurname":null,
  "YomiCompanyName":null,
  "Generation":null,
  "EmailAddresses":[
    {
      "Name":"Pavel Bansky",
      "Address":"pavelb@contoso.onmicrosoft.com"
    }
  ],
  "Websites":[
  ],
  "ImAddresses":[
  ],
  "JobTitle":null,
  "CompanyName":null,
  "Department":null,
  "OfficeLocation":null,
  "Profession":null,
  "AssistantName":null,
  "Manager":null,
  "Phones":[
    {
      "Type":"Business",
      "Number":"+1 732 555 0102"
    }
  ],
  "PostalAddresses":[
  ],
  "SpouseName":null,
  "PersonalNotes":null,
  "Children":[
  ],
  "Gender":null,
  "IsFavorite":null,
  "Flag":{
    "FlagStatus":"NotFlagged"
  }
}

响应类型

新联系人。

更新联系人

更改联系人的属性。

更新联系人

更新联系人

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.readwrite
wl.contacts_create

在请求正文中指定任何可写联系人的属性。只有你指定的属性才会更改。

PATCH https://outlook.office.com/api/beta/me/contacts/{contact_id}

必需的参数	类型	说明
URL 参数
contact_id	字符串	联系人 ID。

示例请求

以下示例设置联系邮政地址和后续标志。

备注

当 Flag.FlagStatus 设置为 Flagged 时， Flag.CompletedDate 无法设置。

PATCH https://outlook.office.com/api/beta/me/contacts/AAMkADlkAAARKMK7AAA=
Content-Type: application/json

{
  "PostalAddresses": [
    {
      "Type": "Business",
      "Street": "Some street",
      "City": "Seattle",
      "State": "WA",
      "PostalCode": "98121"
    }
  ],
  "Birthday": "1974-07-22",
  "Flag": {
    "FlagStatus": "Flagged",
       "DueDateTime": {
            "DateTime": "2017-12-22T08:00:00.0000000",
            "TimeZone": "UTC"
        },
        "StartDateTime": {
            "DateTime": "2017-12-18T08:00:00.0000000",
            "TimeZone": "UTC"
        }
    }
}

示例响应

Status code: 200

{
  "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
  "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAARKMK7AAA=')",
  "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia\"",
  "Id":"AAMkADlkAAARKMK7AAA=",
  "CreatedDateTime":"2016-07-20T23:59:37Z",
  "LastModifiedDateTime":"2016-07-20T23:59:38Z",
  "ChangeKey":"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia",
  "Categories":[
  ],
  "ParentFolderId":"AAMkADlk8yAbgAAAAAAEOAAA=",
  "Birthday":"1974-07-22T00:00:00Z",
  "FileAs":"",
  "DisplayName":"Pavel Bansky",
  "GivenName":"Pavel",
  "Initials":null,
  "MiddleName":null,
  "NickName":null,
  "Surname":"Bansky",
  "Title":null,
  "YomiGivenName":null,
  "YomiSurname":null,
  "YomiCompanyName":null,
  "Generation":null,
  "EmailAddresses":[
    {
      "Name":"Pavel Bansky",
      "Address":"pavelb@contoso.onmicrosoft.com"
    }
  ],
  "Websites":[
  ],
  "ImAddresses":[
  ],
  "JobTitle":null,
  "CompanyName":null,
  "Department":null,
  "OfficeLocation":null,
  "Profession":null,
  "AssistantName":null,
  "Manager":null,
  "Phones":[
    {
      "Type":"Business",
      "Number":"+1 732 555 0102"
    }
  ],
  "PostalAddresses":[
    {
      "Type": "Business",
      "Street": "Some street",
      "City": "Seattle",
      "State": "WA",
      "PostalCode": "98121"
    }
  ],
  "SpouseName":null,
  "PersonalNotes":null,
  "Children":[
  ],
  "Gender":null,
  "IsFavorite":null,
  "Flag": {
        "FlagStatus": "Flagged",
        "DueDateTime": {
            "DateTime": "2017-12-22T08:00:00.0000000",
            "TimeZone": "UTC"
        },
        "StartDateTime": {
            "DateTime": "2017-12-18T08:00:00.0000000",
            "TimeZone": "UTC"
        }
  }
}

示例请求

以下示例将以前已标记的联系人设置为 Complete。

PATCH https://outlook.office.com/api/beta/me/contacts/AAMkADlkAAARKMK7AAA=
Content-Type: application/json

{
  "Flag": {
    "CompletedDateTime":{
      "DateTime": "2018-02-05T18:00:00",
      "TimeZone": "Pacific Standard Time"
    },
    "FlagStatus": "Complete"
  }
}

示例响应

Status code: 200

{
  "@odata.context":"https://outlook.office365.com/api/beta/$metadata#Me/Contacts/$entity",
  "@odata.id":"https://outlook.office365.com/api/beta/Users('af183ae6-7efa-41e4-aa87-fe8790598625@9ac5b33f-49cf-45f7-9ef1-b581dce364d8')/Contacts('AAMkADlkAAARKMK7AAA=')",
  "@odata.etag":"W/\"EQAAABYAAADDii8zlkFETIcBiRn8yAbgAAARKpia\"",
  "Id":"AAMkADlkAAARKMK7AAA=",
  "CreatedDateTime":"2016-07-20T23:59:37Z",
  "LastModifiedDateTime":"2016-07-20T23:59:38Z",
  "ChangeKey":"EQAAABYAAABmngqUDhbeSLkRkXbBznTvAAEw/xwn",
  "Categories":[
  ],
  "ParentFolderId":"AAMkADlk8yAbgAAAAAAEOAAA=",
  "Birthday":"1974-07-22T00:00:00Z",
  "FileAs":"",
  "DisplayName":"Pavel Bansky",
  "GivenName":"Pavel",
  "Initials":null,
  "MiddleName":null,
  "NickName":null,
  "Surname":"Bansky",
  "Title":null,
  "YomiGivenName":null,
  "YomiSurname":null,
  "YomiCompanyName":null,
  "Generation":null,
  "EmailAddresses":[
    {
      "Name":"Pavel Bansky",
      "Address":"pavelb@contoso.onmicrosoft.com"
    }
  ],
  "Websites":[
  ],
  "ImAddresses":[
  ],
  "JobTitle":null,
  "CompanyName":null,
  "Department":null,
  "OfficeLocation":null,
  "Profession":null,
  "AssistantName":null,
  "Manager":null,
  "Phones":[
    {
      "Type":"Business",
      "Number":"+1 732 555 0102"
    }
  ],
  "PostalAddresses":[
    {
      "Type": "Business",
      "Street": "Some street",
      "City": "Seattle",
      "State": "WA",
      "PostalCode": "98121"
    }
  ],
  "SpouseName":null,
  "PersonalNotes":null,
  "Children":[
  ],
  "Gender":null,
  "IsFavorite":null,
  "Flag": {
    "FlagStatus": "Complete",
    "CompletedDateTime": {
        "DateTime": "2018-02-06T00:00:00.0000000",
        "TimeZone": "UTC"
    }
  }
}

响应类型

已更新的联系人。

删除联系人

删除联系人。已删除内容可能无法恢复。

若要了解详细信息，请参阅使用在 Exchange 中 EWS 删除项目。

删除联系人

删除联系人

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.readwrite
wl.contacts_create

DELETE https://outlook.office.com/api/beta/me/contacts/{contact_id}

必需的参数	类型	说明
URL 参数
contact_id	字符串	联系人 ID。

示例请求

DELETE https://outlook.office.com/api/beta/me/contacts/AAMkAGE0Myy2hAAA=

示例响应

Status code: 204

获取联系人文件夹

你可以获取联系人文件夹集合或获取联系人文件夹。

获取联系人文件夹集合
获取联系人文件夹

获取联系人文件夹集合

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic

在已登录用户的邮箱或特定的联系人文件夹获取所有联系人文件夹 (.../me/contactfolders)。

GET https://outlook.office.com/api/beta/me/contactfolders
GET https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}/childfolders

备注

请参阅用于筛选、排序和分页参数的 OData 查询参数。

必需的参数	类型	说明
URL 参数
contact_folder_id	字符串	联系人文件夹 ID，如果你正在从特定联系人文件夹中获取联系人文件夹。

示例请求

GET https://outlook.office.com/api/beta/me/contactfolders

示例响应

状态代码：200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/ContactFolders",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AAMkAGI2TKI5AAA=')",
            "Id": "AAMkAGI2TKI5AAA=",
            "ParentFolderId": "AAMkAGI2AAEOAAA=",
            "DisplayName": "Finance",
            "WellKnownName": null
        },
        {
            "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AQMkADA1MTgAAAA==')",
            "Id": "AQMkADA1MTgAAAA==",
            "ParentFolderId": "AAMkAGI2AAEOAAA=",
            "DisplayName": "Contacts",
            "WellKnownName": "contacts"
        }
    ]
}

响应类型

已请求的联系人文件夹集合。

获取联系人文件夹

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic

通过使用联系人文件夹 ID 获取联系人文件夹。

GET https://outlook.office.com/api/beta/me/contactfolders/{contact_folder_id}

备注

请参阅用于筛选、排序和分页参数的 OData 查询参数。

必需的参数	类型	说明
URL 参数
contact_folder_id	字符串	联系人文件夹 ID。

示例请求

GET https://outlook.office.com/api/beta/me/contactfolders/AAMkAGI2TKI5AAA=

示例响应

状态代码：200

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/ContactFolders/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AAMkAGI2TKI5AAA=')",
    "Id": "AAMkAGI2TKI5AAA=",
    "ParentFolderId": "AAMkAGI2AAEOAAA=",
    "DisplayName": "Finance",
    "WellKnownName": null
}

响应类型

已请求的联系人文件夹。

获取联系人照片

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic

获取指定的登录用户联系人的照片。

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')/photo/$value

必需的参数	类型	说明
URL 参数
contact_id	字符串	该 ID 指定登录用户的特定联系人。

示例请求

GET https://outlook.office.com/api/beta/me/contacts('AAMkAGE1M2IyNGNm===')/photo/$value
Content-Type: image/jpg

响应数据

包含所请求照片的二进制数据。HTTP 响应代码为 200。

如果联系人在 Exchange Online 上尚未具有联系人照片，该操作将返回 HTTP 404。

获取联系人照片元数据

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.read
wl.basic

获取联系人照片的元数据，其中包括以像素为单位的内容类型、宽度和高度。

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')/photo

必需的参数	类型	说明
URL 参数
contact_id	字符串	该 ID 指定登录用户的特定联系人。

示例请求

GET https://outlook.office.com/api/beta/me/contacts('AAMkAGE1M2IyNGNm')/photo

示例响应数据

成功的请求会返回 HTTP 200。

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Contacts('AAMkAGE1M2IyNGNm')/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-b826-40d7-b48b-57002df800e5@1717622f-49d1-4d0c-9d74-709fad664b77')/contacts('AAMkAGE1M2IyNGNm')/photo",
    "@odata.readLink": "https://outlook.office.com/api/beta/Users('ddfcd489-b826-40d7-b48b-57002df800e5@1717622f-49d1-4d0c-9d74-709fad664b77')/contacts('AAMkAGE1M2IyNGNm')/photo",
    "@odata.mediaContentType": "image/jpeg",
    "Id": "103X77",
    "Width": 103,
    "Height": 77
}

设置联系人照片

最低要求的范围

以下各项之一：

https://outlook.office.com/contacts.readwrite
wl.contacts_create

将照片分配给指定的登录用户的联系人。照片应为二进制。它将替换该该联系人的现有照片。

在测试版中仅使用 PUT 进行此操作。

PUT https://outlook.office.com/api/beta/me/contacts('{contact_id}')/photo/$value

必需的参数	类型	说明
URL 参数
contact_id	字符串	该 ID 指定登录用户的特定联系人。

示例请求

PUT https://outlook.office.com/api/beta/me/contacts('AAMkAGE1M2IyNGNm===')/photo/$value
Content-Type: image/jpeg

在请求正文中包括照片的二进制数据。

响应数据

成功的请求会返回 HTTP 200。

后续步骤

无论你准备开始构建应用还是只想了解更多信息，我们都已为你考虑周全。

开始使用邮件、日历和联系人 REST API。
想要查看一些示例吗？我们就有。

或者，了解有关使用 Office 365 平台的更多信息：

Outlook 联系人 REST API 参考（测试版）

所有联系人 API 操作

联系人的操作

联系人文件夹操作

联系人照片操作

另请参阅

使用联系人 REST API

身份验证

API 版本

目标用户

获取联系人

最低要求的范围

获取联系人集合

示例请求

示例响应

响应类型

获取联系人

最低要求的范围

响应类型

示例请求

示例响应

示例请求

示例响应

同步联系人和联系人文件夹

最低要求的范围

响应类型

示例

创建联系人

创建联系人

最低要求的范围

示例请求

示例响应

响应类型

更新联系人

更新联系人

最低要求的范围

示例请求

示例响应

示例请求

示例响应

响应类型

删除联系人

删除联系人

最低要求的范围

示例请求

示例响应

获取联系人文件夹

获取联系人文件夹集合

最低要求的范围

示例请求

示例响应

响应类型

获取联系人文件夹

最低要求的范围

示例请求

示例响应

响应类型

获取联系人照片和元数据

获取联系人照片

最低要求的范围

示例请求

响应数据

获取联系人照片元数据

最低要求的范围

示例请求

示例响应数据

设置联系人照片

最低要求的范围

示例请求

响应数据

后续步骤

其他资源