directoryObject: getByIds

命名空间:microsoft.graph

返回 ID 列表中指定的目录对象。 默认情况下,在 v1.0 中仅返回一部分用户属性。

该函数的一些常见用途是:

  • 解析函数返回的 ID (,这些函数) 如 getMemberObjects 或 getMemberGroups 的集合返回到其后备目录对象。
  • 将应用程序保存在外部存储中的 ID 解析到其后备目录对象。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Directory.Read.All 不可用。
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 Directory.Read.All 不可用。

重要

当应用程序查询返回 directoryObject 类型集合的关系时,如果它没有读取特定资源类型的权限,则会返回该类型的成员,但信息有限。 例如,仅返回对象类型和 ID 的 @odata.type 属性,而其他属性则指示为 null。 通过此行为,应用程序可以请求所需的最低特权权限,而不是依赖于 目录集。*权限。 有关详细信息,请参阅为不可访问的成员对象返回有限的信息。

HTTP 请求

POST /directoryObjects/getByIds

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-type application/json. 必需。

请求正文

在请求正文中,提供具有以下参数的 JSON 对象。

参数 类型 说明
ids String collection 要返回其对象的 ID 集合。 ID 是 GUID,由字符串表示。 最多可以指定 1000 个 ID。
types String collection 指定要搜索的资源集合集的资源类型集合。 如果未指定,则默认为 directoryObject,其包含目录中定义的所有资源类型。 可以在该集合中指定派生自 directoryObject 的任何对象,例如:用户、组、设备对象等。

若要搜索对云解决方案提供商合作伙伴组织的引用 ,请指定directoryObjectPartnerReference。 如果未指定,则默认为 directoryObject,其包含目录中定义的所有资源类型,对云解决方案提供商合作伙伴组织的引用除外。

这些值不区分大小写。

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 String 集合对象。

示例

请求

POST https://graph.microsoft.com/v1.0/directoryObjects/getByIds
Content-type: application/json

{
    "ids": [
        "84b80893-8749-40a3-97b7-68513b600544",
        "5d6059b6-368d-45f8-91e1-8e07d485f1d0",
        "0b944de3-e0fc-4774-a49a-b135213725ef",
        "b75a5ab2-fe55-4463-bd31-d21ad555c6e0"
    ],
    "types": [
        "user",
        "group",
        "device"
    ]
}

响应

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value": [
      {
        "@odata.type": "#microsoft.graph.user",
        "id": "84b80893-8749-40a3-97b7-68513b600544",
        "displayName": "Trevor Jones"
      },
      {
        "@odata.type": "#microsoft.graph.user",
        "id": "5d6059b6-368d-45f8-91e1-8e07d485f1d0",
        "displayName": "Billy Smith"
      },
      {
         "@odata.type": "#microsoft.graph.group",
         "id": "0b944de3-e0fc-4774-a49a-b135213725ef",
         "description": "Pineview School Staff",
         "groupTypes": [
             "Unified"
         ]
      },
      {
         "@odata.type": "#microsoft.graph.device",
         "id": "b75a5ab2-fe55-4463-bd31-d21ad555c6e0",
         "displayName": "e8ba4e98c000002",
         "deviceId": "4c299165-6e8f-4b45-a5ba-c5d250a707ff"
      }
    ]
}