Справочник по API действий управления Office 365
Используйте API действий управления Office 365 для получения сведений о действиях и событиях пользователей, администраторов, системных и политик из журналов действий Office 365 и Microsoft Entra.
Действия и события из Office 365 и Microsoft Entra журналов аудита и действий можно использовать для создания решений, которые обеспечивают мониторинг, анализ и визуализацию данных. Эти решения помогают организациям отслеживать действия, выполняемые с их контентом. Эти действия и события также доступны в отчетах об активности Office 365. Дополнительные сведения см. в статье Поиск в журнале аудита в Microsoft 365.
Совет
Если вы заинтересованы в создании пользовательских отчетов из журналов аудита, вы можете найти следующие блоги полезными.
API действий управления Office 365 — это веб-служба REST, с помощью которой можно разрабатывать решения на любом языке и в любой среде внешнего размещения, поддерживающей сертификаты HTTPS и X.509. API использует Microsoft Entra ID и протокол OAuth2 для проверки подлинности и авторизации. Чтобы получить доступ к API из приложения, необходимо сначала зарегистрировать его в Microsoft Entra ID и настроить его с соответствующими разрешениями. Благодаря этому приложение сможет запрашивать маркеры доступа OAuth2, необходимые для вызова API. Дополнительные сведения см. в статье Начало работы с интерфейсами API управления Office 365.
Сведения о данных, которые возвращает API действий управления Office 365, см. в статье Схема API действий управления Office 365.
Важно!
Чтобы получить доступ к данным с помощью API действий управления Office 365, требуется включить ведение единого журнала аудита для организации Office 365. Это выполняется путем включения журнала аудита Office 365. Инструкции см. в статье Включение и отключение поиска в журнале аудита Office 365.
Работа с API действий управления Office 365
API действий управления Office 365 собирает действия и события в большие двоичные объекты, содержащие контент для определенных клиентов и классифицируемые по типу и источнику контента. В настоящее время поддерживаются следующие типы контента:
Audit.AzureActiveDirectory
Audit.Exchange
Audit.SharePoint
Audit.General (включает все остальные рабочие нагрузки, не входящие в предыдущие типы контента)
DLP.All (только события DLP для всех рабочих нагрузок)
Подробные сведения о событиях и свойствах, связанных с этими типами контента, см. в статье Схема API действий управления Office 365.
Чтобы приступить к получению больших двоичных объектов содержимого для клиента, сначала создайте подписку на нужные типы контента. Если вы получаете большие двоичные объекты с контентом для нескольких клиентов, следует создать несколько подписок для каждого из нужных типов контента, по одной на клиент.
Создав подписку, вы можете регулярно проводить опрос для обнаружения новых больших двоичных объектов с контентом, доступных для скачивания. Вы также можете зарегистрировать конечную точку веб-перехватчика с подпиской, чтобы мы отправляли на нее уведомления, когда становятся доступны новые объекты.
Примечание.
После создания подписки может потребоваться до 12 часов, чтобы для нее стали доступны первые объекты. Большие двоичные объекты с контентом создаются путем сбора и агрегирования действий и событий с нескольких серверов и центров обработки данных. В результате этого распределенного процесса действия и события из больших двоичных объектов не обязательно отображаются в порядке их выполнения. Объект может содержать действия и события, произошедшие до действий и событий, содержащихся в ранее обработанном объекте. Мы работаем над уменьшением задержки между возникновением действий и событий и их появлением в большом двоичном объекте, но не можем гарантировать, что они будут отображаться в хронологическом порядке.
Примечание.
Конфиденциальные данные DLP доступны только в API веб-каналов активности для пользователей с разрешениями "Чтение конфиденциальных данных DLP". Дополнительные сведения о защите от потери данных (DLP) см. в статье Обзор политик защиты от потери данных
Операции с API действий
Все операции с API выполняются в рамках одного клиента, а корневой URL-адрес API включает ИД клиента, который задает контекст. ИД клиента представляет собой GUID. Сведения о том, как получить GUID, см. в статье Начало работы с интерфейсами API управления Office 365.
Так как уведомления, отправляемые веб-перехватчику, включают ИД клиента, вы можете получать уведомления для всех клиентов с помощью одного веб-перехватчика.
URL-адрес конечной точки API зависит от плана подписки на Microsoft 365 или Office 365 для вашей организации.
План для предприятий
https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}
План для государственных организаций (GCC)
https://manage-gcc.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}
План для государственных организаций (GCC High)
https://manage.office365.us/api/v1.0/{tenant_id}/activity/feed/{operation}
План для государственных организаций (DoD)
https://manage.protection.apps.mil/api/v1.0/{tenant_id}/activity/feed/{operation}
Для всех операций API требуется HTTP-заголовок авторизации с маркером доступа, полученным из Microsoft Entra ID. Идентификатор клиента в маркере доступа должен соответствовать идентификатору клиента в корневом URL-адресе API, а маркер доступа должен содержать утверждение ActivityFeed.Read (это соответствует разрешению [Чтение данных действий для организации], настроенное для приложения в Microsoft Entra ID).
Authorization: Bearer eyJ0e...Qa6wg
API действий поддерживает следующие операции:
создание подписки на получение уведомлений и данных об активности для клиента;
отмена подписки, позволяющая перестать получать данные для клиента;
вывод списка текущих подписок;
вывод списка доступного контента и соответствующих URL-адресов;
получение уведомлений, отправляемых веб-перехватчиком, когда становится доступен новый контент;
получение контента по URL-адресу;
вывод списка уведомлений, отправленных веб-перехватчиком;
получение понятных имен ресурсов для объектов в веб-канале данных, указанном идентификаторами GUID.
Создание подписки
Эта операция создает подписку на указанный тип контента. Если подписка на указанный тип контента уже существует, эта операция используется для:
обновления свойств активного веб-перехватчика;
включения веб-перехватчика, отключенного по причине избыточного количества неудачных попыток отправки уведомления;
повторного включения устаревшего веб-перехватчика путем указания более поздней или нулевой конечной даты срока действия;
удаления веб-перехватчика.
| Подписка | Описание |
|---|---|
| Путь | /subscriptions/start?contentType={ContentType} |
| Параметры | contentType — Должен быть допустимым типом контента. |
| PublisherIdentifier | GUID клиента поставщика, который обращается к API из кода. Это не GUID приложения или пользователя, работающего с приложением, а GUID компании, написавшей код. Этот параметр используется для регулирования частоты запросов. Убедитесь, что этот параметр указан во всех отправляемых запросах, чтобы получить отдельную квоту. Ко всем полученным запросам без этого параметра применяется одна квота. |
| Основной текст | webhook — Необязательный объект JSON с тремя свойствами:
|
| Отклик | contentType — Тип контента, указанный в вызове. |
| status | Состояние подписки. Если подписка отключена, вы не сможете выводить или извлекать содержимое. |
| webhook | Свойства веб-перехватчика, указанные в вызове вместе с его состоянием. Если веб-перехватчик отключен, вы не получите уведомление, но по-прежнему сможете выводить список и извлекать содержимое при условии, что подписка включена. |
Пример запроса
POST {root}/subscriptions/start?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Content-Type: application/json; utf-8
Authorization: Bearer eyJ0e...Qa6wg
{
"webhook" : {
"address": "https://webhook.myapp.com/o365/",
"authId": "o365activityapinotification",
"expiration": ""
}
}
Пример отклика
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"contentType": "Audit.SharePoint",
"status": "enabled",
"webhook": {
"status": "enabled",
"address": "https://webhook.myapp.com/o365/",
"authId": "o365activityapinotification",
"expiration": null
}
}
Проверка веб-перехватчиков
При вызове операции /start с указанием веб-перехватчика мы отправим уведомление о проверке на указанный адрес веб-перехватчика, чтобы убедиться, что активный прослушиватель может принимать и обрабатывать уведомления. Если мы не получим отклик HTTP 200 OK, подписка не будет создана. Если же операция /start вызывается для добавления веб-перехватчика к имеющейся подписке, а отклик HTTP 200 OK не получен, то веб-перехватчик не будет добавлен, а подписка останется без изменений.
Пример запроса
POST {webhook address}
Content-Type: application/json; charset=utf-8
Webhook-AuthID: (webhook authId, if provided)
Webhook-ValidationCode: (random opaque string)
{
"validationCode": (random opaque string, same as header)
}
Пример отклика
HTTP/1.1 200 OK
Остановка подписки
Эта операция отменяет подписку на указанный тип контента.
Когда подписка будет остановлена, вы больше не будете получать уведомления и не сможете получить доступное содержимое. Если подписка будет перезапущена, вы получите доступ к новому содержимому с этого момента. Получать контент, который был доступен с момента отмены подписки до ее повторного создания, будет невозможно.
| Подписка | Описание |
|---|---|
| Путь | /subscriptions/stop?contentType={ContentType} |
| Параметры | contentType — Должен быть допустимым типом контента. |
| PublisherIdentifier | GUID клиента поставщика, который обращается к API из кода. Это не GUID приложения или пользователя, работающего с приложением, а GUID компании, написавшей код. Этот параметр используется для регулирования частоты запросов. Убедитесь, что этот параметр указан во всех отправляемых запросах, чтобы получить отдельную квоту. Ко всем полученным запросам без этого параметра применяется одна квота. |
| Основной текст | (пусто) |
| Отклик | (пусто) |
Пример запроса
POST {root}/subscriptions/stop?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Пример отклика
HTTP/1.1 200 OK
Вывод списка текущих подписок
Эта операция возвращает коллекцию текущих подписок вместе со связанными веб-перехватчиками.
| Подписка | Описание | |
|---|---|---|
| Путь | /subscriptions/list |
|
| Параметры | PublisherIdentifier | GUID клиента поставщика, который обращается к API из кода. Это не GUID приложения или пользователя, работающего с приложением, а GUID компании, написавшей код. Этот параметр используется для регулирования частоты запросов. Убедитесь, что этот параметр указан во всех отправляемых запросах, чтобы получить отдельную квоту. Ко всем полученным запросам без этого параметра применяется одна квота. |
| Основной текст | (пусто) | |
| Отклик | Массив JSON | Каждая подписка будет представлена объектом JSON с тремя свойствами:
|
Пример запроса
GET {root}/subscriptions/list?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Пример отклика
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"contentType" : "Audit.SharePoint",
"status": "enabled",
"webhook": {
"status": "enabled",
"address": "https://webhook.myapp.com/o365/",
"authId": "o365activityapinotification",
"expiration": null
}
},
...
{
"contentType": "Audit.Exchange",
"webhook": null
}
]
Вывод списка доступного контента
Эта операция перечисляет контент указанного типа, доступный в данный момент для получения. Этот контент представляет собой сочетание действий и событий, полученных с нескольких серверов из нескольких центров обработки данных. Список контента упорядочен по времени появления сборок, но события и действия в рамках этих сборок не обязательно будут указаны по порядку. Если подписка отключена, возвращается ошибка.
| Подписка | Описание |
|---|---|
| Путь | /subscriptions/content?contentType={ContentType}&startTime={0}&endTime={1} |
| Параметры | contentType — Должен быть допустимым типом контента. |
| PublisherIdentifier | GUID клиента поставщика, который обращается к API из кода. Это не GUID приложения или пользователя, работающего с приложением, а GUID компании, написавшей код. Этот параметр используется для регулирования частоты запросов. Убедитесь, что этот параметр указан во всех отправляемых запросах, чтобы получить отдельную квоту. Ко всем полученным запросам без этого параметра применяется одна квота. |
| startTime endTime | Необязательные значения даты и времени (в формате UTC), указывающие диапазон времени появления возвращаемого контента. Диапазон времени является инклюзивным в отношении startTime (startTime <= contentCreated) и эксклюзивным в отношении endTime (contentCreated < endTime), поэтому неперекрывающиеся и добавочные интервалы времени могут использоваться для страницы доступного содержимого.
ПРИМЕЧАНИЕ. Вы можете указать значения startTime и endTime с интервалом более 24 часов, но это не рекомендуется. Более того, даже если вы получите какие-либо результаты по запросу на период времени продолжительностью более 24 часов, они будут частичными и их не следует учитывать. Запрос должен отправляться с интервалом не более 24 часов между значениями startTime и endTime. |
| Отклик | Массив JSON — Доступное содержимое будет представлено объектами JSON со следующими свойствами:
|
Пример запроса
GET {root}/subscriptions/content?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Пример отклика
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"contentType": "Audit.SharePoint",
"contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
"contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
"contentCreated": "2015-05-23T17:35:00.000Z",
"contentExpiration": "2015-05-30T17:35:00.000Z"
},
...
]
Разбивка на страницы
При выводе списка доступного контента за определенный диапазон времени количество возвращаемых результатов ограничено во избежание просроченных откликов. Если за указанный диапазон времени возвращается больше результатов, чем помещается в один отклик, то результаты будут усечены, а к отклику будет добавлен заголовок с URL-адресом для получения следующей страницы результатов. URL-адрес будет содержать те же параметры startTime и endTime , которые были указаны в исходном запросе, а также параметр, указывающий внутренний идентификатор следующей страницы. Если значения startTime и endTime не были указаны в исходном запросе, то будут заданы даты для 24-часового интервала, предшествующего первоначальному запросу.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
NextPageUri: https://manage.office.com/api/v1/{tenant_id}/activity/feed/subscriptions/content?contentType=Audit.SharePoint&startTime=2015-10-01&endTime=2015-10-02&nextPage=2015101900R022885001761
Чтобы получить список доступного контента за указанный диапазон времени, вы можете извлекать страницы, пока не будет получен отклик без заголовка NextPageUri.
Получение уведомлений
По мере появления нового контента веб-перехватчику, настроенному для подписки, отправляются уведомления. Так как уведомление включает идентификатор клиента, вы можете использовать один и тот же веб-перехватчик для получения уведомлений обо всех клиентах, подписки на которые у вас есть.
Уведомление содержит запрос HTTP POST по протоколу TLS (TLS 1.0 и более поздних версий) по указанному адресу веб-перехватчика. Если конфигурация веб-перехватчика включает ИД аутентификации, мы отправим его в качестве HTTP-заголовка Webhook-AuthID. Любой отклик, кроме HTTP 200 OK, считается сбоем, и выполняется повторная попытка. Вы также можете настроить веб-перехватчик, чтобы требовалась проверка подлинности на основе клиентских сертификатов, и мы выполним аутентификацию с помощью сертификата manage.office.com.
Текст запроса будет содержать массив из одного или нескольких объектов JSON, представляющих доступные большие двоичные объекты с контентом. Количество объектов с контентом в каждом уведомлении ограничено, чтобы размер уведомлений оставался относительно небольшим. Так как это ограничение может измениться, ваша реализация должна запрашивать длину массива, а не рассчитывать на фиксированный размер. Каждый объект будет включать те же свойства, которые возвращает операция /content, а также GUID клиента, которому принадлежат данные, и GUID приложения, создавшего подписки. Это позволит веб-перехватчику задать контекст при использовании с несколькими клиентами и приложениями.
tenantId. GUID клиента, которому принадлежит контент.
clientId. GUID приложения, создавшего подписку.
contentType. Указывает тип контента.
contentId. Непрозрачная строка, однозначно определяющая контент.
contentUri. URL-адрес, используемый при получении контента.
contentCreated. Дата и время появления контента.
contentExpiration. Дата и время, после которых контент больше не будет доступен для получения.
Ниже приводится пример уведомления.
POST https://webhook.myapp.com/o365/
Content-Type: application/json; utf-8
Webhook-AuthID: o365activityapinotification
[
{
"tenantId": "{GUID}",
"clientId": "{GUID}",
"contentType": "Audit.SharePoint",
"contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
"contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
"contentCreated": "2015-05-23T17:35:00.000Z",
"contentExpiration": "2015-05-30T17:35:00.000Z"
},
...
]
Сбой и повторная попытка отправки уведомления
Система уведомлений отправляет уведомления по мере появления нового контента. Если при отправке уведомлений возникнет слишком большое количество сбоев, наш механизм повторных попыток будет экспоненциально увеличивать интервал между попытками. Если сбои продолжат возникать, мы оставляем за собой право отключить веб-перехватчик и совсем перестать отправлять ему уведомления. С помощью операции /start можно заново включить отключенный веб-перехватчик.
Получение содержимого
Чтобы получить большой двоичный объект с контентом, отправьте запрос GET на соответствующий URI, включенный в список доступного контента, и в уведомления, отправляемые веб-перехватчику. Возвращаемый контент будет коллекцией из одного или нескольких действий или событий в формате JSON.
Пример запроса
GET https://manage.office.com/api/v1.0/41463f53-8812-40f4-890f-865bf6e35190/activity/feed/audit/301299007231$301299007231$41463f53881240f4890f865bf6e35190aad2015062920$e1c2ab19858a469fb1f1fd097effffc9$04 HTTP/1.1
Authorization: Bearer eyJ0e...Qa6wg
Пример отклика
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"CreationTime": "2015-06-29T20:03:19",
"Id": "80c76bd2-9d81-4c57-a97a-accfc3443dca",
"Operation": "PasswordLogonInitialAuthUsingPassword",
"OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
"RecordType": 9,
"ResultStatus": "failed",
"UserKey": "1153977025279851686@contoso.onmicrosoft.com",
"UserType": 0,
"Workload": "AzureActiveDirectory",
"ClientIP": "134.170.188.221",
"ObjectId": "admin@contoso.onmicrosoft.com",
"UserId": "admin@contoso.onmicrosoft.com",
"AzureActiveDirectoryEventType": 0,
"ExtendedProperties": [
{
"Name": "LoginError",
"Value": "-2147217390;PP_E_BAD_PASSWORD;The entered and stored passwords do not match."
}
],
"Client": "Exchange",
"LoginStatus": -2147217390,
"UserDomain": "contoso.onmicrosoft.com"
},
{
"CreationTime": "2015-06-29T20:03:34",
"Id": "4e655d3f-35fa-42e0-b050-264b2d255c7a",
"Operation": "PasswordLogonInitialAuthUsingPassword",
"OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
"RecordType": 9,
"ResultStatus": "success",
"UserKey": "1153977025279851686@contoso.onmicrosoft.com",
"UserType": 0,
"Workload": "AzureActiveDirectory",
"ClientIP": "134.170.188.221",
"ObjectId": "admin@contoso.onmicrosoft.com",
"UserId": "admin@contoso.onmicrosoft.com",
"AzureActiveDirectoryEventType": 0,
"Client": "Exchange",
"LoginStatus": 0,
"UserDomain": "contoso.onmicrosoft.com"
},
{
"CreationTime": "2015-06-29T20:04:55",
"Id": "b567caf0-088e-4c1c-a4ea-633a1e3d66c8",
"Operation": "Add User.",
"OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
"RecordType": 8,
"ResultStatus": "success",
"UserKey": "1003BFFD8EC47CA6@contoso.onmicrosoft.com",
"UserType": 0,
"Workload": "AzureActiveDirectory",
"ObjectId": "user001@contoso.onmicrosoft.com",
"UserId": "admin@contoso.onmicrosoft.com",
"AzureActiveDirectoryEventType": 0,
"Actor": [
{
"ID": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
"Type": 2
},
{
"ID": "admin@contoso.onmicrosoft.com",
"Type": 5
},
{
"ID": "1003BFFD8EC47CA6",
"Type": 3
}
],
"ActorContextId": "41463f53-8812-40f4-890f-865bf6e35190",
"InterSystemsId": "c2ced078-ad57-4079-a743-5c37f5284790",
"IntraSystemId": "d1497f7e-15b4-49aa-83ad-11a17ca4a2f4",
"Target": [
{
"ID": "user001@contoso.onmicrosoft.com",
"Type": 5
},
{
"ID": "10037FFE91510806",
"Type": 3
}
],
"TargetContextId": "41463f53-8812-40f4-890f-865bf6e35190"
}
]
Список уведомлений
Эта операция выводит список всех попыток отправки уведомлений об указанном типе контента. Если вы не включили веб-перехватчик при создании подписки на тип контента, то для получения не будет доступно никаких уведомлений. Так как мы повторяем попытку отправки уведомления в случае сбоя, эта операция может возвращать множество уведомлений для одного и того же контента, а порядок отправки уведомлений не обязательно будет совпадать с порядком его появления (особенно если происходили сбои и повторные попытки).
С помощью этой операции можно расследовать проблемы, связанные с веб-перехватчиками и уведомлениями, но ее не следует использовать для определения контента, доступного для получения в настоящее время. Используйте вместо нее операцию /content. Мы возвращаем ошибку, если подписка отключена.
| Подписка | Описание |
|---|---|
| Путь | /subscriptions/notifications?contentType={ContentType}&startTime={0}&endTime={1} |
| Параметры | contentType — Должен быть допустимым типом контента. |
| PublisherIdentifier | GUID клиента поставщика, который обращается к API из кода. Это не GUID приложения или пользователя, работающего с приложением, а GUID компании, написавшей код. Этот параметр используется для регулирования частоты запросов. Убедитесь, что этот параметр указан во всех отправляемых запросах, чтобы получить отдельную квоту. Ко всем полученным запросам без этого параметра применяется одна квота. |
| startTime endTime | Необязательные значения даты и времени (в формате UTC), указывающие диапазон времени появления возвращаемого контента. Диапазон времени является инклюзивным по отношению к startTime ( startTime<= contentCreated) и эксклюзивным в отношении endTime (contentCreated< endTime), поэтому неперекрывающиеся интервалы времени могут использоваться для страницы доступного содержимого.
|
| Отклик | Массив JSON — Уведомления будут представлены объектами JSON со следующими свойствами:
|
Пример запроса
GET {root}/subscriptions/notifications?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Пример отклика
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"contentType": "Audit.SharePoint",
"contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
"contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
"contentCreated": "2015-05-23T17:35:00.000Z",
"contentExpiration": "2015-05-30T17:35:00.000Z",
"notificationSent": "2015-05-23T17:36:00.000Z",
"notificationStatus": "success"
},
...
]
Разбивка на страницы
При выводе журнала уведомлений за определенный диапазон времени количество возвращаемых результатов ограничивается во избежание появления просроченных откликов. Если за указанный диапазон времени возвращается больше результатов, чем помещается в один отклик, то результаты усекаются, а к отклику добавляется заголовок с URL-адресом для получения следующей страницы результатов. URL-адрес будет содержать те же параметры startTime и endTime , которые были указаны в исходном запросе, а также параметр, указывающий внутренний идентификатор следующей страницы. Если значения startTime и endTime не были указаны в исходном запросе, то будут заданы даты для 24-часового интервала, предшествующего первоначальному запросу.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
NextPageUri: https://manage.office.com/api/v1/{tenant_id}/activity/feed/subscriptions/content?contentType=Audit.SharePoint&startTime=2015-10-01&endTime=2015-10-02&nextPage=2015101900R022885001761
Чтобы получить список доступного контента за указанный диапазон времени, вы можете извлекать страницы, пока не будет получен отклик без заголовка NextPageUri.
Получение понятных имен ресурсов
Эта операция получает понятные имена указанных по GUID объектов из веб-канала данных. В настоящее время поддерживается только объект DlpSensitiveType.
| Объект | Подписка | Описание |
|---|---|---|
| Путь | /resources/dlpSensitiveTypes |
|
| Параметры | PublisherIdentifier | GUID клиента поставщика, который обращается к API из кода. Это не GUID приложения или пользователя, работающего с приложением, а GUID компании, написавшей код. Этот параметр используется для регулирования частоты запросов. Убедитесь, что этот параметр указан во всех отправляемых запросах, чтобы получить отдельную квоту. Ко всем полученным запросам без этого параметра применяется одна квота. |
| Заголовка | Accept-Language | Заголовок, указывающий нужный язык для локализованных имен. Например, используйте значение "en-US" для английского и "es" для испанского. Если этот заголовок отсутствует, возвращается язык по умолчанию (en-US). |
| Основной текст | (пусто) | |
| Отклик | Массив JSON | Доступный контент будет представлен объектами JSON со следующими свойствами:
|
Пример запроса
GET {root}/resources/dlpSensitiveTypes?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Accept-Language: {language code}
Пример отклика
HTTP/1.1 200 OK
[
{
"id": "50842eb7-edc8-4019-85dd-5a5c1f2bb085",
"name": "CreditCardNumber"
},
{
"id": "0e9b3178-9678-47dd-a509-37222ca96b42",
"name": "EUDebitCardNumber"
},
...
{
}
]
Регулирование API
В организациях, обращающихся к журналам аудита с помощью API действий управления Office 365, применялись ограничения регулирования на уровне издателя. Это означает, что для извлечения данных издателем от имени нескольких клиентов ограничение распространялось на всех этих клиентов.
Мы переходим с ограничения на уровне издателя к ограничению на уровне клиента. В результате каждая организация будет иметь собственную полностью выделенную квоту пропускной способности для доступа к данным аудита. Для всех организаций изначально выделяется базовый уровень 2 000 запросов в минуту. Это не статический, предварительно определенный предел, а моделирующийся на основе сочетания факторов, включая число рабочих мест в организации и получение организациями Office 365 и Microsoft 365 E5 вдвое большей пропускной способности по сравнению с организациями без плана E5. Для защиты работоспособности службы также будет использоваться ограничение максимальной пропускной способности.
Дополнительные сведения см. в разделе "Доступ с высокой пропускной способностью к API действий управления Office 365" статьи Расширенный аудит в Microsoft 365.
Примечание.
Хотя каждый клиент может изначально отправлять до 2 000 запросов в минуту, корпорация Майкрософт не может гарантировать скорость отклика. Она зависит от различных факторов, таких как производительность клиентской системы, а также мощность и скорость сети.
Ошибки
Когда служба обнаруживает ошибку, она возвращает отправителю вызова соответствующий код отклика, используя стандартный синтаксис кодов ошибок HTTP. . Дополнительные сведения включены в текст неудачного запроса в виде одного объекта JSON. Ниже приведен пример полного текста ошибки JSON.
{
"error":{
"code":"AF50000",
"message": "An internal server error occurred. Retry the request."
}
}
| Код | Сообщение |
|---|---|
| AF10001 | Набор разрешений ({0}), отправленный в запросе, не включал ожидаемое разрешение ActivityFeed.Read. {0} — набор разрешений в маркере доступа. |
| AF20001 | Отсутствующий параметр: {0}. {0} — имя отсутствующего параметра. |
| AF20002 | Недопустимый тип параметра: {0}. Ожидаемый тип: {1} {0} — имя недопустимого параметра.{1} — ожидаемый тип (int, datetime, guid). |
| AF20003 | Время окончания срока действия ({0}) уже прошло. {0} — время окончания срока действия, переданное в вызове API. |
| AF20010 | ИД клиента, переданный в URL-адресе ({0}), не совпадает с ИД клиента в маркере доступа ({1}). {0} — идентификатор клиента, переданный в URL-адресе{1} — идентификатор клиента, переданный в маркере доступа |
| AF20011 | Указанный ИД клиента ({0}) не существует в системе или был удален. {0} — ИД клиента, переданный в URL-адресе. |
| AF20012 | Указанный ИД клиента ({0}) неправильно настроен в системе. {0} — ИД клиента, переданный в URL-адресе. |
| AF20013 | ИД клиента, переданный в URL-адресе ({0}), не является допустимым GUID. {0} — ИД клиента, переданный в URL-адресе. |
| AF20020 | Указанный тип контента не является допустимым. |
| AF20021 | Не удалось проверить конечную точку веб-перехватчика {{0}). {1} {0} — адрес веб-перехватчика. {1} = "Конечная точка не вернула HTTP 200". Или "Адрес должен начинаться с HTTPS". |
| AF20022 | Подписка для указанного типа контента не найдена. |
| AF20023 | Подписку отключил {0}. {0} — "администратор клиента" или "администратор службы" |
| AF20030 | Необходимо указать время начала и окончания (или пропустить оба значения), а интервал между ними не должен превышать 24 часа. При этом со времени начала должно пройти не более 7 дней. |
| AF20031 | Недопустимые входные данные nextPage: {0}. {0} — индикатор следующей страницы, переданный в URL-адресе |
| AF20050 | Указанный контент ({0}) не существует. {0} — идентификатор или URL-адрес ресурса |
| AF20051 | Контент, запрашиваемый с помощью ключа {0}, уже устарел. Контент старше 7 дней невозможно получить.< {0} — идентификатор или URL-адрес ресурса |
| AF20052 | Недопустимый ИД контента {0} в URL-адресе {0} — идентификатор или URL-адрес ресурса |
| AF20053 | В заголовке Accept-Language можно указать только один язык. |
| AF20054 | Недопустимый синтаксис в заголовке Accept-Language. |
| AF429 | Слишком много запросов. Method={0}, PublisherId={1} {0} — метод HTTP {1} — GUID клиента, используемый в качестве параметра PublisherIdentifier |
| AF50000 | Произошла внутренняя ошибка. Повторите запрос. |