Outlook 联系人 REST API 引用 （版本 1.0）

适用于： Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

备注

Outlook REST API 的版本 1.0 正被弃用。 自 2018 年 11 月 1 日开始，应用将无法再在 v1.0 REST 端点上使用基本身份验证。 截止到 2019 年 11 月 1 日，1.0 版 REST 端点将完全停用，并且 1.0 版文档将在不久之后移除。 请开始迁移你的应用，以便在 Microsoft Graph 1.0 版中使用 Outlook REST API。 更多详情，请参阅我们的通知。

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

备注

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

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

所有“联系人 API”操作

联系人的操作

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

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

联系人文件夹操作

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

• 获取联系人文件夹

联系人照片操作

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

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

另请参阅

• REST API 联系人资源
• REST 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/v1.0/me/contacts
GET https://outlook.office.com/api/v1.0/me/contactfolders/{contact_folder_id}/contacts

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

备注

默认情况下，响应中的每个联系人都包含其所有属性。 使用 $select 只指定那些你需要的最佳性能的属性。 始终返回该 ID 属性。 请参阅 OData 查询参数了解筛选、排序和分页参数。

以下示例显示如何使用 $select 指定只返回 EmailAddresses、GivenName 和 Surname 响应中每个联系人的属性。 如果不使用 $select，那请参阅 $select 中的示例回复，查找可以为联系人返回属性的完整列表。

示例请求

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

示例响应

状态代码：200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa6\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk2AAA=",
            "GivenName": "Pavel",
            "Surname": "Bansky",
            "EmailAddresses": [
                {
                    "Name": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa5\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk1AAA=",
            "GivenName": "Katie",
            "Surname": "Jordan",
            "EmailAddresses": [
                {
                    "Name": "katiej@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk0AAA=",
            "GivenName": "Garth",
            "Surname": "Fort",
            "EmailAddresses": [
                {
                    "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=",
            "GivenName": "Janet",
            "Surname": "Schorr",
            "EmailAddresses": [
                {
                    "Name": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        }
    ]
}
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa6\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk2AAA=",
            "GivenName": "Pavel",
            "Surname": "Bansky",
            "EmailAddresses": [
                {
                    "Name": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa5\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk1AAA=",
            "GivenName": "Katie",
            "Surname": "Jordan",
            "EmailAddresses": [
                {
                    "Name": "katiej@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk0AAA=",
            "GivenName": "Garth",
            "Surname": "Fort",
            "EmailAddresses": [
                {
                    "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=",
            "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/{version}/me/contacts/{contact_id}

必需的参数	类型	说明
URL 参数
version	string	该 API 的版本。
contact_id	string	联系人 ID。

示例请求

GET https://outlook.office.com/api/v1.0/me/contacts/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop

示例响应

状态代码：200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts/$entity",
    "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHk0AAA=",
    "DateTimeCreated": "2014-10-19T23:08:24Z",
    "DateTimeLastModified": "2014-10-19T23:08:24Z",
    "ChangeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4",
    "Categories": [],
    "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
    "Birthday": null,
    "FileAs": "Fort, Garth",
    "DisplayName": "Garth Fort",
    "GivenName": "Garth",
    "Initials": null,
    "MiddleName": null,
    "NickName": null,
    "Surname": "Fort",
    "Title": null,
    "YomiGivenName": null,
    "YomiSurname": null,
    "YomiCompanyName": null,
    "Generation": null,
    "EmailAddresses": [
        {
            "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
            "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
        }
    ],
    "ImAddresses": [
        "sip:garthf@a830edad9050849nda1.onmicrosoft.com"
    ],
    "JobTitle": "Web Marketing Manager",
    "CompanyName": null,
    "Department": "Sales & Marketing",
    "OfficeLocation": "20/1101",
    "Profession": null,
    "BusinessHomePage": null,
    "AssistantName": null,
    "Manager": null,
    "HomePhones": [],
    "MobilePhone1": null,
    "BusinessPhones": [
        "+1 918 555 0101"
    ],
    "HomeAddress": {},
    "BusinessAddress": {},
    "OtherAddress": {},
    "SpouseName": null,
    "PersonalNotes": null,
    "Children": []
}

响应类型

请求的 联系人。

备注

默认情况下，响应包含联系人的所有属性。 使用 $select 只指定那些你需要的最佳性能的属性。 始终返回该 ID 属性。 请参阅 OData 查询参数了解筛选、排序和分页参数。

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

示例请求

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

示例响应

状态代码：200

{
    "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkAGI2THk0AAA=",
    "GivenName": "Garth",
    "Surname": "Fort",
    "EmailAddresses": [
        {
            "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
            "Address": "garthf@a830edad9050849NDA1.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/v1.0/me/Contacts
GET https://outlook.office.com/api/v1.0/me/ContactFolders/{folderName}

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

响应类型

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

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

备注

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

示例

完全同步的初始请求：

GET https://outlook.office.com/api/v1.0/Me/Contacts

包括以下标头：

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

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

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

包括以下标头：

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

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

标头

Preference-Applied: odata.track-changes

正文

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

有效负载消息

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

标头

Preference-Applied: odata.track-changes

正文

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

有效负载消息

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

https://outlook.office.com/api/v1.0/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/v1.0/me/contacts
POST https://outlook.office.com/api/v1.0/me/contactfolders/{contact_folder_id}/contacts

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

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

示例请求

POST https://outlook.office.com/api/v1.0/me/contacts

Content-Type: application/json

{
  "GivenName": "Pavel",
  "Surname": "Bansky",
  "EmailAddresses": [
    {
      "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "Pavel Bansky"
    }
  ],
  "BusinessPhones": [
    "+1 732 555 0102"
  ]
}

示例响应

状态代码：201

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"EQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAV41eC\"",
  "Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEOAAAmP1Ln1wcHRariNdTMGAO9AAAV4xqVAAA=",
  "ChangeKey": "EQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAV41eC",
  "Categories": [],
  "DateTimeCreated": "2014-10-22T20:38:18Z",
  "DateTimeLastModified": "2014-10-22T20:38:19Z",
  "ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEOAAA=",
  "Birthday": null,
  "FileAs": "",
  "DisplayName": "Pavel Bansky",
  "GivenName": "Pavel",
  "Initials": null,
  "MiddleName": null,
  "NickName": null,
  "Surname": "Bansky",
  "Title": null,
  "Generation": null,
  "EmailAddresses": [
    {
      "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "Pavel Bansky"
    },
    null,
    null
  ],
  "ImAddresses": [
    null,
    null,
    null
  ],
  "JobTitle": null,
  "CompanyName": null,
  "Department": null,
  "OfficeLocation": null,
  "Profession": null,
  "BusinessHomePage": null,
  "AssistantName": null,
  "Manager": null,
  "HomePhones": [
    null,
    null
  ],
  "BusinessPhones": [
    "+1 732 555 0102",
    null
  ],
  "MobilePhone1": null,
  "HomeAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "BusinessAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "OtherAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "YomiSurname": null,
  "YomiGivenName": null,
  "YomiCompanyName": null
}

响应类型

新 联系人。

更新联系人

更改联系人的属性。

• 更新联系人

更新联系人

最低要求的范围

以下各项之一：

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

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

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

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

示例请求

PATCH https://outlook.office.com/api/v1.0/me/contacts/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=

Content-Type: application/json

{
  "HomeAddress": {
    "Street": "Some street",
    "City": "Seattle",
    "State": "WA",
    "PostalCode": "98121"
  },
  "Birthday": "1974-07-22"
}

示例响应

状态代码：200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Contacts/$entity",
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEOAACd9nJ-tVysQos2hTfspaWRAAADTHkzAAA=",
  "ChangeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3",
  "Categories": [],
  "DateTimeCreated": "2014-10-19T23:08:18Z",
  "DateTimeLastModified": "2014-10-19T23:08:18Z",
  "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
  "Birthday": "1974-07-22T00:00:00Z",
  "FileAs": "Schorr, Janet",
  "DisplayName": "Janet Schorr",
  "GivenName": "Janet",
  "Initials": null,
  "MiddleName": null,
  "NickName": null,
  "Surname": "Schorr",
  "Title": null,
  "Generation": null,
  "EmailAddresses": [
    {
      "Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "janets@a830edad9050849NDA1.onmicrosoft.com"
    },
    null,
    null
  ],
  "ImAddresses": [
    "sip:janets@a830edad9050849nda1.onmicrosoft.com",
    null,
    null
  ],
  "JobTitle": "Product Marketing Manager",
  "CompanyName": null,
  "Department": "Sales & Marketing",
  "OfficeLocation": "18/2111",
  "Profession": null,
  "BusinessHomePage": null,
  "AssistantName": null,
  "Manager": null,
  "HomePhones": [
    null,
    null
  ],
  "BusinessPhones": [
    "+1 425 555 0109",
    null
  ],
  "MobilePhone1": null,
  "HomeAddress": {
    "Street": "Some street",
    "City": "Seattle",
    "State": "WA",
    "CountryOrRegion": null,
    "PostalCode": "98121"
  },
  "BusinessAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "OtherAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "YomiSurname": null,
  "YomiGivenName": null,
  "YomiCompanyName": null
}

响应类型

已更新的 联系人。

删除联系人

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

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

• 删除联系人

删除联系人

最低要求的范围

以下各项之一：

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

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

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

示例请求

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

示例响应

Status code: 204

获取联系人文件夹

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

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

获取联系人文件夹集合

最低要求的范围

以下各项之一：

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

在已登录用户 (.../me/contactfolders) 的默认联系人文件夹或特定联系人文件夹下获取联系人文件夹集合。

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

备注

请参阅 OData 查询参数了解筛选、排序和分页参数。

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

示例请求

GET https://outlook.office.com/api/v1.0/me/contactfolders

示例响应

状态代码：200

{
  "@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/ContactFolders",
  "value": [
    {
      "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
      "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAADTKI5AAA=",
      "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
      "DisplayName": "Finance"
    }
  ]
}

响应类型

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

获取联系人文件夹

最低要求的范围

以下各项之一：

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

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

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

备注

请参阅 OData 查询参数了解筛选、排序和分页参数。

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

示例请求

GET https://outlook.office.com/api/v1.0/me/contactfolders/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAADTKI5AAA=

示例响应

状态代码：200

{
  "@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
  "Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAADTKI5AAA=",
  "ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEOAAA=",
  "DisplayName": "Finance"
}

响应类型

已请求的 联系人文件夹。

获取联系人照片和元数据

这个功能在 v2.0 和测试版本中可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。

设置联系人照片

这个功能在 v2.0 和测试版本中可用。 要了解详细信息，在左侧的目录转到 Office 365 REST API 引用部分，并选择以下版本之一。

后续步骤

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

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

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

• Outlook 开发人员中心的 Outlook REST API
• Office 365 平台开发概述
• Office 365 应用验证和资源授权
• 将应用手动注册到 Azure AD，以便访问 Office 365 API
• 邮件 API 参考
• 日历 API 参考
• 任务 REST API
• OneDrive API
• 发现服务 REST API 操作参考
• 邮件、日历、联系人和任务 REST APIs 的资源参考