Пространство имен: microsoft.graph
Важно!
API версии /beta
в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
Получение сообщений в почтовом ящике пользователя, выполнившего вход (в том числе сообщений в папках "Удаленные" и "Несрочные").
В зависимости от размера страницы и данных почтового ящика получение сообщений из почтового ящика может повлечь множество запросов. По умолчанию страница содержит 10 сообщений. Используйте параметр $top
, чтобы настроить размер страницы в диапазоне от 1 до 1000.
Чтобы сократить время отклика, используйте параметр $select
для указания точных свойств, которые вам нужны. См. пример 1 ниже. Настройте значения для $select
и $top
, особенно при необходимости использовании большего размера страницы, так как возврат страницы с сотнями сообщений, каждое из которых содержит полные полезные данные отклика, может привести к истечению времени ожидания шлюза (HTTP 504).
Для получения следующей странице с сообщениями, просто примените весь URL-адрес, возвращаемый в @odata.nextLink
, для другого запроса на получение сообщений. Этот URL-адрес включает любые параметры запроса, которые указаны в первоначальном запросе.
Не извлекайте значение $skip
из URL-адреса @odata.nextLink
для операций с ответами. Данный API использует значение $skip
для учета всех элементов, просмотренных в почтовом ящике пользователя, и возврата элементов типа сообщение на странице. Таким образом, существует возможность, что даже в первоначальном ответе, значение $skip
будет больше, чем размер страницы. Дополнительные сведения см. в статье Разбивка данных Microsoft Graph по страницам в приложении
Вы можете отфильтровать сообщения и получить только те, которые содержат упоминание пользователя , выполнившего вход. См. пример ниже.
По умолчанию GET /me/messages
операция не возвращает свойство упоминания .
$expand
Используйте параметр запроса для поиска сведений о каждом упоминании в сообщении.
Существует два сценария, когда приложение может получить сообщения из папки почты другого пользователя:
- У приложения есть разрешения для приложений; или
- У приложения есть соответствующие делегированные разрешения от одного пользователя, а другой пользователь поделился с ним папкой почты или предоставил ему делегированный доступ. См. подробные сведения и пример.
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба |
Правительство США L4 |
Правительство США L5 (DOD) |
Китай управляется 21Vianet |
✅ |
✅ |
✅ |
✅ |
Разрешения
Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.
Тип разрешения |
Разрешения с наименьшими привилегиями |
Более высокие привилегированные разрешения |
Делегированные (рабочая или учебная учетная запись) |
Mail.ReadBasic |
Mail.ReadWrite, Mail.Read |
Делегированные (личная учетная запись Майкрософт) |
Mail.ReadBasic |
Mail.ReadWrite, Mail.Read |
Приложение |
Mail.ReadBasic.All |
Mail.ReadWrite, Mail.Read |
HTTP-запрос
Для получения всех сообщений в почтовом ящике пользователя:
GET /me/messages
GET /users/{id | userPrincipalName}/messages
Для получения сообщений из определенной папки в почтовом ящике пользователя:
GET /me/mailFolders/{id}/messages
GET /users/{id | userPrincipalName}/mailFolders/{id}/messages
Чтобы получить все сообщения в почтовом ящике пользователя, содержащие упоминание о пользователе, выполните следующие действия:
GET /me/messages?$filter=mentionsPreview/isMentioned eq true
GET /users/{id | userPrincipalName}/messages?$filter=mentionsPreview/isMentioned eq true
Необязательные параметры запросов
Этот метод поддерживает параметры запросов OData для настройки ответа.
Вы можете использовать $filter
параметр запроса в свойстве упоминанияPreview , чтобы получить сообщения, в которых упоминается пользователь, выполнившего вход.
Использование операторов filter и orderby в одном запросе
При использовании операторов $filter
и $orderby
в одном запросе на получение сообщений необходимо указать свойства, соблюдая указанные ниже условия.
- Свойства, используемые в операторе
$orderby
, также должны использоваться в операторе $filter
.
- Свойства, используемые в операторе
$orderby
, представлены в том же порядке, что и для оператора $filter
.
- Свойства, присутствующие в операторе
$orderby
, представлены в операторе $filter
раньше всех остальных свойств.
В противном случае возникнет следующая ошибка:
- Код ошибки:
InefficientFilter
- Сообщение об ошибке:
The restriction or sort order is too complex for this operation.
Имя |
Тип |
Описание |
Authorization |
string |
Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Prefer: outlook.body-content-type |
string |
Формат возвращаемых свойств body и uniqueBody. Возможные значения: "text" или "html". Если заголовок не указан, свойства body и uniqueBody возвращаются в формате HTML. Необязательный параметр. |
Текст запроса
Не указывайте текст запроса для этого метода.
Отклик
В случае успешного 200 OK
выполнения этот метод возвращает код отклика и коллекцию объектов сообщений в тексте ответа.
Примеры
Пример 1. Перечисление всех сообщений
Запрос
В первом примере по умолчанию возвращается 10 сообщений по умолчанию в почтовом ящике пользователя, выполнившего вход.
$select
используется для получения подмножества свойств каждого сообщения в ответе.
GET https://graph.microsoft.com/beta/me/messages?$select=sender,subject
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "sender","subject" };
});
mgc-beta users messages list --user-id {user-id} --select "sender,subject"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"sender","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"sender", "subject"};
});
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.version('beta')
.select('sender,subject')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["sender","subject"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Property "sender,subject"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select = ["sender","subject"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
Отклик
Ниже показан пример отклика. Чтобы получить следующую страницу с сообщениями, примените URL-адрес, возвращенный в @odata.nextLink
, для последующего запроса GET.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users('bb8775a4-4d8c-42cf-a1d4-4d58c2bb668f')/messages(sender,subject)",
"value": [
{
"@odata.etag": "W/\"CQAAABYAAADHcgC8Hl9tRZ/hc1wEUs1TAAAwR4Hg\"",
"id": "AAMkAGUAAAwTW09AAA=",
"subject": "You have late tasks!",
"sender": {
"emailAddress": {
"name": "Microsoft Planner",
"address": "[email protected]"
}
}
}
]
}
Пример 2. Использование $filter для получения всех сообщений, удовлетворяющих определенному условию
Запрос
В следующем примере фильтруются все сообщения в почтовом ящике пользователя, вошедшего в систему, для тех, в которых упоминается пользователь. Он также использует $select
для возврата подмножества свойств каждого сообщения в ответе.
В следующем примере также включается кодировка URL-адреса для пробелов в строке параметра запроса.
GET https://graph.microsoft.com/beta/me/messages?$filter=MentionsPreview/IsMentioned%20eq%20true&$select=Subject,Sender,ReceivedDateTime,MentionsPreview
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "MentionsPreview/IsMentioned eq true";
requestConfiguration.QueryParameters.Select = new string []{ "Subject","Sender","ReceivedDateTime","MentionsPreview" };
});
mgc-beta users messages list --user-id {user-id} --filter "MentionsPreview/IsMentioned eq true" --select "Subject,Sender,ReceivedDateTime,MentionsPreview"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
requestFilter := "MentionsPreview/IsMentioned eq true"
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Select: [] string {"Subject","Sender","ReceivedDateTime","MentionsPreview"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "MentionsPreview/IsMentioned eq true";
requestConfiguration.queryParameters.select = new String []{"Subject", "Sender", "ReceivedDateTime", "MentionsPreview"};
});
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.version('beta')
.filter('MentionsPreview/IsMentioned eq true')
.select('subject,sender,receivedDateTime,mentionsPreview')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "MentionsPreview/IsMentioned eq true";
$queryParameters->select = ["Subject","Sender","ReceivedDateTime","MentionsPreview"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Filter "MentionsPreview/IsMentioned eq true" -Property "Subject,Sender,ReceivedDateTime,MentionsPreview"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
filter = "MentionsPreview/IsMentioned eq true",
select = ["Subject","Sender","ReceivedDateTime","MentionsPreview"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.me.messages.get(request_configuration = request_configuration)
Отклик
Ниже показан пример отклика.
Примечание. Объект отклика, показанный здесь, может быть сокращен для удобочитаемости.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#me/messages(subject,sender,receivedDateTime,mentionsPreview)",
"value":[
{
"@odata.id":"https://graph.microsoft.com/beta/users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/messages('AQMkADJmMTUAAAgVZAAAA')",
"@odata.etag":"W/\"CQAAABYAAAAPFhK2FclcRbABBJhCde8iAAAAAATI\"",
"id":"AQMkADJmMTUAAAgVZAAAA",
"receivedDateTime":"2016-07-21T07:40:21Z",
"subject":"Re: Start planning soon",
"sender":{
"emailAddress":{
"name":"Adele Vance",
"address":"[email protected]"
}
},
"mentionsPreview":{
"isMentioned":true
}
}
]
}
Пример 3. Использование предпочтительного заголовка для получения текста сообщения и uniqueBody имеет текстовый формат
Запрос
В третьем примере показано, как использовать Prefer: outlook.body-content-type="text"
заголовок для получения свойств body и uniqueBody каждого сообщения в текстовом формате.
GET https://graph.microsoft.com/beta/me/messages?$select=subject,body,bodyPreview,uniqueBody
Prefer: outlook.body-content-type="text"
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "subject","body","bodyPreview","uniqueBody" };
requestConfiguration.Headers.Add("Prefer", "outlook.body-content-type=\"text\"");
});
mgc-beta users messages list --user-id {user-id} --select "subject,body,bodyPreview,uniqueBody"
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "outlook.body-content-type=\"text\"")
requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"subject","body","bodyPreview","uniqueBody"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"subject", "body", "bodyPreview", "uniqueBody"};
requestConfiguration.headers.add("Prefer", "outlook.body-content-type=\"text\"");
});
const options = {
authProvider,
};
const client = Client.init(options);
let messages = await client.api('/me/messages')
.version('beta')
.header('Prefer','outlook.body-content-type="text"')
.select('subject,body,bodyPreview,uniqueBody')
.get();
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$headers = [
'Prefer' => 'outlook.body-content-type="text"',
];
$requestConfiguration->headers = $headers;
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["subject","body","bodyPreview","uniqueBody"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Mail
# A UPN can also be used as -UserId.
Get-MgBetaUserMessage -UserId $userId -Property "subject,body,bodyPreview,uniqueBody"
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
select = ["subject","body","bodyPreview","uniqueBody"],
)
request_configuration = RequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("Prefer", "outlook.body-content-type=\"text\"")
result = await graph_client.me.messages.get(request_configuration = request_configuration)
Отклик
Ниже приводится пример отклика.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#users('cd209b0b-3f83-4c35-82d2-d88a61820480')/messages(subject,body,bodyPreview,uniqueBody)",
"value":[
{
"@odata.type":"#microsoft.graph.eventMessageRequest",
"@odata.etag":"W/\"CwAAABYAAABmWdbhEgBXTophjCWt81m9AAAoZYj5\"",
"id":"AAMkAGIAAAoZCfIAAA=",
"subject":"Orientation ",
"bodyPreview":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.",
"body":{
"contentType":"text",
"content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
},
"uniqueBody":{
"contentType":"text",
"content":"Dana, this is the time you selected for our orientation. Please bring the notes I sent you.\r\n"
}
}
]
}