在 Microsoft Graph 中使用 Places API

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。不支持在生产应用程序中使用这些 API。若要确定 API 是否在 v1.0 中可用，请使用版本选择器。

Microsoft Graph 中的 Places API 提供了一种统一的方式来管理和与组织中的物理空间（如建筑物、会议室、办公桌和工作区）交互。

支持的类型

Places API 支持以下类型。

放置类型

Place 表示租户中的不同空间类型。 place 对象可以是以下类型之一。

放置类型	详细信息
建筑	表示租户中的建筑物，具有名称、地址和地理坐标等属性。
书桌	表示单个办公桌。必须将桌面添加到分区。部分的丰富属性包括电子邮件地址、模式和辅助功能。
地板	表示建筑物中的楼层，包括 name、 parentId 和 sortOrder 等属性。建筑物始终是楼层的父级。
房间	表示租户中的聊天室。所有会议室都必须与 Exchange 邮箱关联。可将房间添加到楼层或分区。会议室的丰富属性包括会议室的电子邮件地址、辅助功能、容量、音频设备、视频设备等。
roomList	租户中的会议室集合。 Places支持 roomList，以确保会议室查找器在所有设备上的所有客户端（如跨桌面和移动设备的经典 Outlook）中都可以进行房间预订。但是，如果不在租户中使用 roomFinder，我们建议你依赖新的位置类型和层次结构。有关 roomList 的详细信息，请参阅 roomList 资源类型。
section	表示楼层内的节，包括 name、 parentId 和 label 等属性。下层始终是分区的父级。
工作	表示桌子的集合。所有工作区都必须与 Exchange 邮箱关联。可将工作区添加到分区。工作区的丰富属性包括工作区、模式、辅助功能和容量的电子邮件地址。

映射特征类型

地图功能表示相应地点的地图。地图特征对象可以是以下类型之一。

地图功能类型	详细信息
buildingMap	表示与 Places 中的建筑物关联的映射文件。此对象是 building.geojson 的 IMDF 格式表示形式。
fixtureMap	表示 IMDF 格式的 fixture.geojson 文件，该文件定义空间中的可移动或半永久性物理资产。这些资产支持实用工具、服务或美观功能，而不会影响结构完整性。
footprintMap	表示 IMDF 格式的 footprint.geojson 文件，该文件定义所引用建筑物的大致物理范围。
levelMap	表示 IMDF 格式的 level.geojson 文件，该文件定义建筑物内的物理楼层结构。
sectionMap	表示 IMDF 格式的 section.geojson 文件，该文件定义建筑物楼层) (部分，例如区域或分区。
unitMap	表示 IMDF 格式的 unit.geojson 文件，该文件定义建筑物楼层) (单位，例如房间或办公室。

使用 Places API

Places API 使具有适当读取或写入权限的应用程序能够与放置对象交互。每个 place 对象都包含基本属性，例如 id、 placeId 和 displayName。更高级的类型（如会议室、工作区和办公桌）提供更多属性，例如 mode、 emailAddress 和 deviceInformation。

Places中的映射 API 使具有适当读取或写入权限的应用程序能够与地图功能对象进行交互。每个地图特征对象都包含基本属性（如 id）和其他属性（如 placeId、 geometry 和 display_point）。

每种类型的详细描述在各自的文档部分中提供。

Places列表和后代 API 的先决条件

在使用“列出位置对象或位置：后代 API”之前，必须确保在 Microsoft 365 环境中正确配置Places设置;否则，除非完成以下设置步骤，否则这些 API 不会返回任何位置：

下载并连接到 MicrosoftPlaces PowerShell 模块。有关详细信息，请参阅 Connect-MicrosoftPlaces。
使用以下命令启用建筑物，使位置可见。有关详细信息，请参阅 Set-PlacesSettings。
```
Set-PlacesSettings -EnableBuildings 'Default:true'
```

常见用例

下表列出了Places API 的一些常见用途。

用例	REST 资源	另请参阅
创建和管理位置	地方	place 方法
与场所空间（如建筑物、楼层、分区、房间、会议室列表、工作区或办公桌）交互	地方	place 方法
向上插入位置	地方	向上插入位置
引入建筑物的地图文件	建筑	引入映射文件
列出建筑物中的级别	levelMap	列表级别
列出建筑物中的占用空间	footprintMap	列出占用空间
获取和删除 buildingMap	buildingMap	buildingMap 方法
创建和管理 unitMap	unitMap	unitMap 方法
创建和管理 fixtureMap	fixtureMap	fixtureMap 方法
创建和管理 sectionMap	sectionMap	sectionMap 方法

比较Places API 与 findRooms 和 findRoomLists

findRooms 和 findRoomLists 函数支持对租户中的会议室和会议室列表进行类似的查找。下表比较了 places API 和这些函数。

注意

findRooms 和 findRoomLists 函数已弃用。

Places API	findRooms 和 findRoomLists 函数 (弃用)
获取租户中的所有会议室或会议室列表，以及会议室列表中的所有会议室。	获取租户中的所有会议室或会议室列表，以及会议室列表中的所有会议室。
列表可以返回租户中的 100 多个会议室。	findRooms 最多返回租户中的前 100 个会议室。
支持在租户中获取单个会议室或会议室列表。	不支持获取租户中的单个会议室或会议室列表。
除了显示名称和 SMTP 地址外，还定义 room 和 roomList 的特定实体，这些实体还指定了更丰富的属性集。	每个会议室和会议室列表都是一种较轻的电子邮件地址类型，仅指定显示名称和 SMTP 地址。
仅支持具有委派 (的组织方案，仅适用于工作或学校帐户) 或应用程序权限。	仅支持具有委派权限或应用程序权限的组织方案。
支持更新租户中的单个会议室或会议室列表。	不支持更新租户中的单个会议室或会议室列表。

后续步骤

使用 Microsoft Graph Places API 与不同的位置实体进行交互。了解详细信息：

探索对你的方案最有帮助的资源和方法。
尝试在 Graph 浏览器中使用 API。

反馈

此页面是否有帮助？

Last updated on 2025-10-16