Panoramica di analisi delle sale

Le prenotazioni delle camere, combinate con i dati dei sensori di presenza, offrono informazioni chiave per i gestori immobiliari e delle strutture per comprendere, analizzare e ottimizzare meglio l'utilizzo delle camere. Analizzando i dati delle prenotazioni che riflettono l'uso previsto delle camere insieme ai dati dei sensori che mostrano l'occupazione effettiva, i manager possono comprendere l'occupazione e il comportamento delle prenotazioni e identificare gli alti tassi di mancata presentazione. Questi dati aiutano i manager a prendere decisioni migliori sulla disponibilità delle sale.

Utilizzo della stanza in base all'intenzione di utilizzo

L'analisi delle sale usa i dati di prenotazione delle sale per tenere traccia dell'uso previsto delle stanze, fornendo informazioni dettagliate sull'occupazione pianificata delle stanze.

I dati delle prenotazioni vengono raccolti da tutte le cassette postali delle sale in Exchange associate a un tenant tramite un servizio che viene eseguito quotidianamente.

Utilizzo della stanza in base all'occupazione effettiva

L'analisi delle stanze utilizza i segnali di occupazione per rilevare l'effettiva presenza di persone, consentendo la misurazione dell'uso effettivo della stanza.

Attualmente, Microsoft supporta i seguenti segnali di occupazione:

  • Dispositivi Teams Rooms che partecipano a una riunione pianificata di Microsoft Teams usando i dati CRS (Call Record Summarized)
  • Pannello di Teams: dispositivi con archiviazione abilitata
  • Sensori di presenza o conteggio persone integrati di terze parti

Dettagli dei dati CRS

Il segnale riepilogato del record di chiamata contiene l'ora di inizio e di fine della riunione di Teams, che può essere usata per dedurre l'occupazione della stanza. Il segnale CallRecordSummarid è disponibile nei 4 giorni successivi all'ora dell'evento. E rimane disponibile per 28 giorni. CRS è attualmente supportato in queste aree principali: NAM, EUR, JPN e APAC. Se la tua organizzazione si trova all'interno di una di queste regioni supportate, il processo di onboarding dei dati CRS è completamente automatizzato. Non è richiesta alcuna azione manuale per l'integrazione dei dati. Quando il sistema rileva che l'utente si trova all'interno di un'area supportata, il flusso di dati viene avviato automaticamente.

Schema del set di dati

Colonna Tipo Descrizione
AadTenantId Stringa ID tenant del record. Viene usato per partizionare i dati nel contenitore tenant e viene eliminato dopo la partizione.
ActorId Stringa Microsoft Entra ID dell'attore, che può essere un utente o una stanza. In seguito viene usato per connettersi con l'ID stanza da Inventario sala per ottenere segnali dalle sale.
StartTime Stringa Ora di inizio della riunione, che indica che la sala è occupata.
EndTime Stringa Ora di fine riunione, che indica che la sala non è più occupata.
PrimarySmtp Stringa SMTP della persona o della stanza.
ActorIdType Stringa Tipo di ID attore, che deve essere Microsoft Entra ID. Questa stringa viene usata per il debug.
Tipo di attore Stringa Tipo di attore, che è sempre "utente" indipendentemente dalla persona o dalla stanza.
CreationTime Stringa Ora di creazione del record.
DatasetCategory Stringa Categoria del set di dati, che può essere commerciale o MSIT.
Tipo di segnale Stringa CallRecordSummarized, che è il tipo di segnale nel set di dati SIGS.

Connessione dei dati del sensore di presenza

Il collegamento dei sensori di presenza e di conteggio delle persone avviene in quattro fasi.

  • Onboarding del dispositivo.
  • Caricamento dei dati di telemetria.
  • Inserimento di dati di telemetria in tempo reale.
  • Verifica che i dati siano disponibili in Places.

Onboarding del dispositivo

Il primo passaggio prevede il caricamento di un file CSV con i metadati del dispositivo, incluso il modo in cui i dispositivi vengono mappati a un PlaceId in Microsoft Places. Questo passaggio consente di contestualizzare i dati di telemetria quando raggiungono Places.

Il diagramma seguente mostra come eseguire l'onboarding di dispositivi e sensori in Places.

Diagramma che mostra come eseguire l'onboarding di dispositivi e sensori in Microsoft Places.

Prima di tutto, è necessario preparare i dati del dispositivo.

  • Scarica le informazioni sui luoghi da Microsoft Places. Installare prima di tutto PowerShell 7 eseguendo il cmdlet di PowerShell seguente. Per altre informazioni su PowerShell in Windows, vedere Installazione di PowerShell in Windows.

PowerShell

Install-Module -Name ExchangeOnlineManagement
Import-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline

First, the device data needs to be prepared.

- Download place information from Microsoft Places. First, install **PowerShell 7** by running the following PowerShell cmdlet. To learn more about PowerShell on Windows, see [Installing PowerShell on Windows](/powershell/scripting/install/installing-powershell-on-windows).

### PowerShell

```powershell
Install-Module -Name ExchangeOnlineManagement
Import-Module -Name ExchangeOnlineManagement
Connect-ExchangeOnline
  • Aprire PowerShell come amministratore ed eseguire il comando di PowerShell di ExchangeOnline seguente per verificare se l'account dispone del ruolo TenantPlacesManagement necessario e per assicurarsi che il nome utente sia elencato.

PowerShell

Get-ManagementRoleAssignment -Role TenantPlacesManagement -GetEffectiveUsers
  • Se si dispone delle autorizzazioni corrette, dovrebbero essere visualizzati il nome e il ruolo assegnato seguenti.

    • Nome: PlacesAdmin
    • Ruolo assegnato: TenantPlacesManagement
  • Per ottenere il PlaceId degli edifici, aprire una nuova finestra di PowerShell ed eseguire il cmdlet di Windows PowerShell seguente.

PowerShell

Install-Module -Name MicrosoftPlaces -AllowPrerelease -Force
Connect-MicrosoftPlaces
  • Eseguire i seguenti comandi per scaricare l'elenco dei piani e delle stanze.

PowerShell

$buildingName = ""
$allPlaces = Get-PlaceV3 | Select-Object PlaceId, DisplayName, Type, ParentId
$building = $allPlaces | Where-Object { $_.DisplayName -eq $buildingName -and $_.Type -eq "Building" }
$floors = $allPlaces | Where-Object { $_.ParentId -eq $building.PlaceId }
$spacesAndRooms = $floors | ForEach-Object {
    $floor = $_;
    $allPlaces | Where-Object { $_.ParentId -eq $floor.PlaceId }
}
$places = @()
$floors | ForEach-Object { $places += $_ }
$spacesAndRooms | ForEach-Object { $places += $_ }
$outputPath = 'C:\places.csv'
$places | Select-Object PlaceId, DisplayName, Type | Export-Csv -Path $outputPath -NoTypeInformation
  • Il file di output nel percorso del file CSV deve contenere le informazioni seguenti:
PlaceId DisplayName Tipo
5D275BBA-5D7D-487F-855E-75CD2943204F Piano 1 Pavimento
0FA1B1EB-6066-45EA-8F7C-09B4E8CC4E74 Sala Conf 1202/3455 (9) Room
  • Scaricare i metadati del dispositivo da una soluzione partner o dal sistema, inclusi tutti i dispositivi.
  • Usa uno script o mappa manualmente i dispositivi a PlaceId utilizzando il seguente formato di dati per PlacesDevice.
Colonna Descrizione Note Esempio
DeviceId (obbligatorio) Identificatore univoco del dispositivo (scelta consigliata: Manufacturer_DeviceUniqueId). Deve corrispondere all'ID dei dati di telemetria inviati. Manuf1_3455
DisplayName Nome visualizzato del dispositivo. Se applicabile, è possibile usare un nome descrittivo. Manuf1_3455
Descrizione Descrizione del dispositivo.
MacAddress Indirizzo MAC del dispositivo. Fornito dal fornitore (se disponibile).
Produttore (obbligatorio) Produttore del dispositivo. Fornito dall'amministratore IT. Manuf1
IPV4Address Indirizzo IPV4 del dispositivo. Fornito dal fornitore (se disponibile).
Indirizzo IPV6 Indirizzo IPV6 del dispositivo. Fornito dal fornitore, se disponibile.
PlaceId (obbligatorio) PlaceId a cui è mappato il dispositivo in Places. L'amministratore IT esegue il mapping di DeviceID al campo DisplayName da un elenco di sale. 76FE540F-01A9-425E-ACD5-5D7D1DA44FBF
Tag Elenco di tag personalizzati associati al dispositivo per facilitare la ricerca. ["IsVirtual_False", "Building_121"]
Sensor.SensorId (obbligatorio) Identificatore univoco di un sensore all'interno del dispositivo. Deve essere incluso nel payload di telemetria standard. PeopleCount, Occupancy
Sensor.DisplayName Il nome del display del sensore. Puoi usare un nome descrittivo (se applicabile). Occupancy, PeopleCount
Sensor.SensorType (obbligatorio) Il tipo di sensore. Elenco convalidato (vedere gli esempi). Graffetta
Sensor.PlaceId Identificatore univoco del luogo servito dal sensore (è necessario fornire queste informazioni solo se il sensore si trova in una posizione diversa da quella in cui si trova il dispositivo). 76FE540F-01A9-425E-ACD5-5D7D1DA44FBF

Linee guida generali per dispositivi e sensori

  • È consigliabile specificare il DeviceId come Manufacturer_DeviceUniqueId. Tuttavia, nei casi in cui i partner non possono inviare dati di telemetria a livello di dispositivo (ad esempio, combinano i dati di telemetria da più dispositivi), è possibile creare un ID dispositivo virtuale come Manufacturer_Building_VirtualDeviceId. In questo caso, VirtualDeviceId può essere una chiave naturale di uno spazio. Se il cliente fornisce il VirtualDeviceId, è necessario includere le informazioni sui dispositivi fisici da cui viene calcolata la telemetria. Le informazioni sul dispositivo fisico possono essere contenute in tag.

  • Se Sensor.SensorType è univoco per un dispositivo, è sufficiente specificare SensorType. Nei casi in cui sono presenti più flussi di dati per un particolare tipo di sensore per un dispositivo, è necessario un SensorId univoco. SensorType e SensorId, nella maggior parte dei casi, sono PeopleCount, Occupancy e così via, a meno che SensorType non sia univoco per un dispositivo. In questo caso, SensorId è SensorType_SomeUnique identificatore.

Una volta preparati i metadati del dispositivo, le informazioni sul dispositivo possono essere caricate in Microsoft Places nei modi seguenti.

  • Uso dei cmdlet di PowerShell
  • Uso delle API di Microsoft Graph

Uso dei cmdlet di PowerShell

Per gestire singolarmente i dispositivi, è possibile usare direttamente i cmdlet di PowerShell per Microsoft Places. Per altre informazioni sui cmdlet di Places, vedere il modulo cmdlet di Microsoft Places per PowerShell.

Nota

Per eseguire i cmdlet, è necessario che sia assegnato il ruolo TenantPlacesManagement.

Nome del cmdlet Descrizione Parametri
New-PlaceDevice Crea un nuovo dispositivo DeviceId (obbligatorio), DisplayName, Descrizione, MACAddress, Produttore (obbligatorio), IPV4Address, IPV6Address, PlaceId (obbligatorio), Tag, Sensori (obbligatorio)
Remove-PlaceDevice Elimina un dispositivo ID (obbligatorio)
Set-PlaceDevice Aggiornamenti di un dispositivo ID (obbligatorio), DeviceId (obbligatorio), DisplayName, Description, MACAddress, Manufacturer (obbligatorio), IPV4Address, IPV6Address, PlaceId, Tag, Sensori (obbligatorio)
Get-PlaceDevice ottiene un dispositivo Id, filtro, inizio
  • Aprire PowerShell 7 (non come amministratore).

  • Installare Microsoft Places eseguendo il cmdlet di Windows PowerShell seguente. Per ulteriori informazioni sull'installazione Microsoft Places, vedere il Microsoft Places PowerShell Gallery.

PowerShell

Install-Module -Name MicrosoftPlaces -AllowPrerelease -Force
  • Importare il modulo di Microsoft Places eseguendo il cmdlet di Windows PowerShell seguente.

PowerShell

Import-Module -Name MicrosoftPlaces
  • Dopo aver installato e importato il modulo, connettersi al modulo Microsoft Places eseguendo il cmdlet di PowerShell Places seguente.

PowerShell

Connect-MicrosoftPlaces
  • Usa New-PlaceDevice esempio di cmdlet mostrato di seguito per aggiungere un dispositivo. Il parametro Sensors è un oggetto di tipo MicrosoftPlaces.PlacesDevices.Sensor con i campi indicati in precedenza.

PowerShell

New-PlaceDevice -DeviceId "contoso_9D6816" -DisplayName "Contoso 9D6816 Device" -Description "Contoso 9D6816 Device" -MACAddress "00:0A:95:9D:68:16" -Manufacturer "Contoso" -IPV4Address "192.168.1.100" -IPV6Address "2001:db8::ff00:42:8329" -PlaceId "acfa3bc0-2b83-425b-8910-84a0250e9671" -Tags "BuildingA" -Sensors (New-Object MicrosoftPlaces.PlacesDevices.Sensor -Property @{SensorType="occupancy"})
  • Usare Get-PlaceDevice per visualizzare l'elenco dei dispositivi. Per impostazione predefinita, restituisce 10 dispositivi. Per restituire più dispositivi, aggiungi il -top parametro come mostrato di seguito.

PowerShell

Get-PlaceDevice -top 100
  • Usare Set-PlaceDevice per aggiornare un dispositivo con l'ID esistente.

PowerShell

Set-PlaceDevice -Id "e5a216ff-1d32-4647-8dab-a2523ee5796e" -DeviceId "contoso_7D6816" -DisplayName "Contoso 7D6816 Device" -Description "Contoso 9D6816 Device" -MACAddress "00:0A:95:9D:68:16" -Manufacturer "Contoso" -IPV4Address "192.168.1.100" -IPV6Address "2001:db8::ff00:42:8329" -PlaceId "acfa3bc0-2b83-425b-8910-84a0250e9671" -Tags "BuildingA" -Sensors (New-Object MicrosoftPlaces.PlacesDevices.Sensor -Property @{SensorType="peopleCount"})
  • Usare Remove-PlaceDevice per eliminare un dispositivo.

PowerShell

Remove-PlaceDevice -Id "e5a216ff-1d32-4647-8dab-a2523ee5796e"

Uso delle API di Microsoft Graph

Per modificare il processo o automatizzare e integrare con i sistemi esistenti, è possibile usare le API di Microsoft Graph.

Per usare le API, segui questa procedura.

  • Creare la registrazione di un'app in Microsoft Entra.im. Per altre informazioni sulle autorizzazioni PlaceDeviceRead.All e PlaceDevice.ReadWrite.All, vedere le informazioni di riferimento sulle autorizzazioni di Microsoft Graph.

  • Crea e distribuisci un'applicazione per sincronizzare le informazioni sui dispositivi tra Microsoft Places e i tuoi partner.

Per altre informazioni sui dispositivi sensore, vedere le API di Microsoft Graph e la documentazione sui dispositivi seguenti:

Dispositivo di esempio

PowerShell

POST https://graph.microsoft.com/beta/workplace/sensorDevices
{
    "deviceId": "contoso_9D6821_occ_new",
    "displayName": "Contoso 9D6816 Device",
    "description": "Contoso 9D6816 Device",
    "macAddress": "00:0A:95:9D:68:16",
    "manufacturer": "Contoso",
    "ipV4Address": "192.168.1.100",
    "ipV6Address": "2001:db8::ff00:42:8329",
    "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671",
    "tags": [
        "BuildingA",
        "Floor 3",
        "Room 300",
        "Conference Room"
    ],
    "sensors": [
        {
            "sensorId": "Occupancy",
            "displayName": null,
            "sensorType": "occupancy",
            "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671"
        }
    ]
}

Esempio

PowerShell

GET
https://graph.microsoft.com/beta/workplace/sensorDevices/<workplacesensordevice-id>

GET
https://graph.microsoft.com/beta/workplace/sensorDevices/8e404458-e9b1-4153-b6b5-4858ccee1486

Risposta di esempio

PowerShell

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#workplace/sensorDevices/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET workplace/sensorDevices('<guid>')?$select=description,deviceId",
    "id": "8e404458-e9b1-4153-b6b5-4858ccee1486",
    "deviceId": "contoso_9D6821_occ_new",
    "displayName": "Contoso 9D6816 Device",
    "description": "Contoso 9D6816 Device",
    "macAddress": "00:0A:95:9D:68:16",
    "manufacturer": "Contoso",
    "ipV4Address": "192.168.1.100",
    "ipV6Address": "2001:db8::ff00:42:8329",
    "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671",
    "tags": [
        "BuildingA",
        "Floor 3",
        "Room 300",
        "Conference Room"
    ],
    "sensors": [
        {
            "sensorId": "Occupancy",
            "displayName": null,
            "sensorType": "occupancy",
            "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671"
        }
    ]
}

Esempio

PowerShell

PATCH https://graph.microsoft.com/beta/workplace/sensorDevices/8e404458-e9b1-4153-b6b5-4858ccee1486

{
    "deviceId": "contoso_9D6821_occ_new",
    "displayName": "Contoso 9D6816 Device New",
    "description": "Contoso 9D6816 Device",
    "macAddress": "00:0A:95:9D:68:16",
    "manufacturer": "Contoso",
    "ipV4Address": "192.168.1.100",
    "ipV6Address": "2001:db8::ff00:42:8329",
    "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671",
    "tags": [
        "BuildingA",
        "Floor 3",
        "Room 300",
        "Conference Room"
    ],
    "sensors": [
        {
            "sensorId": "Occupancy",
            "displayName": null,
            "sensorType": "occupancy",
            "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671"
        }
    ]
}

Risposta di esempio

PowerShell

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#workplace/sensorDevices/$entity",
    "id": "8e404458-e9b1-4153-b6b5-4858ccee1486",
    "deviceId": "contoso_9D6821_occ_new",
    "displayName": "Contoso 9D6816 Device New",
    "description": "Contoso 9D6816 Device",
    "macAddress": "00:0A:95:9D:68:16",
    "manufacturer": "Contoso",
    "ipV4Address": "192.168.1.100",
    "ipV6Address": "2001:db8::ff00:42:8329",
    "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671",
    "tags": [
        "BuildingA",
        "Floor 3",
        "Room 300",
        "Conference Room"
    ],
    "sensors": [
        {
            "sensorId": "Occupancy",
            "displayName": null,
            "sensorType": "occupancy",
            "placeId": "acfa3bc0-2b83-425b-8910-84a0250e9671"
        }
    ]
}

Esempio

DELETE https://graph.microsoft.com/beta/workplace/sensorDevices/<workplaceSensorDevice-Id>

DELETE https://graph.microsoft.com/beta/workplace/sensorDevices/052062b9-38f6-48d4-a638-05a72c79419b

Caricamento dei dati di telemetria

Dopo l'onboarding dei dispositivi in Microsoft Places, è possibile eseguire un refill una tantum dei dati cronologici per popolare Places con i dati di telemetria cronologici. È quindi possibile configurare Places in modo da ricevere dati di telemetria continui dai dispositivi per rimanere sempre aggiornato.

Il diagramma seguente illustra il flusso di caricamento dei file di recupero informazioni (metà superiore) e il flusso continuo di telemetria del dispositivo (metà inferiore).

Diagramma che mostra come eseguire un refill una tantum dei dati cronologici in Microsoft Places.

Opzione 1: uso del cmdlet Push-Dataset

Microsoft Places accetta dati cronologici in uno schema e formato di file CSV specifici. È necessario esportare questi dati da un sistema esistente e quindi usare il cmdlet di PowerShell seguente per caricare i dati.

Nome del cmdlet Descrizione Parametri Esempio
Push-Dataset Carica il set di dati in ADLS. Tipo, percorso Push-Dataset -Type RoomOccupancy -Path C:\sensordata\

Nota

Il tipo può essere RoomOccupancy e PeopleCount. Il ruolo deve essere assegnato a TenantPlacesManagement. Per altre informazioni sui cmdlet di PowerShell, vedere la Microsoft Places PowerShell Gallery.

  • Aprire PowerShell 7 (non come amministratore).

  • Installare Microsoft Places eseguendo il cmdlet di Windows PowerShell seguente. Per ulteriori informazioni sull'installazione Microsoft Places, vedere il Microsoft Places PowerShell Gallery.

PowerShell

Install-Module –Name MicrosoftPlaces –AllowPrerelease –Force
  • Importare il modulo di Microsoft Places eseguendo il cmdlet di Windows PowerShell seguente.

PowerShell

Import-Module -Name MicrosoftPlaces
  • Connettersi al modulo Microsoft Places eseguendo il cmdlet di PowerShell Places seguente.

PowerShell

Connect-MicrosoftPlaces
  • Caricare il set di dati dalla posizione nel dispositivo (usando la cartella e il percorso) eseguendo il cmdlet di PowerShell Places seguente.

PowerShell

Push-Dataset -Type RoomOccupancy -Path <folder path>

Formato di file CSV per PeopleCount

Nome colonna Ordine delle colonne Comment Esempio
DeviceId 1 ID dispositivo. Manuf1_1202_3455
SensorId 2 ID sensore. PeopleCount
Valore 3 Numero intero senza segno. PeopleCount (qualsiasi numero intero senza segno, ad esempio 5).
IngestionTime 4 Timestamp dai dati di telemetria, in formato UTC. 2023-06-27T18:24:20.808Z
locationHint Stringa Informazioni aggiuntive per indicare la posizione del dispositivo. Edificio-1

CSV di esempio

PowerShell

19966d8e-4434-477a-a38a-2df5651cd90f,6afe1ea7-82aa-451c-b2e1-48e48ca39ec0,5,2023-06-27T18:24:20.808Z,building1
19966d8e-4434-477a-a38a-2df5651cd90f,6afe1ea7-82aa-451c-b2e1-48e48ca39ec0,5,2023-06-27T18:24:20.808Z,building1
457702f3-c58d-44fa-9d26-f153fcd27452,a7387ed0-b540-47b0-8170-bc9c80f6c5b9,5,2023-06-27T18:24:20.808Z,building1
457702f3-c58d-44fa-9d26-f153fcd27452,a7387ed0-b540-47b0-8170-bc9c80f6c5b9,5,2023-06-27T18:24:20.808Z,building1

Il formato di file CSV per l'occupazione

Nome colonna Ordine delle colonne Comment Esempio
DeviceId 1 ID dispositivo. Manuf1_1202_3455
SensorId 2 ID sensore. RoomOccupancy
Valore 3 Numero intero senza segno. Occupazione: vero o falso.
IngestionTime 4 Timestamp dai dati di telemetria, in formato UTC. 2023-06-27T18:24:20.808Z
locationHint Stringa Informazioni aggiuntive per indicare la posizione del dispositivo. Edificio-1

CSV di esempio

PowerShell

19966d8e-4434-477a-a38a-2df5651cd90f,6afe1ea7-82aa-451c-b2e1-48e48ca39ec0,true,2023-06-27T18:24:20.808Z,building1
19966d8e-4434-477a-a38a-2df5651cd90f,6afe1ea7-82aa-451c-b2e1-48e48ca39ec0,true,2023-06-27T18:30:20.808Z,building1
457702f3-c58d-44fa-9d26-f153fcd27452,a7387ed0-b540-47b0-8170-bc9c80f6c5b9,false,2023-06-27T18:40:20.808Z,building1
457702f3-c58d-44fa-9d26-f153fcd27452,a7387ed0-b540-47b0-8170-bc9c80f6c5b9,true,2023-06-27T18:45:20.808Z,building1

Opzione 2: automatizzare con l'API Graph di Microsoft

Per creare un'applicazione per automatizzare il caricamento dei dati di telemetria e per creare un'applicazione per automatizzare la registrazione e l'onboarding dei dispositivi, le API sono disponibili tramite Microsoft Graph.

Per usare le API, segui questa procedura.

  • Creare la registrazione di un'app in Microsoft Entra. Per altre informazioni sulle autorizzazioni PlaceDeviceRead.All e PlaceDevice.ReadWrite.All, vedere le informazioni di riferimento sulle autorizzazioni di Microsoft Graph.
  • Crea e distribuisci un'applicazione per sincronizzare i dati di telemetria tra Microsoft Places e i tuoi partner.
  • Usare l'API IngestTelemetry per inviare i dati sull'occupazione e sul numero di persone a Microsoft Places.

Per altre informazioni sull'inserimento della telemetria del sensore per un sensore aziendale e per altre informazioni sull'API IngestTelemetry, vedere workplaceSensorDevice: ingestTelemetry.

Per inviare i dati sull'occupazione e sul numero di persone a Microsoft Places utilizzando l'API Graph Microsoft

  • Scarica i dati dai sistemi esistenti come descritto in precedenza.
  • Preparare i dati di telemetria in base al seguente formato di dati di presenza.

Formato segnale-dati di presenza

Parametro Tipo Descrizione
Telemetria (obbligatorio) workplaceSensorDeviceTelemetry Raccolta dei dati di telemetria raccolti e segnalati da un sensore in un dispositivo della sala.
deviceId (obbligatorio) Stringa Identificatore univoco definito dall'utente del dispositivo fornito al momento della creazione. Non usare l'identificatore del dispositivo generato dal sistema. Utilizzare solo gli ID dispositivo di cui è stato eseguito l'onboarding usando il cmdlet new-device.
sensorId Stringa Identificatore univoco definito dall'utente del sensore nel dispositivo. Se il dispositivo dispone di più sensori dello stesso tipo, è necessario fornire la proprietà per identificare ogni sensore. Se il dispositivo dispone di un solo sensore di un tipo, la proprietà può essere omessa. Il valore predefinito è il tipo di sensore. Facoltativo.
boolValue (obbligatorio) Booleano Vero o falso a seconda che la stanza sia occupata o meno.
timestamp (obbligatorio) DateTimeOffset La data e l'ora in cui il sensore ha misurato e segnalato il suo valore. Il tipo di timestamp rappresenta le informazioni di data e ora usando il formato ISO 8601 ed è sempre in formato UTC. Ad esempio, la mezzanotte UTC del 1° gennaio 2024 è 2024-01-01T00:00:00Z.
sensorType (obbligatorio) workplaceSensorType Occupazione
LocationHint (obbligatorio) Stringa Informazioni aggiuntive usate per indicare la posizione del dispositivo.

People count data signal-data format

Parametro Tipo Descrizione
Telemetria (obbligatorio) workplaceSensorDeviceTelemetry Raccolta dei dati di telemetria raccolti e segnalati da un sensore in un dispositivo della sala.
deviceId (obbligatorio) Stringa Identificatore univoco definito dall'utente del dispositivo fornito al momento della creazione. Non usare l'identificatore del dispositivo generato dal sistema. Utilizzare solo gli ID dispositivo di cui è stato eseguito l'onboarding usando il cmdlet new-device.
sensorId Stringa Identificatore univoco definito dall'utente del sensore nel dispositivo. Se il dispositivo dispone di più sensori dello stesso tipo, è necessario fornire la proprietà per identificare ogni sensore. Se il dispositivo dispone di un solo sensore di un tipo, la proprietà può essere omessa. Il valore predefinito è il tipo di sensore. Facoltativo.
intValue (obbligatorio) Int32 Numero di persone che occupano la stanza.
timestamp (obbligatorio) DateTimeOffset La data e l'ora in cui il sensore ha misurato e segnalato il suo valore. Il tipo di timestamp rappresenta le informazioni di data e ora usando il formato ISO 8601 ed è sempre in formato UTC. Ad esempio, la mezzanotte UTC del 1° gennaio 2024 è 2024-01-01T00:00:00Z.
sensorType (obbligatorio) workplaceSensorType peopleCount
LocationHint (obbligatorio) Stringa Informazioni aggiuntive per indicare la posizione del dispositivo.
  • Esegui l'API per inviare i dati a Microsoft Places.

Il comando seguente è una richiesta API di esempio per l'occupazione.

PowerShell

{
  "telemetry": [
    {
      "deviceId": "19966d8e-4434-477a-a38a-2df5651cd90f",
      "sensorid": "6afe1ea7-82aa-451c-b2e1-48e48ca39ec0",
      "sensorType": "occupancy",
      "boolValue": false,
      "timestamp": "2021-03-31T09:36:05.144Z",
      "locationHint": "building1"
    }
  ]
}

Il comando seguente è una richiesta API di esempio per il conteggio delle persone.

PowerShell

{
  "telemetry": [
    {
      "deviceId": "457702f3-c58d-44fa-9d26-f153fcd27452",
      "sensorid": "a7387ed0-b540-47b0-8170-bc9c80f6c5b9",
      "sensorType": "peopleCount",
      "intValue": 5,
      "timestamp": "2023-06-27T18:24:20.808Z",
      "locationHint": "building1"
    }
  ]
}

Inserimento di dati di telemetria in tempo reale

I connettori descritti nell'ambito necessitano dell'autorizzazione seguente per richiedere il servizio di inserimento di dati di telemetria in tempo reale.

  • PlaceDeviceTelemetry.ReadWrite.All

È necessario completare il consenso dell'amministratore o creare un'applicazione Microsoft Entra con l'autorizzazione in base all'architettura selezionata. Per altre informazioni sull'autorizzazione PlaceDeviceTelemetry.ReadWrite.All, vedere le informazioni di riferimento sulle autorizzazioni di Microsoft Graph.

Il diagramma seguente illustra l'architettura per l'inserimento di dati di telemetria.

Diagramma che mostra l'architettura usata per l'inserimento di dati di telemetria.

Per i clienti che scelgono questi tipi di integrazione, è necessario completare il consenso dell'amministratore a livello di tenant per concedere le autorizzazioni ai servizi partner per inserire le telemetrie per loro conto.

Se si usa l'interfaccia della riga di comando di PowerShell, Graph o Azure di Microsoft Graph, sostituire l'ID o l'ID app (dei comandi indicati) nelle pagine per creare un'entità servizio, quindi concedere il consenso dell'amministratore nell'entità servizio in Azure.

Screenshot che mostra la finestra di dialogo Autorizzazioni integrazione di Microsoft Places.

Se si usa un URL di consenso amministratore, sostituire l'ID app nella pagina con l'ID app partner, quindi aprirlo in un browser. Crea un'entità servizio e chiede di concedere il consenso dell'amministratore. Per concedere il consenso dell'amministratore, selezionare Accetta.

Screenshot della finestra di dialogo Autorizzazioni richieste dall'amministratore.

Microsoft Places rende disponibile un'API che accetta la telemetria in un formato standard esposto su Microsoft Graph. L'API accetta un batch di messaggi di telemetria.

  • Per l'architettura di tipo B, i clienti si affidano a un'integrazione fornita dai loro partner hardware ospitati in loco nell'ambiente del cliente.
  • Per l'architettura di tipo C, i clienti possono creare un processo a esecuzione prolungata o un processo basato su eventi, usando Funzioni di Azure, per chiamare le API di Microsoft Places per inviare dati di telemetria dell'edificio.
  • Entrambe le architetture di integrazione di tipo B e C richiedono ai clienti di creare una registrazione dell'app in Microsoft Entra, come illustrato nella figura seguente, e di fornire il consenso dell'amministratore con PlaceDeviceTelemetry.ReadWrite.All. Per altre informazioni sulle autorizzazioni esposte da Microsoft Graph, vedere le informazioni di riferimento sulle autorizzazioni di Microsoft Graph.

Screenshot che mostra la finestra di dialogo dell'applicazione Register asn.

Verificare che i dati siano disponibili in Microsoft Places

Verificare che i dati siano disponibili in Microsoft Places

Dopo l'onboarding dei dispositivi e l'API sta inserendo i dati in tempo reale del sensore, i report di analisi di Microsoft Places iniziano a popolarsi. Per sbloccare informazioni dettagliate che consentono di ottimizzare l'area di lavoro, verifica che i dati fluiscano nel dashboard di analisi entro 72 ore.