Excel-Tabelle mit Powershell hochladen und Smap aktualisieren.

Diren Teke · 25. April

Ich habe ein Skript erstellt welches über PowerShell und der REST-API, Daten aus einer Excel-Tabelle holt, in ein Smap einfügt und diesen Smap aktualisiert.

Als Dankeschön an SmapOne veröffentliche ich diesen Skript.

<#
.SYNOPSIS
Nimmt Daten aus einer Excel-Datei und lädt sie auf SmapOne in einen Datenauswahlblock hoch und aktualisiert den entsprechenden Smap.

.DESCRIPTION
Dieses PowerShell-Skript, ist darauf ausgelegt, Daten aus einer Excel-Datei mit Hilfe der Rest-API von Smapone in einen Datenauswahlblock zu füllen und anschliessend ein Update der Smap durchzuführen.

.PARAMETER excelPath
Gibt den Pfad zur Excel-Datei an, die mit den hochzuladenden Daten.
Aufbau der Smap muss alle Spalten der Exceltabelle enthalten.
Benötigt Modul "Import-Excel" siehe .notes

.PARAMETER smapID
Gibt die ID der smapOne App an, die aus der Browser-URL der App entnommen werden kann.
SmapOne API -> Intern und AccessToken eingeben -> Datasource -> [GET] /DataSource/{dataSourceId} -> dataSourceID eingeben -> Try it out!

.PARAMETER dataSourceID
Gibt die Data Source ID an, die mit dem Smap verbunden ist.
SmapOne API -> Intern und AccessToken eingeben -> Datasource -> [GET] /DataSource -> Try it out!

.PARAMETER AccessToken
Gibt das Login-Token des smapOne Accounts an.
Smapone-Plattform -> Mein Profil -> Rest-API -> Token verwalten.

.INPUTS
Daten aus einer Excel-Datei.

.OUTPUTS
Ergebnisse der API-Aufrufe und des Datenupload-Prozesses.

.EXAMPLE
Ausführen dieses Skriptes führt zu einem Hochladen der Daten aus der Exceltabelle an die gewünschte Smap. Anschliessend wird ein Update an die Nutzer des Smaps durchgeführt.
Parameter des Smaps müssen angepasst werden/sein.

.LINK
Weitere Informationen zu SmapOne: https://www.smapone.com/
Platform zum erstellen der Smaps: https://platform.smapone.com/
Swagger zur SmapOne API: https://platform.smapone.com/Backend/swagger/ui/index
PowerShell Invoke-RestMethod: https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-restmethod

.NOTES
Datum: 05.01.2024
Autor: Diren Teke
Version: 1.0
Systemvoraussetzungen:
Das Skript kann ab PowerShell Version 5.1.X betrieben werden, bei Verionen unterhalb dieser ist die Funktionsweise eventuell nicht gewährleistet.
->Mit $PSVersionTable.Version kann in der PowerShell Console die aktuelle Version eingesehen werden.

Die vorinstallierte Version ab Windows 10 Systemen sollte 5.1.X sein.
Vor der Benutzung des Skrips muss sichergestellt werden, dass das Modul Import-Excel herruntergeladen wurden.
-> install-module -Name ImportExcel -Force
#>

<#
--------------------------------
Eingabe-Parameter
--------------------------------
#>
#Parameter für die Kommunikation mit der API setzen
param(
# Pfad zur Excel-Datei
[string]$excelPath = "Eingeben_Pfad",

# SmapID der Smap
[string]$smapID = "Eingeben_smapID",

# DataSourceID des Smaps
[string]$dataSourceID = "Eingabe_DataSource",

# Access-Token des Creator SmapAccounts
[string]$AccessToken = "Eingabe_AccessToken"
)

<#
--------------------------------
Headers-Definition
--------------------------------
#>
# Angaben zum Header als Array
$headers = @{
"Content-Type" = "application/json"
"Accept" = "application/json"
'Authorization' = "Basic $AccessToken"
}

<#
--------------------------------
Auslesen-Letzte-Smap-Version
--------------------------------
#>
# URL- REST-API-Informationen Informationen einer Smap abfragen.
$apiInformation = "https://platform.smapone.com/Backend/intern/DataSource/$($dataSourceID)?accesstoken=$($AccessToken)"

# Holen der Informationen des Smaps.
$SmapInformation = Invoke-RestMethod -Uri $apiInformation -Method Get -Headers $headers

# Letzte Version extrahieren.
$SmapVersion = $SmapInformation.latestVersion

# Ausgabe letzte Version.
Write-Output "Letzte Version $SmapVersion"

# Ausgabe des API-URL's welches die aktuelle Version des Smaps beinhalten muss.
Write-Output "URL Endpunkt: $apiEndpunkt"

<#
--------------------------------
Excel-Auslesen und umwandeln zu Json
--------------------------------
#>
# Excel-Daten mit dem Modul Import-Excel auslesen.
$excelData = Import-Excel $excelPath

# Ausgabe der Excel-Daten
$excelData | Format-Table

# Konvertierung der Daten von Excel zu Json. Array wird mit "," "@" zwingend definiert.
$jsonData =,@($excelData) | ConvertTo-Json

# Ausgabe des zu übermittelnden Json-Bodys. Muss ein Array sein!
Write-Output "Json-Body (Array) aus Jsondata an API: $jsonData"

<#
--------------------------------
REST-API-Aufruf
--------------------------------
#>
# URL- REST-API-Endpunkt für das Hochladen der Daten an die API.
$apiEndpunkt = "https://platform.smapone.com/Backend/intern/DataSource/$($dataSourceID)/Versions/$($SmapVersion)/Definition/Values?accesstoken=$($AccessToken)"

# URL- REST-API-Endpunkt-Update für das Aktualisieren des Smaps.
$apiEndpunktUpdate = "https://platform.smapone.com/Backend/intern/Smaps/$($smapID)/Versions/Current/DataSources/Update?updateEditVersion=true&accesstoken=$($AccessToken)"

# Ausgabe Rest-API Kommunikation startet als nächstes.
Write-Host "Vor Invoke-RestMethoden"

# Übermitteln des Json-Body (Array) mit den Daten aus der Excel an die API, unbedingt mit Unicode utf-8.
$datenAnAPI = Invoke-RestMethod -Uri $apiEndpunkt -Method Put -Body $jsonData -Headers $headers -ContentType "application/json; charset=utf-8"

# Ausgabe nach Übermittlung an die API.
Write-Output "Daten nach übermitteln an Smap: $datenAnAPI"

# Aktualisiern der Smap.
$updateSmap = Invoke-RestMethod -Uri $apiEndpunktUpdate -Method Put -Headers $headers -ContentType "application/json; charset=utf-8"

# Ausgabe nach Aktualisierung der API.
Write-Output "Nach update des Smaps: $updateSmap"

# Ausgabe das die Rest API kommunikation beendet ist.
Write-Host "Nach Invoke-RestMethoden"