Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.
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
-topparametro 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:
Per altre informazioni sulla visualizzazione dei dispositivi, vedere Elencare sensorDevices.
Per altre informazioni sulla creazione di un nuovo dispositivo, vedere Creare workplaceSensorDevice.
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"
}
]
}
- Per informazioni su come visualizzare un dispositivo specifico, vedere Ottenere workplaceSensorDevice.
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"
}
]
}
- Per altre informazioni sull'aggiornamento del dispositivo esistente, vedi workplaceSensorDevice.
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"
}
]
}
- Per altre informazioni sull'eliminazione di un dispositivo, vedere Eliminare workplaceSensorDevice.
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).
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.
Consenso dell'amministrazione: architettura di tipo A, connettore SaaS (hardware-partner-owned connector)
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.
- Questo si applica quando i provider di hardware hanno creato connettori SaaS multi-tenant (app single o multi-tenant). Per altre informazioni sui connettori multitenant, vedere Tenancy in Microsoft Entra ID.
- Ottenere l'ID app (GUID) dal partner che inserisce le telemetrie per conto del servizio.
- Creare un'entità servizio con l'ID app. È possibile scegliere tra diverse opzioni. Per ulteriori informazioni, vedere Creare un'applicazione aziendale da un'applicazione multi-tenant in Microsoft Entra ID.
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.
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.
Consenso dell'Amministrazione: architettura di tipo B e C, connettore in esecuzione in un ambiente on-site del cliente
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.
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.