列出设备
本文内容
命名空间:microsoft.graph
重要
Microsoft Graph /beta
版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。
检索目录中的注册设备列表。
此 API 可用于以下国家级云部署 。
全局服务
美国政府 L4
美国政府 L5 (DOD)
由世纪互联运营的中国
✅
✅
✅
✅
权限
为此 API 选择标记为最低特权的权限。 只有在应用需要它时 ,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型 。 要了解有关这些权限的详细信息,请参阅 权限参考 。
权限类型
最低特权权限
更高特权权限
委派(工作或学校帐户)
Device.Read.All
Directory.Read.All、Directory.ReadWrite.All
委派(个人 Microsoft 帐户)
不支持。
不支持。
应用程序
Device.Read.All
Device.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
调用用户还必须具有以下Microsoft Entra角色 之一:
用户
目录读取器
目录作者
合规性管理员
设备管理器
应用程序管理员
安全读取者
安全管理员
特权角色管理员
云应用程序管理员
客户密码箱访问审批者
Dynamics 365管理员
Power BI 管理员
桌面分析管理员
Microsoft 托管桌面管理员
Teams 通信管理员
Teams 通信支持工程师
Teams 通信支持专家
Teams 管理员
合规数据管理员
安全操作员
Kaizala 管理员
全局读取者
目录审阅者
Windows 365 管理员
HTTP 请求
GET /devices
可选的查询参数
此方法支持 $count
、、$expand
、$filter
、$orderby
$search
、 $select
和 $top
OData 查询参数 来帮助自定义响应。 只有将 ConsistencyLevel 标头设置为 eventual
和 $count
时,才支持某些查询。 有关详细信息,请参阅 目录对象的高级查询功能 。
名称
说明
Authorization
持有者 {token}。 必填。 详细了解 身份验证和授权 。
ConsistencyLevel
最终。 当使用 $search
或 $filter
的特定用法时,需要此标头和 $count
。 有关使用 ConsistencyLevel 和 $count
的详细信息,请参阅 目录对象的高级查询功能 。
请求正文
请勿提供此方法的请求正文。
响应
如果成功,此方法在响应正文中返回 200 OK
响应代码和 device 对象集合。
示例
示例 1:获取设备列表
请求
以下示例显示了一个请求。
GET https://graph.microsoft.com/beta/devices
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Devices.GetAsync();
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta devices list
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
devices, err := graphClient.Devices().Get(context.Background(), nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DeviceCollectionResponse result = graphClient.devices().get();
const options = {
authProvider,
};
const client = Client.init(options);
let devices = await client.api('/devices')
.version('beta')
.get();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->devices()->get()->wait();
Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement
Get-MgBetaDevice
from msgraph import GraphServiceClient
graph_client = GraphServiceClient(credentials, scopes)
result = await graph_client.devices.get()
响应
以下示例显示了相应的响应。
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"value": [
{
"accountEnabled":true,
"deviceId":"00000000-0000-0000-0000-000000000000",
"deviceVersion":1,
"displayName":"contoso_Android",
"Manufacturer":"Google",
"Model":"Pixel 3a",
"operatingSystemVersion":"10.0"
}
]
}
示例 2:仅获取设备计数
请求
以下示例显示了一个请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual
,因为在请求中有 $count
。 有关使用 ConsistencyLevel 和 $count
的详细信息,请参阅 目录对象的高级查询功能 。
注意: $count
和$search
查询参数当前在 Azure AD B2C 租户中不可用。
GET https://graph.microsoft.com/beta/devices/$count
ConsistencyLevel: eventual
响应
以下示例显示了相应的响应。
HTTP/1.1 200 OK
Content-type: text/plain
294
示例 3:列出所有设备并仅返回其 ID 和 extensionAttributes 属性
请求
GET https://graph.microsoft.com/beta/devices?$select=id,extensionAttributes
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Devices.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","extensionAttributes" };
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta devices list --select "id,extensionAttributes"
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdevices "github.com/microsoftgraph/msgraph-beta-sdk-go/devices"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphdevices.DevicesRequestBuilderGetQueryParameters{
Select: [] string {"id","extensionAttributes"},
}
configuration := &graphdevices.DevicesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
devices, err := graphClient.Devices().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DeviceCollectionResponse result = graphClient.devices().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "extensionAttributes"};
});
const options = {
authProvider,
};
const client = Client.init(options);
let devices = await client.api('/devices')
.version('beta')
.select('id,extensionAttributes')
.get();
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Devices\DevicesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DevicesRequestBuilderGetRequestConfiguration();
$queryParameters = DevicesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","extensionAttributes"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->devices()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement
Get-MgBetaDevice -Property "id,extensionAttributes"
from msgraph import GraphServiceClient
from msgraph.generated.devices.devices_request_builder import DevicesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = DevicesRequestBuilder.DevicesRequestBuilderGetQueryParameters(
select = ["id","extensionAttributes"],
)
request_configuration = DevicesRequestBuilder.DevicesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.devices.get(request_configuration = request_configuration)
响应
以下示例显示了相应的响应。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#devices(id,extensionAttributes)",
"value": [
{
"id": "6a59ea83-02bd-468f-a40b-f2c3d1821983",
"extensionAttributes": {
"extensionAttribute1": null,
"extensionAttribute2": null,
"extensionAttribute3": null,
"extensionAttribute4": null,
"extensionAttribute5": null,
"extensionAttribute6": null,
"extensionAttribute7": null,
"extensionAttribute8": null,
"extensionAttribute9": null,
"extensionAttribute10": null,
"extensionAttribute11": null,
"extensionAttribute12": null,
"extensionAttribute13": null,
"extensionAttribute14": null,
"extensionAttribute15": null
}
}
]
}
示例 4:使用$filter和$top获取一个显示名称以“a”开头的设备,包括返回的对象计数
请求
以下示例显示了一个请求。 此请求需要将 ConsistencyLevel 标头设置为 eventual
和 $count=true
查询字符串,因为请求同时具有 $orderby
和 $filter
查询参数。 有关使用 ConsistencyLevel 和 $count
的详细信息,请参阅 目录对象的高级查询功能 。
注意: $count
和$search
查询参数当前在 Azure AD B2C 租户中不可用。
GET https://graph.microsoft.com/beta/devices?$filter=startswith(displayName, 'a')&$count=true&$top=1&$orderby=displayName
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Devices.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "startswith(displayName, 'a')";
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.QueryParameters.Top = 1;
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta devices list --top "1" --filter "startswith(displayName, 'a')" --count "true" --orderby "displayName" --consistency-level "eventual"
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdevices "github.com/microsoftgraph/msgraph-beta-sdk-go/devices"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestFilter := "startswith(displayName, 'a')"
requestCount := true
requestTop := int32(1)
requestParameters := &graphdevices.DevicesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Count: &requestCount,
Top: &requestTop,
Orderby: [] string {"displayName"},
}
configuration := &graphdevices.DevicesRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
devices, err := graphClient.Devices().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DeviceCollectionResponse result = graphClient.devices().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "startswith(displayName, 'a')";
requestConfiguration.queryParameters.count = true;
requestConfiguration.queryParameters.top = 1;
requestConfiguration.queryParameters.orderby = new String []{"displayName"};
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
const options = {
authProvider,
};
const client = Client.init(options);
let devices = await client.api('/devices')
.version('beta')
.header('ConsistencyLevel','eventual')
.filter('startswith(displayName, \'a\')')
.orderby('displayName')
.top(1)
.get();
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Devices\DevicesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DevicesRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = DevicesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(displayName, 'a')";
$queryParameters->count = true;
$queryParameters->top = 1;
$queryParameters->orderby = ["displayName"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->devices()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement
Get-MgBetaDevice -Filter "startswith(displayName, 'a')" -CountVariable CountVar -Top 1 -Sort "displayName" -ConsistencyLevel eventual
from msgraph import GraphServiceClient
from msgraph.generated.devices.devices_request_builder import DevicesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = DevicesRequestBuilder.DevicesRequestBuilderGetQueryParameters(
filter = "startswith(displayName, 'a')",
count = True,
top = 1,
orderby = ["displayName"],
)
request_configuration = DevicesRequestBuilder.DevicesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.devices.get(request_configuration = request_configuration)
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#devices",
"@odata.count":1,
"value":[
{
"accountEnabled":true,
"deviceId":"00000000-0000-0000-0000-000000000000",
"deviceVersion":1,
"displayName":"a_device_1",
"Manufacturer":"Google",
"Model":"Pixel 3a",
"operatingSystemVersion":"10.0",
"hostNames":[]
},
{
"accountEnabled":true,
"deviceId":"00000000-0000-0000-0000-000000000001",
"deviceVersion":1,
"displayName":"a_device_1",
"Manufacturer":"Microsoft",
"Model":"Surface",
"operatingSystemVersion":"windows10EnterpriseN",
"hostNames":["contoso.com", "device_1"]
}
]
}
示例 5:使用$search获取显示名称包含字母“Android”的设备,包括返回的对象计数
请求
以下示例显示了一个请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual
,因为在请求中有 $search
和 $count=true
查询字符串。 有关使用 ConsistencyLevel 和 $count
的详细信息,请参阅 目录对象的高级查询功能 。
注意: $count
和$search
查询参数当前在 Azure AD B2C 租户中不可用。
GET https://graph.microsoft.com/beta/devices?$search="displayName:Android"&$count=true
ConsistencyLevel: eventual
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/beta/$metadata#devices",
"@odata.count":1396,
"value":[
{
"accountEnabled":true,
"deviceId":"00000000-0000-0000-0000-000000000000",
"deviceVersion":1,
"displayName":"contoso_Android",
"Manufacturer":"Google",
"Model":"Pixel 3a",
"operatingSystemVersion":"10.0",
"hostNames":[]
}
]
}
示例 6:使用 extensionAttributes 上的筛选器获取设备
请求
以下示例显示了一个请求。 此请求要求将 ConsistencyLevel 标头设置为 ,并将$count=true
查询字符串设置为 eventual
,因为 extensionAttributes 属性仅支持$filter
高级查询参数。 有关使用 ConsistencyLevel 和 $count
的详细信息,请参阅 目录对象的高级查询功能 。
注意: $count
和$search
查询参数当前在 Azure AD B2C 租户中不可用。
GET https://graph.microsoft.com/beta/devices?$filter=extensionAttributes/extensionAttribute1 eq 'BYOD-Device'&$count=true
ConsistencyLevel: eventual
// Code snippets are only available for the latest version. Current version is 5.x
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Devices.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'";
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta devices list --filter "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'" --count "true" --consistency-level "eventual"
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphdevices "github.com/microsoftgraph/msgraph-beta-sdk-go/devices"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestFilter := "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'"
requestCount := true
requestParameters := &graphdevices.DevicesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Count: &requestCount,
}
configuration := &graphdevices.DevicesRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
devices, err := graphClient.Devices().Get(context.Background(), configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
DeviceCollectionResponse result = graphClient.devices().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'";
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
const options = {
authProvider,
};
const client = Client.init(options);
let devices = await client.api('/devices')
.version('beta')
.header('ConsistencyLevel','eventual')
.filter('extensionAttributes/extensionAttribute1 eq \'BYOD-Device\'')
.get();
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Devices\DevicesRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new DevicesRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = DevicesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'";
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->devices()->get($requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement
Get-MgBetaDevice -Filter "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'" -CountVariable CountVar -ConsistencyLevel eventual
from msgraph import GraphServiceClient
from msgraph.generated.devices.devices_request_builder import DevicesRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = DevicesRequestBuilder.DevicesRequestBuilderGetQueryParameters(
filter = "extensionAttributes/extensionAttribute1 eq 'BYOD-Device'",
count = True,
)
request_configuration = DevicesRequestBuilder.DevicesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.devices.get(request_configuration = request_configuration)
响应
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#devices",
"@odata.count": 1,
"value": [
{
"@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/6a59ea83-02bd-468f-a40b-f2c3d1821983/Microsoft.DirectoryServices.Device",
"id": "6a59ea83-02bd-468f-a40b-f2c3d1821983",
"accountEnabled": true,
"approximateLastSignInDateTime": "2021-10-21T06:36:56Z",
"createdDateTime": "2021-09-21T15:16:30Z",
"deviceId": "eab73519-780d-4d43-be6d-a4a89af2a348",
"displayName": "DESKTOP-LK3PESR",
"operatingSystem": "Windows",
"operatingSystemVersion": "10.0.19043.1237",
"alternativeSecurityIds": [
{
"type": 2,
"identityProvider": null,
"key": "WAA1ADAAOQA6AD...ADQAMwB5AGEAcQBnAD0A"
}
],
"extensionAttributes": {
"extensionAttribute1": "BYOD-Device",
"extensionAttribute2": null,
"extensionAttribute3": null,
"extensionAttribute4": null,
"extensionAttribute5": null,
"extensionAttribute6": null,
"extensionAttribute7": null,
"extensionAttribute8": null,
"extensionAttribute9": null,
"extensionAttribute10": null,
"extensionAttribute11": null,
"extensionAttribute12": null,
"extensionAttribute13": null,
"extensionAttribute14": null,
"extensionAttribute15": null
}
}
]
}