REST API приложений Defender для облака
В этой статье описывается взаимодействие с Defender для облака приложениями по протоколу HTTPS.
API приложений Microsoft Defender для облака предоставляет программный доступ к приложениям Defender для облака через конечные точки REST API. Приложения могут использовать API для выполнения операций чтения и обновления данных и объектов Defender для облака Apps. Например, API приложений Defender для облака поддерживает следующие распространенные операции для объекта пользователя:
- Отправка файлов журнала для облачного обнаружения
- создание скриптов блокировки;
- вывод списка действий и оповещений;
- закрытие и разрешение оповещений.
Структура URL-адреса API
Чтобы использовать API Defender для облака Apps, необходимо сначала получить URL-адрес API от клиента. URL-адрес API использует следующий формат: https://<portal_url>/api/<endpoint>
Чтобы получить URL-адрес API приложений Defender для облака для клиента, сделайте следующее:
На портале Microsoft Defender выберите параметры. Затем выберите "Облачные приложения". В разделе "Система" выберите "О".
На экране Defender для облака приложениях можно просмотреть URL-адрес API.
Получив URL-адрес API, добавьте /api
в него суффикс, чтобы получить URL-адрес API. Например, если url-адрес портала имеется https://mytenant.us2.contoso.com
, url-адрес API — это https://mytenant.us2.portal.cloudappsecurity.com/api
.
Маркеры API
Defender для облака приложениям требуется маркер API в заголовке всех запросов API к серверу, например следующий:
Authorization: Token <your_token_key>
Где <your_token_key>
находится личный маркер API.
Дополнительные сведения о маркерах API см. в разделе "Управление маркерами API".
Маркеры API — пример
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"
Какие действия поддерживаются?
В следующей таблице описаны поддерживаемые действия.
Ресурс | HTTP-команды | Маршруты URI |
---|---|---|
Процедуры | GET или POST | /api/v1/activities/ |
видны узлы | GET или POST | /api/v1/alerts/ |
Обогащение данных | GET, POST или DELETE | /api/subnet/ |
Сущности | GET или POST | /api/v1/entities/ |
Файлы | GET или POST | /api/v1/files/ |
Где ресурс представляет группу связанных сущностей.
Какие типы полей поддерживаются?
В следующей таблице описаны поддерживаемые типы полей:
Поле | Description |
---|---|
строка | Текстовая строка |
boolean | Логическое значение, представляющее значение true/false |
integer | 32-битное целое число со знаком |
TIMESTAMP | Миллисекунда с эпохи |
Метки времени
Упоминания меток времени в API приложений Defender для облака относятся к метке времени Unix в миллисекундах. Эта метка времени определяется числом миллисекунда с 1970-01-01 01 0:00:00. Командлет PowerShell для преобразования дат в метки времени можно использовать командлет PowerShell для получения даты .
Ограничения
Вы можете ограничить запросы, предоставив параметр ограничения в запросе.
Для предоставления параметра ограничения поддерживаются следующие методы:
- URL-кодирование (с
Content-Type: application/x-www-form-urlencoded
заголовком) - Данные форм
- Текст JSON (с
Content-Type: multipart/form-data
соответствующим заголовком границ)
Примечание.
- Если ограничение не задано, будет задано значение по умолчанию 100.
- Ответы на все запросы, сделанные с помощью маркера API, ограничены максимум 100 элементами.
- Ограничение регулирования для всех запросов API составляет 30 запросов в минуту на клиент.
Фильтры
При наличии большого количества результатов вы найдете полезное для точной настройки запросов с помощью фильтров. В этом разделе описывается структура операторов, с которыми можно использовать фильтры.
Структура
Некоторые конечные точки API поддерживают фильтры при выполнении запросов. В их соответствующих разделах вы найдете ссылку на все доступные поля фильтрации и поддерживаемые операторы для этого ресурса.
Большинство фильтров поддерживают несколько значений для предоставления мощных запросов. При объединении фильтров и операторов мы используем AND в качестве логического оператора между фильтрами.
Фильтры — пример
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
"filters": {
"some.field": {
"eq": ["value1", "value2"],
"isset": true
},
"some.field2": {
"gte": 5
}
},
"skip": 5,
"limit": 10
}'
Операторы
Примечание.
Не все операторы совместимы со всеми фильтрами.
В следующей таблице описаны поддерживаемые операторы:
Оператор | Тип ответа | Description |
---|---|---|
содержит | список строк | Возвращает все соответствующие записи, содержащие одну из предоставленных строк. |
deq | список значений | Возвращает все записи, содержащие одно значение, не равное указанному значению. |
потомок | список значений | Возвращает все соответствующие записи, соответствующие значениям или потомкам их |
не устареть | список строк | Возвращает все соответствующие записи, которые не начинаются с каждой предоставленной строки. |
заканчивается на | список строк | Возвращает все соответствующие записи, заканчивающиеся одной из предоставленных строк. |
eq | список значений | Возвращает все соответствующие записи, содержащие одно из предоставленных значений. |
gt | одно значение | Возвращает все записи, значения которых больше предоставленного значения. |
gte | одно значение | Возвращает все записи, значение которых больше или равно заданному значению. |
gte_ndays | number | Возвращает все записи с датой позже N дней назад |
набор мезосет | boolean | Если задано значение true, возвращает все соответствующие записи, не имеющие значения в указанном поле. |
isset | boolean | Если задано значение true, возвращает все соответствующие записи, имеющие значение в указанном поле. |
lt | одно значение | Возвращает все записи, значения которых меньше указанного значения. |
lte | одно значение | Возвращает все записи, значение которых меньше или равно предоставленному значению. |
lte_ndays | number | Возвращает все записи с датой выше N дней назад |
ncontains | список строк | Возвращает все соответствующие записи, не содержащие одну из предоставленных строк. |
ndescendantof | список значений | Возвращает все соответствующие записи, не соответствующие значениям или потомкам их |
neq | список значений | Возвращает все соответствующие записи, не содержащие все предоставленные значения. |
range | список объектов, содержащих поля start и end | Возвращает все записи в одном из предоставленных диапазонов. |
startswith | список строк | Возвращает все соответствующие записи, начиная с одной из предоставленных строк. |
startswithsingle | строка | Возвращает все соответствующие записи, начиная с предоставленной строки. |
text | строка | Выполняет полнотекстовый поиск всех записей |
Следующие шаги
Если у вас возникли проблемы, мы здесь, чтобы помочь. Чтобы получить помощь или поддержку проблемы с продуктом, откройте запрос в службу поддержки.