Outlook ユーザー写真 REST API リファレンス
適用対象: Exchange Online | Office 365
注意
このドキュメントは、プレビュー版に含まれるユーザー写真 API のベータ版について説明しますプレビュー機能は、最終版までに変更される場合があり、それらの機能を使用するコードが動作しなくなる場合もあります。このため、一般に、運用コードでは運用バージョンの API のみを使用してください。入手可能な場合、現時点では v2.0 が優先バージョンです。
ユーザー写真 API を使用すると、Azure Active Directory によってセキュリティ保護されているメールボックスを所有する Office 365 のユーザーの写真をダウンロードしたり、設定したりすることができます。
注意
注 ユーザー写真 API は Hotmail.com、Live.com、MSN.com、Outlook.com、Passport.com など、Microsoft のアカウント ドメインの消費者のメールボックスをサポートしていません。
ベータ版の API が不要な場合 左の目次で、Office 365 REST API リファレンス セクションに移動し、使用したいバージョンを選択します。
ユーザー写真 REST API の使用
認証
その他の Outlook REST API と同様に、Outlook ユーザー写真 API へのすべての要求には、有効なアクセス トークンを含める必要があります。 アクセス トークンを取得するには、アプリを登録して識別し、適切な承認を取得する必要があります。
効率化された登録と承認のオプションに関する詳細情報を参照してください。 ユーザー写真 API で特定の操作を続行する際には、この点に留意してください。
API のバージョン
この API は、プレビューから一般提供 (GA) の状態にレベル上げされています。Outlook REST API の v2.0 とベータのバージョンでサポートされます。
対象ユーザー
対象ユーザーは、サインインしているユーザー、またはユーザー ID で指定されているユーザーになります。
この API の使用方法の詳細について、および Outlook REST API のすべてのサブセットに共通する情報については、「Outlook REST API の使用」を参照してください。
ユーザー写真の操作
ユーザー写真の操作を使用すると、ユーザーの写真のメタデータとフォト ストリームをバイナリ形式で取得したり、ユーザー写真を設定したりできます。
ユーザー写真 API には、photo エンティティに加えて、ベータ版でのみ使用可能なプレビューの photos コレクションもあります。photos コレクションを使用すると、関心のあるユーザー写真について具体的なサイズを指示できます。
写真のメタデータを取得する
要求したユーザー写真に関する情報 (コンテンツ タイプ、eTag、ピクセル単位の幅と高さなど) を取得します。
必須スコープ
指定したユーザー (サインインしているユーザーであってもかまいません) の写真のメタデータを取得するには、次のいずれかのスコープを使用します。
- 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 | 文字列 | ユーザーの電子メール アドレスです。 |
| サイズ | 文字列 | 写真のサイズ。値 '1 x 1' は、Active Directory とメールボックスのどちらにも写真が存在しない場合に自動的に生成されます。 写真がメールボックスに格納されている場合の事前定義済みサイズは、'48x48'、'64x64'、'96x96'、'120x120'、'240x240'、'360x360'、'432x432'、'504x504'、'648x648' です。ユーザーがアップロードした写真が大きくない場合は、それよりも小さい事前定義済みサイズで表現できるサイズのみがダウンロード可能になります。たとえば、アップロードした写真が 504x504 ピクセルの場合は、648×648 を除くすべてのサイズの写真がダウンロード可能になります。 写真が 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 | 文字列 | ユーザーの電子メール アドレスです。 |
| サイズ | 文字列 | 写真のサイズ。値 '1 x 1' は、Active Directory とメールボックスのどちらにも写真が存在しない場合に自動的に生成されます。 写真がメールボックスに格納されている場合の事前定義済みサイズは、'48x48'、'64x64'、'96x96'、'120x120'、'240x240'、'360x360'、'432x432'、'504x504'、'648x648' です。ユーザーがアップロードした写真が大きくない場合は、それよりも小さい事前定義済みサイズで表現できるサイズのみがダウンロード可能になります。たとえば、アップロードした写真が 504x504 ピクセルの場合は、648×648 を除くすべてのサイズの写真がダウンロード可能になります。 写真が 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 | 文字列 | ユーザーの電子メール アドレスです。 |
要求のサンプル
PUT https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpeg
要求の本文に、写真のバイナリ データを含めます。
応答データ
成功した要求は、HTTP 200 を返します。
次の手順
アプリケーション開発を開始する準備ができている方にも、単に詳しい情報を必要としている方にも、最適なコンテンツをご用意しています。
- メール、予定表、および連絡先 REST API の使用を開始します。
- サンプルについては、こちらをご覧ください。
Office 365 プラットフォームの使い方の詳細については、次のリンク先をご覧ください。