REST API приложений Defender для облака

Статья
10/20/2023

В этой статье описывается взаимодействие с Defender для облака приложениями по протоколу HTTPS.

API приложений Microsoft Defender для облака предоставляет программный доступ к приложениям Defender для облака через конечные точки REST API. Приложения могут использовать API для выполнения операций чтения и обновления данных и объектов Defender для облака Apps. Например, API приложений Defender для облака поддерживает следующие распространенные операции для объекта пользователя:

отправка файлов журнала для Cloud Discovery;
создание скриптов блокировки;
вывод списка действий и оповещений;
закрытие и разрешение оповещений.

Структура 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/
Files	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
}'

Операторы