Outlook Benutzerfoto-REST-API-Referenz (Beta)
Gilt für: Exchange Online | Office 365
Hinweis
Diese Dokumentation behandelt die Beta-Version der Benutzerfoto-API in der Vorschau. Die Features der Vorschauversion können vor der Fertigstellung geändert werden und können den Code, der sie verwendet, unterbrechen. Aus diesem Grund sollten Sie in der Regel nur eine Produktionsversion einer API in Ihrem Produktionscode verwenden. Falls verfügbar, ist v2.0 derzeit die bevorzugte Version.
Mit der Benutzerfoto-API können Sie das Foto eines Benutzers herunterladen oder einstellen, dessen Postfach durch Azure Active Directory auf Office 365 gesichert ist.
Hinweis
Die Benutzerfoto-API unterstützt keine Postfächer für Endverbraucher in Microsoft-Konto-Domänen wie Hotmail.com, Live.com, MSN.com, Outlook.com und Passport.com.
Sie interessieren sich nicht für die Beta-Version der API? Wechseln Sie im Inhaltsverzeichnis auf der linken Seite zu Office 365 REST API-Referenz und wählen Sie die gewünschte Version aus.
Verwendung der Benutzerfoto-REST-API
Authentifizierung
Wie andere Outlook-REST-API sollten Sie für jede Anforderung an die Outlook-Benutzerfoto-API ein gültiges Zugriffstoken angeben. Sie müssen Ihre App registriert und identifiziert haben und die entsprechende Autorisierung erhalten haben, ein Zugriffstoken abzurufen.
Sie können mehr über einige optimierte Registrierungs- und Autorisierungsoptionen für Sie herausfinden. Beachten Sie dies, wenn Sie mit den spezifischen Operationen in der Benutzerfoto-API fortfahren.
Version der API
Diese API wurde von der Vorschauversion auf den Status Allgemeine Verfügbarkeit (GA) befördert. Sie wird in den v2.0 und Beta-Versionen der Outlook-REST-API unterstützt.
Ziel-Benutzer
Der Ziel-Benutzer kann der angemeldete Benutzer oder ein durch eine Benutzer-ID angegebener Benutzer sein.
Weitere Informationen zur Verwendung dieser API und Informationen, die allen Untergruppen der Outlook-REST-API gemeinsam sind, finden Sie unter Verwendung der Outlook-REST-API.
Benutzerfoto-Operationen
Mit den Benutzerfoto-Operationen können Sie die Foto-Metadaten und den Foto-Stream eines Benutzers im Binärformat abrufen und das Benutzerfoto einstellen.
Zusätzlich zur Foto-Entität bietet die Benutzerfoto-API eine Foto-Sammlung, die nur in der Beta-Version verfügbar ist. Die Foto-Sammlung erlaubt es Ihnen, bestimmte Größen für das Benutzerfoto anzugeben, das Sie interessiert.
Foto-Metadaten abrufen
Erhalten Sie Informationen über das gewünschte Benutzerfoto, das den Inhaltstyp, den eTag sowie die Breite und Höhe in Pixeln enthält.
Erforderlicher Bereich
Verwenden Sie einen der folgenden Bereiche, um Foto-Metadaten des angegebenen Benutzers zu erhalten, der der angemeldete Benutzer sein kann:
- user.readbasic.all
- user.read.all
- user.readwrite.all
Sie können auch den folgenden Bereich verwenden, um Foto-Metadaten speziell des angemeldeten Benutzers zu erhalten:
- user.read
Rufen Sie die Metadaten für das größte verfügbare Foto ab
GET https://outlook.office.com/api/beta/me/photo
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo
Rufen Sie die Metadaten für alle verfügbaren Bildgrößen ab
GET https://outlook.office.com/api/beta/me/photos
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos
Metadaten für eine bestimmte Fotogröße abrufen
GET https://outlook.office.com/api/beta/me/photos('{size}')
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')
| Optionaler Parameter | Typ | Beschreibung |
|---|---|---|
| URL-Parameter | ||
| user_id | Zeichenfolge | Die E-Mail-Adresse des Benutzers. |
| size | Zeichenfolge | Eine Fotogröße. Der Wert von '1x1' wird automatisch generiert, falls ein Foto nicht sowohl im Active Directory als auch im Postfach vorhanden ist. Wenn das Foto im Postfach gespeichert ist, dann sind es die vordefinierten Größen: '48x48', 64x64', 96x96', 120x120', 240x240', 360x360', 432x432', 504x504' und '648x648'. Wenn der Benutzer ein Foto nicht groß genug hochlädt, stehen nur die Größen zur Verfügung, die durch die kleineren vordefinierten Größen dargestellt werden können. Wenn der Benutzer beispielsweise ein Foto mit 504x504 Pixeln hochlädt, sind alle Fotogrößen bis auf 648x648 zum Download verfügbar. Fotos können eine beliebige Größe aufweisen, wenn sie in Active Directory gespeichert sind. |
Beispielanfrage
Diese Anfrage liefert die Metadaten für ein 240x240 Pixel großes Bild für den angemeldeten Benutzer.
GET https://outlook.office.com/api/beta/me/photos('240x240')
Daten der Beispielantwort
Die folgenden Antwortdaten zeigen die Foto-Metadaten. Der HTTP-Antwort-Code ist 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
}
Die folgenden Antwortdaten zeigen den Inhalt einer Antwort, wenn noch kein Foto für den Benutzer hochgeladen wurde. Der HTTP-Antwort-Code ist 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
}
Foto abrufen
Rufen Sie das Benutzerfoto des angegebenen Benutzers ab.
Dieser Vorgang ermöglicht es einem Mandanten-Administrator, einer App den Abruf eines Benutzerfotos eines beliebigen Nutzers im Mandanten zu ermöglichen.
Erforderlicher Bereich
Verwenden Sie einen der folgenden Bereiche, um das Foto des angegebenen Benutzers zu erhalten, der der angemeldete Benutzer sein kann:
- user.readbasic.all
- user.read.all
- user.readwrite.all
Sie können auch den folgenden Bereich verwenden, um das Foto speziell des angemeldeten Benutzers zu erhalten:
- user.read
- user.readwrite
Rufen Sie die größte verfügbare Größe ab
GET https://outlook.office.com/api/beta/me/photo/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo/$value
Rufen Sie das Foto in einer bestimmten Größe ab
GET https://outlook.office.com/api/beta/me/photos('{size}')/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')/$value
| Optionaler Parameter | Typ | Beschreibung |
|---|---|---|
| URL-Parameter | ||
| user_id | Zeichenfolge | Die E-Mail-Adresse des Benutzers. |
| size | Zeichenfolge | Eine Fotogröße. Der Wert von '1x1' wird automatisch generiert, falls ein Foto nicht sowohl im Active Directory als auch im Postfach vorhanden ist. Wenn das Foto im Postfach gespeichert ist, dann sind es die vordefinierten Größen: '48x48', 64x64', 96x96', 120x120', 240x240', 360x360', 432x432', 504x504' und '648x648'. Wenn der Benutzer ein Foto nicht groß genug hochlädt, stehen nur die Größen zur Verfügung, die durch die kleineren vordefinierten Größen dargestellt werden können. Wenn der Benutzer beispielsweise ein Foto mit 504x504 Pixeln hochlädt, sind alle Fotogrößen bis auf 648x648 zum Download verfügbar. Fotos können eine beliebige Größe aufweisen, wenn sie in Active Directory gespeichert sind. |
Beispielanfrage
Diese Anforderung ruft das Foto für den angemeldeten Benutzer ab.
GET https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpg
Antwortdaten
Enthält die binären Daten des angeforderten Fotos. Der HTTP-Antwortcode ist 200.
Benutzerfoto einstellen
Weisen Sie dem angegebenen Benutzer ein Foto zu. Das Foto sollte binär sein. Es ersetzt jedes vorhandene Foto für diesen Benutzer.
Dieser Vorgang ermöglicht es einem Mandanten-Administrator, einer App den Abruf eines Benutzerfotos eines beliebigen Nutzers im Mandanten zu ermöglichen. Verwenden Sie für diesen Vorgang nur PUT in der Betaversion.
Erforderlicher Bereich
Verwenden Sie den folgenden Bereich, um das Foto des angegebenen Benutzers einzustellen, der ein beliebiger Benutzer des Mandanten oder des angemeldeten Benutzers sein kann:
- user.readwrite.all
Sie können auch den folgenden Bereich verwenden, um das Foto speziell des angemeldeten Benutzers einzustellen:
- user.readwrite
PUT https://outlook.office.com/api/beta/me/photo/$value
PUT https://outlook.office.com/api/beta/users('{user_id}')/photo/$value
| Optionaler Parameter | Typ | Beschreibung |
|---|---|---|
| URL-Parameter | ||
| user_id | Zeichenfolge | Die E-Mail-Adresse des Benutzers. |
Beispielanfrage
PUT https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpeg
Fügen Sie die Binärdaten des Fotos in den Text der Anfrage ein.
Antwortdaten
Eine erfolgreiche Anforderung gibt HTTP 200 zurück.
Nächste Schritte
Egal, ob Sie bereit sind, eine App zu erstellen oder einfach nur mehr darüber erfahren möchten, wir haben alles im Griff.
- Beginnen Sie mit den E-Mail-, Kalender- und Kontakte-REST-APIs.
- Möchten Sie Beispiele sehen? Wir haben sie.
Oder erfahren Sie mehr über die Verwendung der Office 365-Plattform: