Trabajar con la API de Places en Microsoft Graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

La API de Places en Microsoft Graph proporciona una manera unificada de administrar e interactuar con espacios físicos, como edificios, salas, escritorios y áreas de trabajo, dentro de una organización.

Tipos compatibles

Los siguientes tipos se admiten en la API de Places.

Tipos de lugares

El lugar representa diferentes tipos de espacio dentro de un espacio empresarial. Un objeto de ubicación puede ser uno de los siguientes tipos.

Tipo de lugar Detalles
Edificio Representa un edificio dentro del inquilino y tiene propiedades como el nombre, la dirección y las coordenadas geográficas.
escritorio Representa escritorios individuales. Se debe agregar un escritorio a una sección. Las propiedades enriquecidas de la sección incluyen la dirección de correo electrónico, el modo y la accesibilidad.
suelo Representa un piso dentro de un edificio, incluidas propiedades como name, parentId y sortOrder. Un edificio es siempre el padre de un piso.
habitación Representa una habitación dentro del inquilino. Todas las salas deben estar asociadas a los buzones de Exchange. Una habitación se puede agregar a un piso o a una sección. Las propiedades enriquecidas de la sala incluyen una dirección de correo electrónico para la sala, accesibilidad, capacidad, dispositivo de audio, dispositivo de vídeo, etc.
roomList Una colección de habitaciones en el inquilino. Places admite roomList para garantizar que la reserva de salas funcione en el Buscador de salas en todos los clientes en todos los dispositivos, como Outlook clásico en equipos de escritorio y móviles.

Sin embargo, le recomendamos que confíe en los nuevos tipos de lugar y jerarquía si no usa roomFinder en el inquilino. Para obtener más información sobre roomList, consulte el tipo de recurso roomList .
section Representa una sección dentro de un piso, incluidas propiedades como nombre, parentId y etiqueta. Un piso es siempre el padre de una sección.
Área de trabajo Representa una colección de escritorios. Todas las áreas de trabajo deben estar asociadas a los buzones de Exchange. Se puede agregar un área de trabajo a una sección. Las propiedades enriquecidas de un área de trabajo incluyen una dirección de correo electrónico para el área de trabajo, modo, accesibilidad y capacidad.

Tipos de características de mapa

La entidad de mapa representa el mapa correspondiente de un lugar. Un objeto de entidad de mapa puede ser uno de los siguientes tipos.

Tipo de característica de mapa Detalles
buildingMap Representa un archivo de mapa asociado a un edificio en Places. Este objeto es la representación en formato IMDF de building.geojson.
fixtureMap Representa un archivo fixture.geojson en formato IMDF que define activos físicos móviles o semipermanentes dentro de un espacio. Estos activos respaldan funciones de utilidad, servicio o estéticas sin afectar la integridad estructural.
footprintMap Representa un archivo footprint.geojson en formato IMDF que define la extensión física aproximada de un edificio al que se hace referencia.
levelMap Representa un archivo level.geojson en formato IMDF que define la estructura física del suelo dentro de un edificio.
sectionMap Representa un archivo section.geojson en formato IMDF que define secciones (como zonas o tabiques) en el piso de un edificio.
unitMap Representa un archivo unit.geojson en formato IMDF que define unidades (como habitaciones u oficinas) en un piso de un edificio.

Uso de la API de Places

La API de Places permite que las aplicaciones con los permisos de lectura o escritura adecuados interactúen con los objetos de lugar. Cada objeto de lugar incluye propiedades fundamentales como id, placeId y displayName. Los tipos más avanzados, como salas, áreas de trabajo y escritorios, ofrecen más propiedades, como mode, emailAddress y deviceInformation.

Las API de mapa en Places permiten que las aplicaciones con los permisos de lectura o escritura adecuados interactúen con los objetos de entidad de mapa. Cada objeto de entidad de mapa incluye propiedades fundamentales como id y otras propiedades como placeId, geometry y display_point.

Las descripciones detalladas de cada tipo están disponibles en sus respectivas secciones de documentación.

Requisitos previos para la lista de Places y las API descendientes

Antes de poder usar las API List place objects o place: descendants, debe asegurarse de que la configuración de Places está configurada correctamente en el entorno de Microsoft 365; de lo contrario, estas API no devuelven ningún lugar a menos que se completen los siguientes pasos de configuración:

  1. Descargue y conéctese al módulo de PowerShell MicrosoftPlaces . Para obtener más información, consulte Connect-MicrosoftPlaces.
  2. Haga visibles los lugares habilitando los edificios con el siguiente comando. Para obtener más información, consulte Set-PlacesSettings. 
    Set-PlacesSettings -EnableBuildings 'Default:true'

Casos de uso comunes

En la tabla siguiente se enumeran algunos de los usos comunes de la API de Places.

Caso de uso Recurso de REST Vea también
Crear y administrar un lugar lugar Métodos de colocación
Interactuar con espacios de lugar como edificio, piso, sección, sala, lista de salas, área de trabajo o escritorio lugar Métodos de colocación
Lugares de Upsert lugar Lugares de Upsert
Ingerir el archivo de mapa de un edificio Edificio Ingerir archivo de asignación
Niveles de lista en un edificio levelMap Niveles de lista
Enumerar huellas en un edificio footprintMap Enumerar huellas
Obtener y eliminar un buildingMap buildingMap métodos buildingMap
Crear y administrar un unitMap unitMap métodos unitMap
Crear y administrar un fixtureMap fixtureMap Métodos fixtureMap
Crear y administrar un sectionMap sectionMap Métodos sectionMap

Comparación de las API de Places con findRooms y findRoomLists

Las funciones findRooms y findRoomLists admiten búsquedas similares para salas y listas de salas de un espacio empresarial. En la tabla siguiente se comparan la API de lugares y estas funciones.

Nota:

Las funciones findRooms y findRoomLists están obsoletas.

API de Places Funciones findRooms y findRoomLists (en desuso)
Obtiene todas las salas o listas de salas de un espacio empresarial y todas las salas de una lista de salas. Obtiene todas las salas o listas de salas de un espacio empresarial y todas las salas de una lista de salas.
List puede devolver más de 100 salas en un espacio empresarial. findRooms devuelve hasta las primeras 100 salas de un espacio empresarial.
Admite la obtención de una sala individual o una lista de salas en un espacio empresarial. No admite la obtención de una sala individual o una lista de salas en un espacio empresarial.
Define las entidades específicas de room y roomList que especifican un conjunto de propiedades más completo, además del nombre para mostrar y la dirección SMTP. Cada sala y lista de salas es de un tipo emailAddress más ligero que especifica solo el nombre para mostrar y la dirección SMTP.
Solo admite escenarios organizativos con permisos delegados (solo para cuentas de trabajo o escuela) o de aplicación. Solo admite escenarios organizativos con permisos delegados o de aplicación.
Admite la actualización de una sala individual o una lista de salas de un espacio empresarial. No admite la actualización de una sala individual o una lista de salas de un espacio empresarial.

Pasos siguientes

Use las API de Microsoft Graph Places para interactuar con diferentes entidades de lugar. Para obtener más información:

  • Explore los recursos y los métodos que son más útiles para su escenario.
  • Pruebe la API en el Probador de Graph.
  • Last updated on