API машин спискаList machines API

Применяется к: Microsoft Defender для конечной точкиApplies to: Microsoft Defender for Endpoint

Примечание

Если вы клиент правительства США, используйте URL-адреса, указанные в Microsoft Defender для конечных точек для государственных клиентов США.If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Совет

Для улучшения производительности можно использовать сервер ближе к географическому расположению:For better performance, you can use server closer to your geo location:

  • api-us.securitycenter.microsoft.comapi-us.securitycenter.microsoft.com
  • api-eu.securitycenter.microsoft.comapi-eu.securitycenter.microsoft.com
  • api-uk.securitycenter.microsoft.comapi-uk.securitycenter.microsoft.com

Описание APIAPI description

Извлекает коллекцию машин, которые связывались с облаком Microsoft Defender для конечной точки.Retrieves a collection of Machines that have communicated with Microsoft Defender for Endpoint cloud.
Поддерживает запросы OData V4.Supports OData V4 queries.
Запрос OData поддерживается $filter на: computerDnsName , , , , и lastSeen healthStatus osPlatform riskScore rbacGroupId .The OData's $filter query is supported on: computerDnsName, lastSeen, healthStatus, osPlatform, riskScore and rbacGroupId.
Примеры запросов OData с Defender для endpointSee examples at OData queries with Defender for Endpoint

ОграниченияLimitations

  1. Устройства можно получить в последний раз в соответствии с настроенным периодом хранения.You can get devices last seen according to your configured retention period.
  2. Максимальный размер страницы — 10 000.Maximum page size is 10,000.
  3. Ограничения скорости для этого API : 100 вызовов в минуту и 1500 вызовов в час.Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

РазрешенияPermissions

Тип разрешенияPermission type РазрешениеPermission Имя отображения разрешенийPermission display name
ApplicationApplication Machine.Read.AllMachine.Read.All 'Read all machine profiles''Read all machine profiles'
ApplicationApplication Machine.ReadWrite.AllMachine.ReadWrite.All 'Read and write all machine information''Read and write all machine information'
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) Machine.ReadMachine.Read 'Read machine information''Read machine information'
Делегированные (рабочая или учебная учетная запись)Delegated (work or school account) Machine.ReadWriteMachine.ReadWrite 'Read and write machine information''Read and write machine information'

Примечание

При получении маркера с помощью учетных данных пользователей:When obtaining a token using user credentials:

  • Пользователю необходимо иметь по крайней мере следующее разрешение на роль: "Просмотр данных" (см. создание и управление ролями для получения дополнительных сведений)The user needs to have at least the following role permission: 'View Data' (See Create and manage roles for more information)
  • Ответ будет включать только устройства, к которые пользователь имеет доступ на основе параметров группы устройств (см. дополнительные сведения о создании и управлении группами устройств).Response will include only devices, that the user have access to, based on device group settings (See Create and manage device groups for more information)

HTTP-запросHTTP request

GET https://api.securitycenter.microsoft.com/api/machines

Заголовки запросовRequest headers

ИмяName ТипType ОписаниеDescription
AuthorizationAuthorization СтрокаString Bearer {token}.Bearer {token}. Обязательное поле.Required.

Текст запросаRequest body

переменная EmptyEmpty

ОткликResponse

Если успешно и машины существуют — 200 ОК со списком машинных сущностями в теле.If successful and machines exists - 200 OK with list of machine entities in the body. Если нет недавних машин - 404 Не найдено.If no recent machines - 404 Not Found.

ПримерExample

ЗапросRequest

Ниже приведен пример запроса.Here is an example of the request.

GET https://api.securitycenter.microsoft.com/api/machines

ОткликResponse

Ниже приведен пример отклика.Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json
{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Machines",
    "value": [
        {
            "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
            "computerDnsName": "mymachine1.contoso.com",
            "firstSeen": "2018-08-02T14:55:03.7791856Z",
            "lastSeen": "2018-08-02T14:55:03.7791856Z",
            "osPlatform": "Windows10",
            "version": "1709",
            "osProcessor": "x64",
            "lastIpAddress": "172.17.230.209",
            "lastExternalIpAddress": "167.220.196.71",
            "osBuild": 18209,
            "healthStatus": "Active",
            "rbacGroupId": 140,
            "rbacGroupName": "The-A-Team",
            "riskScore": "Low",
            "exposureLevel": "Medium",
            "isAadJoined": true,
            "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
            "machineTags": [ "test tag 1", "test tag 2" ]
        }
        ...
    ]
}