Aufgaben-Python/courses/powershell/10_json_csv_xml_und_rest_apis

PS 10: JSON, CSV, XML & REST-APIs (Invoke-RestMethod) 🌐

Willkommen zu Modul 10 des PowerShell 7+ DevOps-Kurses!

In modernen Cloud- und DevOps-Architekturen sind REST-APIs und standardisierte Datenformate wie JSON, CSV und XML das Rückgrat der Systemintegration. PowerShell bietet mit Cmdlets wie Invoke-RestMethod, ConvertFrom-Json und dem [xml]-Typbeschleuniger erstklassige Werkzeuge zur Datenverarbeitung.

---

💡 1. Das Wichtigste in Kürze

A. Invoke-RestMethod vs. Invoke-WebRequest

• Invoke-WebRequest: Liefert das rohe HTTP-Antwortobjekt inklusive HTML, Statuscode und Raw-Content zurück.
• Invoke-RestMethod: Erkennt automatisch JSON/XML-Antworten und wandelt den Payload direkt in native PSCustomObject-Hierarchien um!

$headers = @{
    "Authorization" = "Bearer $env:API_TOKEN"
    "Content-Type"  = "application/json"
}

$response = Invoke-RestMethod -Uri "https://api.github.com/user/repos" -Headers $headers -Method GET
$response | Select-Object -Property name, stargazers_count, html_url

---

B. Die gefährliche Falle: ConvertTo-Json -Depth

Standardmäßig serialisiert ConvertTo-Json Objekte nur bis zu einer Verschachtelungstiefe von 2 Ebenen! Tiefere Objekte werden als String System.Collections.Hashtable abgeschnitten.

⚠️ DevOps-Best-Practice: Setze bei komplexen Datenstrukturen (z.B. Kubernetes-Configs oder Azure ARM Templates) immer explizit -Depth 10 oder höher!

$clusterConfig = @{
    cluster = @{
        network = @{
            subnets = @("10.0.1.0/24", "10.0.2.0/24")
        }
    }
}

# Falsch (Tiefe wird abgeschnitten):
$badJson = $clusterConfig | ConvertTo-Json

# Richtig (Verlustfreie Serialisierung):
$goodJson = $clusterConfig | ConvertTo-Json -Depth 10

---

C. CSV-Export ohne Metadaten-Müll

Beim Exportieren von Objekten in CSV-Dateien für Excel oder Berichte sorgt der Schalter -NoTypeInformation dafür, dass die lästige Typzeile (#TYPE System.Management.Automation.PSCustomObject) entfällt:

$servers | Select-Object Hostname, IP, Role | Export-Csv -Path "servers.csv" -Delimiter ";" -NoTypeInformation -Encoding utf8

---

D. Schnelles XML-Parsing mit [xml]

Durch das Voranstellen von [xml] konvertiert PowerShell XML-Strings direkt in navigierbare .NET-Objekte:

[xml]$manifest = Get-Content -Path "infrastructure.xml"
# Direkter Zugriff über Punktnotation oder XPath:
$allNodes = $manifest.SelectNodes("//server")

---

🎼 Die didaktische Analogie: "Der Zoll-Containerhafen"

• Die REST-API: Das Frachtschiff, das Waren über das Meer (HTTP/HTTPS) transportiert.
• JSON / XML: Die genormten Seecontainer – überall auf der Welt lesbar und maschinell verarbeitbar.
• Invoke-RestMethod: Der automatische Hafen-Kran, der den Container entlädt und die Ware sofort fix und fertig ausgepackt auf das Förderband legt.
• -Depth: Die Prüftiefe beim Zoll. Schaut man nur in die oberste Kiste (-Depth 2), übersieht man die wertvollen Teile ganz unten im Container!

---

🎯 Aufgaben & Teilziele in aufgabe.ps1

1. TODO 1: Get-RestApiData
   Baue einen flexiblen REST-API-Client mit Bearer-Token-Unterstützung und Invoke-RestMethod.
2. TODO 2: Convert-JsonToCsvReport
   Wandle einen JSON-String in ein sauberes CSV-Format ohne #TYPE-Kopfzeile und mit konfigurierbarem Trennzeichen um.
3. TODO 3: Format-DeepNestedConfig
   Serialisiere tief verschachtelte Konfigurationen mit ConvertTo-Json -Depth und validiere die Rückumwandlung.
4. TODO 4: Parse-XmlServerManifest
   Parse ein XML-Manifest mit dem [xml]-Beschleuniger und gib eine Liste strukturierter Server-Objekte zurück.

---

🧪 Tests ausführen

Invoke-Pester ./test_aufgabe.ps1