IPU-Verbrauch der IDMC per REST-API auswerten

Hat eure Org das Feature „Intelligent Cloud Data Management“, wird die IDMC-Lizenz in Informatica Processing Units abgerechnet, kurz IPUs. Die Oberfläche zeigt den Verbrauch zwar an, aber wer ihn regelmäßig nach Projekten aufschlüsseln, an Fachbereiche weiterberechnen oder in ein eigenes Reporting laden will, braucht die REST-API. In einem meiner Projekte habe ich dafür einen Client gebaut und gegen eine echte Org betrieben. In diesem Artikel zeige ich euch, wie die Schnittstelle funktioniert und an welchen Stellen sie sich anders verhält, als man erwartet.

Die Beispiele verwenden curl und jq unter Linux.

Alle Aufrufe brauchen eine Session. Man meldet sich am Login-Host seiner Region an, also etwa dm-us oder dm-em:

BASE=https://dm-em.informaticacloud.com
LOGIN=$(curl -s -X POST "$BASE/saas/public/core/v3/login" \
  -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d "{\"username\":\"$IDMC_USER\",\"password\":\"$IDMC_PASSWORD\"}")

SID=$(echo "$LOGIN" | jq -r '.userInfo.sessionId')
API=$(echo "$LOGIN" | jq -r '.products[0].baseApiUrl')

Wichtig ist die zweite Variable. Die Antwort enthält unter products[].baseApiUrl die Adresse des Pods, auf dem eure Org liegt, in der Form https://<pod>.dm-em.informaticacloud.com/saas. Alle weiteren Aufrufe gehen an diese Adresse, nicht an den Login-Host. Die Session-ID erwarten die v3-Ressourcen im Header INFA-SESSION-ID, die ältere v2-API im Header icSessionId (Session IDs). Mein Client schickt beide mit. Damit die Beispiele kurz bleiben, packe ich sie in ein Array:

H=(-H "icSessionId: $SID" -H "INFA-SESSION-ID: $SID" -H 'Accept: application/json')

Das Muster: Auftrag, Abfrage, Download

Der Verbrauch kommt nicht direkt als Antwort. Man legt einen Export-Job an, fragt dessen Status ab, bis er fertig ist, und lädt dann ein ZIP mit CSV-Dateien herunter.

Ablauf eines Metering-Exports: Login, Export-Job anlegen, Status abfragen, bis der Job fertig ist, und ZIP mit CSV-Dateien laden — Ablauf eines Metering-Exports.

Einen Bericht über den Februar legt man so an:

JOB=$(curl -s -X POST "$API/public/core/v3/license/metering/ExportMeteringData" "${H[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"startDate":"2026-02-01T00:00:00Z","endDate":"2026-02-28T23:59:59Z",
       "jobType":"SUMMARY","allLinkedOrgs":"TRUE","combinedMeterUsage":"TRUE"}' \
  | jq -r '.jobId')

Anschließend fragt man den Status ab, bis einer der drei Endzustände SUCCESS, PARTIAL_SUCCESS oder FAILED erreicht ist. Unterwegs sieht man CREATED und PROCESSING:

while :; do
  STATUS=$(curl -s "$API/public/core/v3/license/metering/ExportMeteringData/$JOB" "${H[@]}" | jq -r '.status')
  echo "$STATUS"
  case "$STATUS" in SUCCESS|PARTIAL_SUCCESS|FAILED) break ;; esac
  sleep 30
done

curl -s -o verbrauch.zip "$API/public/core/v3/license/metering/ExportMeteringData/$JOB/download" "${H[@]}"
unzip verbrauch.zip

Auch PARTIAL_SUCCESS lässt sich herunterladen. Das Ergebnis ist dann möglicherweise unvollständig, aber in der Regel trotzdem brauchbar. Die Wartezeit solltet ihr großzügig bemessen: Selbst in einer Org ohne viel Betrieb dauert ein Export mehrere Minuten.

Die vier Berichtsarten

Über das Feld jobType wählt man die Detailstufe. Start- und Enddatum sind Zeitstempel in UTC. Das Enddatum ist inklusive, 2026-02-28T23:59:59Z schließt den 28. Februar also vollständig ein.

Bericht	Inhalt	Besonderheit
`SUMMARY`	Verbrauch je Meter, also je Dienst	höchstens 180 Tage
`PROJECT_FOLDER`	Verbrauch je Projekt und Ordner	höchstens 30 Tage
`ASSET`	Verbrauch je Asset und Meter	höchstens 30 Tage, ohne `allLinkedOrgs`
`JOB_LEVEL`	einzelne Jobläufe	eigener Pfad, andere Einheit, höchstens 180 Tage

Für die Aufteilung nach Projekten und Assets sehen die Bodies so aus. Bei ASSET kann man optional mit meterId auf einen Meter einschränken:

{"startDate":"2026-02-01T00:00:00Z","endDate":"2026-02-15T23:59:59Z","jobType":"PROJECT_FOLDER","allLinkedOrgs":"TRUE"}
{"startDate":"2026-02-01T00:00:00Z","endDate":"2026-02-15T23:59:59Z","jobType":"ASSET"}

Der Bericht auf Jobebene hat einen eigenen Pfad für den Start und kein Feld jobType. Status und Download laufen aber wie bei den anderen über ExportMeteringData/<jobId>:

curl -s -X POST "$API/public/core/v3/license/metering/ExportServiceJobLevelMeteringData" "${H[@]}" \
  -H 'Content-Type: application/json' \
  -d '{"startDate":"2026-02-01T00:00:00Z","endDate":"2026-02-28T23:59:59Z","allMeters":"TRUE"}'

Was in den CSV-Dateien steht

Hier liegt die größte Überraschung. Die Spalte mit dem Verbrauch heißt in jedem Bericht anders, und bei den Meter-Spalten unterscheidet sich sogar die Schreibweise:

Bericht	Verbrauch	Meter-Spalten
`SUMMARY`	`IPU`	`MeterId`, `MeterName`
`PROJECT_FOLDER`	`Consumption (IPUs)`	keine
`ASSET`	`Consumption (IPUs)`	`Meter ID`, `Meter Name`
`JOB_LEVEL`	`Metered Value`	keine

Beim Bericht auf Jobebene ist Vorsicht geboten. Metered Value ist keine IPU-Angabe, sondern der Wert in der Einheit des jeweiligen Meters. Bei Cloud Data Integration sind das laut Doku meist Rechenstunden (compute hours), bei Change Data Capture und SQL ELT dagegen verarbeitete Zeilen. Wer diese Spalte als IPUs aufsummiert, rechnet falsch. Kosten lassen sich deshalb nur aus den anderen drei Berichten ableiten.

Außerdem ist ASSET eine Teilmenge von SUMMARY. Meter, die an keinem Asset hängen, etwa für Sub-Organisationen, fehlen im Asset-Bericht und tauchen nur in SUMMARY auf. Die Summe des Asset-Berichts kann daher kleiner sein als der Gesamtverbrauch.

Beim Einlesen der Dateien solltet ihr drei Eigenheiten einplanen:

Manche Dateien beginnen mit einem Byte Order Mark. In Python liest man sie deshalb mit encoding="utf-8-sig", sonst heißt die erste Spalte nicht so, wie erwartet.
Für Verbrauch, der keinem Projekt oder Asset zugeordnet ist, schreibt die API den Text null in die Spalte. Das ist kein Projekt namens „null“, sondern gehört in einen eigenen Topf für nicht zugeordneten Verbrauch.
Datumsangaben kommen teils im US-Format MM/TT/JJJJ, im Bericht auf Jobebene dagegen als 2026-02-01 01:05:08.0.

Grenzen und Fallen

Einige Grenzen findet man erst durch Fehlermeldungen heraus:

PROJECT_FOLDER und ASSET lehnen Zeiträume über 30 Tage mit 400 LS_298 ab. SUMMARY und JOB_LEVEL vertragen laut Doku bis zu 180 Tage. Ich arbeite deshalb mit Halbmonaten, also vom 1. bis 15. und vom 16. bis zum Monatsende.
ASSET lehnt das Feld allLinkedOrgs mit 400 V3API_MeteringError_001 ab.
Pro Org dürfen höchstens fünf Export-Jobs gleichzeitig aktiv sein, also im Status CREATED oder PROCESSING. Wer mehrere Berichte und Zeiträume abruft, legt die Jobs deshalb nacheinander an.
Ein fertiges ZIP lässt sich nur drei Tage lang herunterladen. Danach muss man den Export neu anstoßen.
Die Meldung „Detailed Job level Data is not supported for meters: []“ beim Bericht auf Jobebene werte ich nicht als Fehler, mein Client überspringt den Bericht dann einfach. Berichte auf Jobebene gibt es laut Doku ohnehin nur für bestimmte Meter.

Das war es auch schon. Mit den vier Berichten und etwas Sorgfalt bei den CSV-Spalten lässt sich der IPU-Verbrauch gut automatisiert auswerten, zum Beispiel für eine monatliche Aufteilung auf die Projekte.