Outlook 用户照片 REST API 参考（试用版）
适用于： Exchange Online | Office 365
备注
本文档涵盖了试用版用户照片 API 的预览。 预览功能在最终确定之前可能会发生变化，并可能会让使用它们的代码无法正常运行。 正因为如此，一般而言，生产代码中只应使用生产版本的 API。 如果可用，2.0 版目前是首选版本。
用户照片 API 可下载或设置用户的照片，这类用户的邮箱由 Office 365 上的 Azure Active Directory 提供安全保护。
备注
用户照片 API 不支持 Microsoft 帐户域中的消费类邮箱，例如 Hotmail.com、Live.com、MSN.com、Outlook.com 和 Passport.com。
对 API 的 beta 版本不感兴趣？ 在左侧的目录中，转到 Office 365 REST API 参考部分，然后选择所需的版本。
使用用户照片 REST API
身份验证
与其他 Outlook REST API 一样，对于 Outlook 用户照片 API 的每个请求，都应该包含有效的访问令牌。 获取访问令牌需要注册和识别应用，并获得相应的授权。
你可以了解更多有关简化注册和授权选项的信息。 在用户照片 API 中继续执行特定操作时，请记住这一点。
API 版本
此 API 已从预览升级到正式发布 (GA) 状态。 它在 Outlook REST API 的 2.0 和 beta 版本中得到支持。
目标用户
目标用户可以是登录用户，也可以是用户 ID 指定的用户。
有关使用此 API 的更多信息以及 Outlook REST API 所有子集的通用信息，请参阅使用 Outlook REST API。
用户照片操作
用户照片操作可让你获取二进制格式的用户照片元数据和照片流，并设置用户照片。
除单张照片外，用户照片 API 还提供了一个处于预览状态的照片集（但仅在 beta 版本中提供）。 该照片集可让你指定自己感兴趣的特定照片尺寸。
获取照片元数据
获取所请求的用户照片的信息，其中包括内容类型、电子标签以及以像素为单位的宽度和高度。
所需范围
使用以下范围之一获取指定用户的照片元数据，这些指定用户可以是登录用户：
- user.readbasic.all
- user.read.all
- user.readwrite.all
还可以使用以下范围来获取特定登录用户的照片元数据：
- user.read
获取最大可用照片的元数据
GET https://outlook.office.com/api/beta/me/photo
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo
获取所有可用照片尺寸的元数据
GET https://outlook.office.com/api/beta/me/photos
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos
获取指定照片尺寸的元数据
GET https://outlook.office.com/api/beta/me/photos('{size}')
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')
| 可选参数 | 类型 | 说明 |
|---|---|---|
| Url 参数 | ||
| user_id | string | 用户的电子邮件地址。 |
| size | string | 照片尺寸。 如果照片在 Active Directory 和邮箱中均不存在，则会自动生成 '1x1' 的值。 如果照片存储在邮箱中，则预定义的尺寸为：'48x48'、'64x64'、'96x96'、'120x120'、'240x240'、'360x360'、'432x432'、'504x504' 和 '648x648'。 如果用户没有上传足够大的照片，则仅可用较小的预定义尺寸表示的尺寸可用。 例如，如果用户上传像素为 504x504 的照片，除 648x648 外所有尺寸的照片都可供下载。 如果照片存储在 Azure Active Directory 中，则可以使用任何尺寸。 |
示例请求
请求为登录用户获取 240x240 像素图像的元数据。
GET https://outlook.office.com/api/beta/me/photos('240x240')
示例响应数据
以下响应数据显示照片元数据。 HTTP 响应代码是 200。
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/photo/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/photo",
"@odata.mediaContentType": "image/jpeg",
"@odata.mediaEtag": "\"BA09D118\"",
"Id": "240X240",
"Width": 240,
"Height": 240
}
以下响应数据显示了尚未为用户上传照片时的响应内容。 HTTP 响应代码是 200。
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/photo/$entity",
"@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/photo",
"@odata.mediaContentType": "image/gif",
"@odata.mediaEtag": "",
"Id": "1X1",
"Width": 1,
"Height": 1
}
获取照片
获取指定用户的用户照片。
此操作允许租户管理员让应用程序获取租户中任何用户的用户照片。
所需范围
使用以下范围之一获取指定用户的照片元数据，这些指定用户可以是登录用户：
- user.readbasic.all
- user.read.all
- user.readwrite.all
你还可以使用以下范围来获取特定登录用户的照片：
- user.read
- user.readwrite
获取最大的可用尺寸
GET https://outlook.office.com/api/beta/me/photo/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo/$value
获取特定尺寸的照片
GET https://outlook.office.com/api/beta/me/photos('{size}')/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')/$value
| 可选参数 | 类型 | 说明 |
|---|---|---|
| Url 参数 | ||
| user_id | string | 用户的电子邮件地址。 |
| size | string | 照片尺寸。 如果照片在 Active Directory 和邮箱中均不存在，则会自动生成 '1x1' 的值。 如果照片存储在邮箱中，则预定义的尺寸为：'48x48'、'64x64'、'96x96'、'120x120'、'240x240'、'360x360'、'432x432'、'504x504' 和 '648x648'。 如果用户没有上传足够大的照片，则仅可用较小的预定义尺寸表示的尺寸可用。 例如，如果用户上传像素为 504x504 的照片，除 648x648 外所有尺寸的照片都可供下载。 如果照片存储在 Azure Active Directory 中，则可以使用任何尺寸。 |
示例请求
此请求获取已登录用户的照片。
GET https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpg
响应数据
包含所请求照片的二进制数据。HTTP 响应代码为 200。
设置用户照片
将照片分配给指定的用户。 照片应为二进制。 它会替换该用户的任何现有照片。
此操作允许租户管理员让应用程序设置租户中任何用户的用户照片。 在测试版中仅使用 PUT 进行此操作。
所需范围
使用以下范围设置指定用户的照片，该用户可以是承租人中的任何用户或已登录用户：
- user.readwrite.all
你还可以使用以下范围来设置特定登录用户的照片：
- user.readwrite
PUT https://outlook.office.com/api/beta/me/photo/$value
PUT https://outlook.office.com/api/beta/users('{user_id}')/photo/$value
| 可选参数 | 类型 | 说明 |
|---|---|---|
| Url 参数 | ||
| user_id | string | 用户的电子邮件地址。 |
示例请求
PUT https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpeg
包括请求正文中照片的二进制数据。
响应数据
成功的请求会返回 HTTP 200。
后续步骤
无论你准备开始构建应用还是只想了解更多信息，我们都已为你考虑周全。
- 开始使用邮件、日历和联系人 REST API。
- 想要查看一些示例吗？ 我们就有。
或者，了解有关使用 Office 365 平台的更多信息：