Referência da API REST da Foto do Usuário do Outlook
Aplica-se ao: Exchange Online | Office 365
Observação
Esta documentação cobre a versão beta da API da Foto do Usuário em versão prévia. Os recursos de versão prévia estão sujeitos a alterações antes da finalização e podem fazer com que seu código deixe de funcionar. Por essa razão, em geral, você deve usar somente uma versão de produção de uma API em seu código de produção. Se disponível, a versão v2.0 é a preferida no momento.
A API da Foto do Usuário permite baixar ou definir a foto de um usuário cuja caixa de correio esteja protegida pelo Active Directory do Azure no Office 365.
Observação
A API da Foto do Usuário não oferece suporte a caixas de correio de cliente em domínios de conta da Microsoft, como Hotmail.com, Live.com, MSN.com, Outlook.com e Passport.com.
Tem interesse na versão beta da API? No tabela de conteúdo à esquerda, vá para a seção Referência da API REST do Office 365 e selecione a versão desejada.
Como usar a API REST da Foto do Usuário
Autenticação
Como outra API REST do Outlook, você deve incluir um token de acesso válido a cada solicitação à API da Foto do Usuário do Outlook. A obtenção de um token de acesso exige que você registre e identifique seu aplicativo e obtenha a autorização adequada.
Saiba mais sobre algumas opções simplificadas de registro e autorização para você. Tenha isso em mente ao prosseguir com as operações específicas na API da Foto do Usuário.
Versão da API
Essa API foi promovida da versão prévia para o status de Disponibilidade Geral (GA). Há suporte nas versões v2.0 e beta da API REST do Outlook.
Usuário de destino
O usuário de destino pode ser o usuário conectado ou um usuário especificado por uma identificação do usuário.
Para obter mais informações sobre como usar essa API e informações comuns a todos os subconjuntos da API REST do Outlook, consulte Usar a API REST do Outlook.
Operações de foto do usuário
As operações de foto do usuário permitem que você obtenha os metadados e o fluxo da foto de um usuário em formato binário e defina a foto do usuário.
Além da entidade foto, a API da Foto do Usuário fornece uma coleção de fotos que está em versão prévia e disponível apenas na versão beta. A coleção de fotos permite indicar tamanhos específicos da foto do usuário de interesse.
Obter metadados da foto
Obtenha informações sobre a foto do usuário solicitada, incluindo tipo de conteúdo, eTag, e largura e altura em pixels.
Escopo requerido
Use um dos escopos a seguir para obter metadados da foto do usuário especificado, que pode ser o usuário conectado:
- user.readbasic.all
- user.read.all
- user.readwrite.all
Também é possível usar o escopo a seguir para obter metadados da foto especificamente do usuário conectado:
- user.read
Obter os metadados da maior foto disponível
GET https://outlook.office.com/api/beta/me/photo
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo
Obter os metadados de todos os tamanhos disponíveis de fotos
GET https://outlook.office.com/api/beta/me/photos
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos
Obter os metadados para um tamanho específico de foto
GET https://outlook.office.com/api/beta/me/photos('{size}')
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')
| Parâmetro opcional | Tipo | Descrição |
|---|---|---|
| Parâmetros de Url | ||
| user_id | sequência de caracteres | O endereço de email do usuário. |
| tamanho | sequência de caracteres | Uma dimensão de foto. O valor '1x1' é gerado automaticamente caso uma foto não esteja presente no Active Directory e na caixa de correio. Se a foto estiver armazenada na caixa postal, os tamanhos predefinidos são: '48x48', '64x64', '96x96', '120x120', '240x240', '360x360', '432x432', '504x504' e '648x648'. Caso o usuário não faça o carregamento de uma foto grande o suficiente, só estarão disponíveis os tamanhos que podem ser representados pelos menores tamanhos predefinidos. Por exemplo, quando o usuário carrega uma foto de 504x504 pixels, todos os tamanhos de foto ficam disponíveis para baixar, exceto o de 648x648. As fotos podem ter qualquer dimensão, desde que estejam armazenadas no Active Directory. |
Solicitação de amostra
Solicitação de amostra
GET https://outlook.office.com/api/beta/me/photos('240x240')
Dados de resposta da amostra
Os dados de resposta a seguir mostram os metadados da foto. O código de resposta 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
}
Os dados de resposta a seguir mostram o conteúdo de uma resposta quando uma foto ainda não foi carregada para o usuário. O código de resposta 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
}
Obter foto
Obter a foto do usuário especificado.
Essa operação permite que um administrador de locatário deixe que um aplicativo obtenha a foto de usuário de qualquer usuário no locatário.
Escopo requerido
Use um dos escopos a seguir para obter metadados da foto do usuário especificado, que pode ser o usuário conectado:
- user.readbasic.all
- user.read.all
- user.readwrite.all
Você também pode usar o escopo a seguir para obter a foto especificamente do usuário conectado:
- user.read
- user.readwrite
Obter o maior tamanho disponível
GET https://outlook.office.com/api/beta/me/photo/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo/$value
Obter a foto de um tamanho específico
GET https://outlook.office.com/api/beta/me/photos('{size}')/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')/$value
| Parâmetro opcional | Tipo | Descrição |
|---|---|---|
| Parâmetros de Url | ||
| user_id | sequência de caracteres | O endereço de email do usuário. |
| tamanho | sequência de caracteres | Uma dimensão de foto. O valor '1x1' é gerado automaticamente caso uma foto não esteja presente no Active Directory e na caixa de correio. Se a foto estiver armazenada na caixa postal, os tamanhos predefinidos são: '48x48', '64x64', '96x96', '120x120', '240x240', '360x360', '432x432', '504x504' e '648x648'. Caso o usuário não faça o carregamento de uma foto grande o suficiente, só estarão disponíveis os tamanhos que podem ser representados pelos menores tamanhos predefinidos. Por exemplo, quando o usuário carrega uma foto de 504x504 pixels, todos os tamanhos de foto ficam disponíveis para baixar, exceto o de 648x648. As fotos podem ter qualquer dimensão, desde que estejam armazenadas no Active Directory. |
Solicitação de amostra
Esta solicitação obtém a foto para o usuário conectado.
GET https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpg
Dados de resposta
Contém os dados binários da foto solicitada. O código de resposta HTTP é 200.
Definir a foto do usuário
Atribuir uma foto ao usuário especificado. A foto deve estar em binário. Ela substitui qualquer foto existente para esse usuário.
Essa operação permite que um administrador de locatários deixe que um aplicativo defina a foto do usuário de qualquer usuário no locatário. Use apenas o PUT para essa operação na versão beta.
Escopo requerido
Use o escopo a seguir para definir a foto do usuário especificado, que pode ser qualquer usuário no locatário ou o usuário conectado:
- user.readwrite.all
Também é possível usar o escopo a seguir para definir a foto especificamente do usuário conectado:
- user.readwrite
PUT https://outlook.office.com/api/beta/me/photo/$value
PUT https://outlook.office.com/api/beta/users('{user_id}')/photo/$value
| Parâmetro opcional | Tipo | Descrição |
|---|---|---|
| Parâmetros de Url | ||
| user_id | sequência de caracteres | O endereço de email do usuário. |
Solicitação de amostra
PUT https://outlook.office.com/api/beta/me/photo/$value
Content-Type: image/jpeg
Inclua os dados binários da foto no corpo da solicitação.
Dados de resposta
Uma solicitação bem-sucedida retorna HTTP 200.
Próximas etapas
Se você estiver pronto para começar a criar um aplicativo ou apenas quiser aprender mais, temos tudo o que você precisa.
- Comece com as APIs REST de email, calendário e contatos.
- Procura exemplos? Nós temos.
Se preferir, aprenda mais sobre como usar a plataforma do Office 365: