Поиск устройств по тегу APIFind devices by tag 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

Поиск машин по тегу.Find Machines by Tag.
startswith запрос поддерживается.startswith query is supported.

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

  1. Ограничения скорости для этого API : 100 вызовов в минуту и 1500 вызовов в час.Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

РазрешенияPermissions

Для вызова этого API требуется одно из следующих разрешений.One of the following permissions is required to call this API. Дополнительные дополнительные информации, в том числе о выборе разрешений, см. в этой ссылке: Использование API endpoint Defender для Microsoft DefenderTo learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs

Тип разрешенияPermission type РазрешениеPermission Имя отображения разрешенийPermission display name
ПриложениеApplication Machine.Read.AllMachine.Read.All 'Read all machine profiles''Read all machine profiles'
ПриложениеApplication 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:

  • В ответ будут включены только устройства, к которые пользователь имеет доступ на основе параметров группы устройств (см. дополнительные сведения о создании и управлении группами устройств).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)
  • Пользователю необходимо иметь по крайней мере следующее разрешение на роль: "Просмотр данных" (см. создание и управление ролями для получения дополнительных сведений)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 /api/machines/findbytag?tag={tag}&useStartsWithFilter={true/false}

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

ИмяName ТипType ОписаниеDescription
АвторизацияAuthorization StringString Bearer {token}.Bearer {token}. Обязательное поле.Required.

Запрос параметров URIRequest URI parameters

ИмяName ТипType ОписаниеDescription
tagtag StringString Имя тега.The tag name. Обязательное поле.Required.
useStartsWithFilteruseStartsWithFilter BooleanBoolean При наборе true поиск будет находить все устройства с именем тега, которое начинается с данного тега в запросе.When set to true, the search will find all devices with tag name that starts with the given tag in the query. Значение по умолчанию: false.Defaults to false. Необязательное поле.Optional.

Тело запросаRequest body

переменная EmptyEmpty

ОткликResponse

Если успешно — 200 ОК со списком машин в теле отклика.If successful - 200 OK with list of the machines in the response body.

ПримерExample

ЗапросRequest

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

GET https://api.securitycenter.microsoft.com/api/machines/findbytag?tag=testTag&useStartsWithFilter=true