REST API Microsoft Defender for Cloud Apps

Статья
11/28/2024

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

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

Отправка файлов журналов для обнаружения в облаке
Создание блочных скриптов
Перечисление действий и оповещений
Закрытие или разрешение оповещений

Структура URL-адреса API

Чтобы использовать API Defender for Cloud Apps, необходимо сначала получить URL-адрес API из клиента. URL-адрес API использует следующий формат: https://<portal_url>/api/<endpoint>.

Чтобы получить URL-адрес API Defender for Cloud Apps для клиента, сделайте следующее:

На портале Microsoft Defender выберите Параметры. Затем выберите Облачные приложения. В разделе Система выберите О программе.
На экране Defender for Cloud Apps о программе вы увидите URL-адрес API.

Получив URL-адрес API, добавьте в него суффикс /api , чтобы получить URL-адрес API. Например, если URL-адрес портала — https://mytenant.us2.contoso.com, то URL-адрес API — https://mytenant.us2.portal.cloudappsecurity.com/api.

Маркеры API

Defender for Cloud Apps требуется маркер 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/
Entities	GET или POST	/api/v1/entities/
Файлы	GET или POST	/api/v1/files/

Где Ресурс представляет группу связанных сущностей.

Какие типы полей поддерживаются?

В следующей таблице описаны поддерживаемые типы полей:

Поле	Описание
string	Текстовая строка
логический	Логическое значение, представляющее значение true/false
integer	32-разрядное целое число со знаком
метка времени	Миллисекунда с эпохи

Временные метки

Упоминания меток времени в API Defender for Cloud Apps относятся к метке времени Unix в миллисекундах. Эта метка времени определяется числом миллисекундах с 1970-01-01 0:00:00. Для преобразования дат в метки времени можно использовать командлет PowerShell get-date .

Ограничения

Вы можете ограничить запросы, указав параметр limit в запросе.

Для предоставления параметра limit поддерживаются следующие методы:

В кодировке URL-адреса (с заголовком Content-Type: application/x-www-form-urlencoded )
Данные форм
Текст JSON (с Content-Type: multipart/form-data и соответствующим заголовком границы)

Примечание.

Если ограничение не указано, будет установлено значение по умолчанию 100.
Ответы на все запросы, выполненные с помощью маркера API, ограничены не более 100 элементами.
Ограничение для всех запросов API составляет 30 запросов в минуту на клиент.

Фильтры

Если у вас есть большое количество результатов, вам будет полезно точно настроить запросы с помощью фильтров. В этом разделе описывается структура и операторы, которые могут использоваться с фильтрами.

Структура

Некоторые конечные точки API поддерживают фильтры при выполнении запросов. В соответствующих разделах вы найдете ссылку со списком всех доступных фильтруемых полей и поддерживаемых операторов для этого ресурса.

Большинство фильтров поддерживают несколько значений, предоставляя мощные запросы. При объединении фильтров и операторов мы используем И в качестве логического оператора между фильтрами.

Пример фильтров

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
}'

Операторы

Примечание.

Не все операторы совместимы со всеми фильтрами.

В следующей таблице описаны поддерживаемые операторы:

Оператор	Тип ответа	Описание
contains	список строк	Возвращает все соответствующие записи, содержащие одну из предоставленных строк.
deq	список значений	Возвращает все записи, содержащие одно значение, не равное одному указанному значению.
потомок	список значений	Возвращает все соответствующие записи, соответствующие значениям или их потомкам
doesnotstartwith	список строк	Возвращает все соответствующие записи, не начиная с каждой из предоставленных строк.
endswith	список строк	Возвращает все соответствующие записи, заканчивающиеся одной из предоставленных строк.
eq	список значений	Возвращает все соответствующие записи, содержащие одно из указанных значений.
gt	одно значение	Возвращает все записи, значение которых больше указанного значения.
Гтэ	одно значение	Возвращает все записи, значение которых больше или равно предоставленному значению.
gte_ndays	число	Возвращает все записи с датой позже, чем на N дней назад
параметр isnotset	логический	Если задано значение true, возвращает все соответствующие записи, которые не имеют значения в указанном поле.
isset	логический	Если задано значение true, возвращает все соответствующие записи, имеющие значение в указанном поле.
lt	одно значение	Возвращает все записи, значение которых меньше указанного значения.
lte	одно значение	Возвращает все записи, значение которых меньше или равно предоставленному значению.
lte_ndays	число	Возвращает все записи с датой, предшествующей N дней назад
ncontains	список строк	Возвращает все соответствующие записи, не содержащие одну из предоставленных строк.
ndescendantof	список значений	Возвращает все соответствующие записи, не соответствующие значениям или их потомкам
neq	список значений	Возвращает все соответствующие записи, не содержащие все предоставленные значения.
range	список объектов, содержащих поля "start" и "end"	Возвращает все записи в пределах одного из предоставленных диапазонов.
startswith	список строк	Возвращает все соответствующие записи, начиная с одной из предоставленных строк.
startswithsingle	string	Возвращает все соответствующие записи, начиная с предоставленной строки
текст	string	Выполняет полнотекстовый поиск всех записей

Дальнейшие действия

Проверка подлинности API

Если у вас возникнут какие-либо проблемы, мы здесь, чтобы помочь. Чтобы получить помощь или поддержку по проблеме с продуктом, отправьте запрос в службу поддержки.

Поделиться через