API-referenser
AME API (Active Metadata Engine API) är den enda styrkanalen för PDQ-plattformen. Alla komponenter — INGEST, DLS, DWA, QPI, DataOps-konsolen och Config UI — läser och skriver sin konfiguration, sitt tillstånd och sin revisionsinformation via detta enda REST-gränssnitt.
Den här sidan beskriver API:et på kapabilitetsnivå: vad du kan göra med det och var varje kapabilitet finns. Den fullständiga och alltid aktuella endpoint-referensen — parametrar, scheman och exempel — genereras av den körande tjänsten.
Varje installation publicerar sitt eget aktuella kontrakt:
- Swagger UI —
https://<din-ame-host>/docs - ReDoc —
https://<din-ame-host>/redoc - OpenAPI-schema —
https://<din-ame-host>/openapi.json
Om tjänsten är monterad bakom ett sökvägsprefix ingår det prefixet i det publicerade kontraktet.
Versionshantering
Endpoints versionshanteras i sökvägen: /api/v3/..., /api/v3.1/..., /api/v3.2/..., /api/v4/....
- Använd v3 och högre. V3-ytan är komplett — inklusive schemaläggaren — så en integration behöver inte längre blanda versioner.
- En högre delversion ersätter en lägre inom samma kapabilitet. Där både
/api/v3och/api/v3.2finns för källfiler ärv3.2det aktuella kontraktet. - v4 är en framåtriktad kontraktsyta för dataprodukter, och omfattar för närvarande modellobjekt, källfiler och målobjektsorienterade mappningar.
- Inget tas bort vid uppgradering. Äldre versioner finns kvar för bakåtkompatibilitet, men nytt arbete bör riktas mot den senaste versionen av varje kapabilitet.
- Vissa kapabilitetsområden är märkta som Deprecated i OpenAPI-taggarna trots att v3-sökvägar finns — se Äldre områden.
Autentisering och behörighet
API:et använder OAuth2 password flow och utfärdar bearer-tokens.
POST /tokenmedusernameochpasswordsom formulärfält.- Skicka den returnerade token som
Authorization: Bearer <token>vid varje efterföljande anrop.
Tre kontoegenskaper styr vad en token får göra:
| Egenskap | Effekt |
|---|---|
| Inaktiverat | Alla anrop avvisas. |
| Skrivskyddat | GET tillåts; POST, PUT, DELETE och PATCH avvisas. |
| Administratör | Krävs för administrativa operationer. |
Lösenord lagras med bcrypt_sha256. Befintliga äldre hashar fortsätter att gälla och uppgraderas när lösenordet ändras nästa gång.
Kapabiliteter
Administration och plattformsinställningar
Global konfiguration av dataplattformsinstallationen och den metadatavokabulär som används i den.
- Läs och uppdatera globala dataplattformsinställningar — zonnamn, modell- och schemanamn, klienttyp, lagringsintegration samt namnkonventioner såsom skiftläge för tabellnamn och suffix för objektnycklar.
- Underhåll fältkategoriseringar — hierarkin av fältgrupper och fältdomäner som används för att klassificera data. Kategoriseringar versionshanteras vid sparande i stället för att skrivas över.
- Underhåll dokumentationsnoteringar — fria nyckel/värde-noteringar kopplade till moduler och synliga i dokumentationen.
- Hjälpfunktioner för uppsättning: generera en hash, generera ett salt, kryptera en sträng.
Bassökvägar: /api/v3/settings, /api/v3/fieldcategorizations, /api/v3/documentation/notes
Ingest
Allt som INGEST behöver veta om vad som ska extraheras, samt körningsstyrning och övervakning kring det.
- Anslutningar — hantera anslutningar till källsystem och datalager, där inloggningsuppgifter hanteras via plattformens kryptering.
- Exportdefinitioner — skapa, läsa, uppdatera, ta bort och flytta ingest-definitioner mellan källsystem; uppdatera extraheringsfilter; ange startdatum för en extrahering.
- Arbetsbelastningsstyrning — reservera en arbetsbelastning för en arbetare, starta en arbetsbelastning, markera den som slutförd, hämta nästa arbetsbelastning för ett källsystem och köra om en arbetsbelastning.
- Övervakning — lista exportkörningar under en tidsperiod och lista körningar som fortfarande pågår. Båda finns per källsystem och över alla system, så en övervakningstjänst behöver inte göra ett anrop per system.
Bassökväg: /api/v3/ingest/... — livscykel för definitioner under /api/v3.1/ingest/...
Källhanterare — källsystem, källfiler och mappningar
Datakontraktslagret: vad en källa levererar och hur det mappas mot modellen.
- Källsystem — lista, läsa och uppdatera definitioner av källsystem.
- Källfiler — definitionen av en levererad datamängd. Skapa, ersätta, komplettera, läsa och ta bort ett källfilsdatakontrakt. Strukturen versionshanteras, så en specifik historisk strukturversion kan hämtas.
- Fältmappningar — mappa källfält till målattribut och organisera mappningar i mappningsgrupper.
- Relationsmappningar — definiera relationer mellan mappade objekt, med mappningsnummer som nyckel.
- Målobjektsorienterade mappningar (v4) — läs och skriv samma mappningar organiserade efter målobjekt i stället för efter källfält.
Bassökvägar: /api/v3/systems, /api/v3.2/sourcefiles/..., /api/v4/sourcefiles/...
Datamodeller
Den affärsmodell som DWA automatiserar mot.
- Objekt — läsa, skapa, ersätta och ta bort modellobjekt. Ett komplett objekt inklusive attribut kan skickas i ett enda anrop.
- Attribut och relationer — läsa, skapa och ta bort individuellt.
- Ämnesområden — definiera ämnesområden och koppla objekt till eller från dem.
- Laddningsmönster — läsa och ange laddningsmönster för ett objekt.
- Dataproduktkontrakt (v4) — läsa ett modellobjekt uttryckt som ett dataproduktkontrakt.
Bassökvägar: /api/v3.1/model/..., /api/v4/model/...
Schemaläggare för källor
Orkestrering av flöden — ett flöde är den schemalagda bearbetningen av en källfil genom dess laddningssteg.
- Scheman — läsa och underhålla huvudschemat och arbetsschemat, per källfil eller efter tidsfönster; läsa ett flödes tillstånd, typ och nästa steg; sätta tillstånd.
- Körningsstyrning — starta ett flöde, köra om en känd körning från ett valt steg och allt nedströms, eller starta om den pågående körningen så att endast oavslutade steg körs.
- Massoperationer — sätta tillstånd i grupp och hoppa över steg genom att markera dem som slutförda utan att köra dem, vilket låser upp en stoppad kedja.
- Processorsteg — läsa och sätta tillstånd för extraprocessorsteg i kedjan.
Bassökvägar: /api/v3/schedule/..., /api/v3/master/schedule/...
Extraprocessorer
Anpassade bearbetningssteg som körs som en del av ett flöde.
- Definiera, läsa och ta bort extraprocessorer samt slå upp dem efter namn eller typ.
- Granska ofullständiga extraprocessorkörningar och exekveringsloggen.
Bassökväg: /api/v3/extraprocessor
Revision och datakontrakt
Det revisionsspår som DLS skapar när data rör sig genom zonerna, samt befordran av en observerad profil till ett överenskommet kontrakt.
- Batchar och loggar — läsa och skriva revisionsbatchar och revisionsloggen för en laddning.
- Profiler per zon — läsa revisionen av en källfil per bearbetningszon och befordra en specifik profil till datakontrakt för den källfilen.
- Synkronisering av definition — synkronisera en komplett observerad filstruktur från revisionen in i källfilsdefinitionen.
- Publiceringsrevision — revision och statistik för publicerade källfiler och publicerade tabeller, sökbart per datumintervall.
- Utlösare — utlösa omstart eller överhoppning för en eller flera filer (med orsak till överhoppning), skapa utlösare från en lista för en zon och registrera en odefinierad blob-fil för ombearbetning.
- Laddningsstatistik — läsa och skriva statistik per laddning.
Bassökvägar: /api/v3/audit/..., /api/v3/sourcefiles/{sourcefile}/audits, /api/v3/statistics
Quality Performance Indicator (QPI)
Datakvalitetsramverket, byggt som ett asynkront delsystem med operatör och arbetare. API:et kör aldrig själva probe-SQL:en: det skapar en körningsnyckel, köar arbetet och registrerar utfallet.
- Definitioner — skapa, läsa, inaktivera och ta bort QPI-definitioner samt validera ett probe-kommando innan det sparas.
- Exekvering — utlösa en körning och få en enda körningsnyckel som omfattar hela satsen; logga start och slut; kontrollera när körningen är klar; läsa resultat och exekveringsstatistik.
- Status — lista ofullständiga körningar och läsa exekveringsloggen.
- Beroenden — hitta vilka QPI:er som beror på ett visst flöde och utlösa exakt dessa när flödet är klart.
- Inställningar — läsa och uppdatera inställningar för QPI-delsystemet.
Bassökväg: /api/v3/qpi/...
Systemhälsa
Plattformens driftstatus, avsedd för instrumentpaneler och larm.
- Sammanfattning — ett övergripande hälsovärde över ett tidsfönster.
- Runtime-logg och mätvärden — spårningen av körningsjobb med härledda allvarlighetsnivåer.
- Jobblogg, mätvärden och status — jobbens körningshistorik och aktuella status.
Samtliga endpoints tar emot ett tidsfönster och en radgräns.
Bassökväg: /api/v3/systemhealth/...
OpenLineage
Härkomst (lineage) publicerad i OpenLineage-format, så att plattformen kan konsumeras av externa katalog- och lineage-verktyg.
- Läs en datamängd med dess schema- och lineage-facetter för ett givet laddningssteg, valfritt avgränsat till en källfil eller filnyckel, på sammanfattnings- eller detaljnivå.
Bassökväg: /api/v3/openlineage/dataset
Äldre områden
Dessa områden finns fortfarande tillgängliga under v3 men är märkta som Deprecated i OpenAPI-taggarna. De finns kvar för befintliga integrationer; använd kapabiliteterna ovan för nytt arbete.
| Område | Kapabilitet |
|---|---|
| Avvikelser | Typkonverteringar av felaktiga data med urval, upptäckt av felaktiga laddningar samt upptäckt av frikopplade poster med hjälpfunktioner för korrigering och omladdning. |
| Övervakning | Misslyckade källexporter och exportlogg, samt omstart av en källexport. |
| Datahärkomst | Spåra ett värde bakåt genom transformationslagren, från modellen eller från källan. |
| Importer | V2-föregångaren till Ingest. Ersatt av /api/v3/ingest/.... |
Konventioner
- Format — JSON i både anrop och svar. Svaren innehåller en status och ett meddelande vid sidan av nyttolasten.
- Statuskoder — standardiserad HTTP-semantik.
401vid ogiltig eller utgången token,403vid inaktiverat konto, skrivförsök från ett skrivskyddat konto eller saknad administratörsbehörighet,404vid saknad post och504när en databasfråga överskrider den konfigurerade tidsgränsen. - Fel — databasfel översätts till läsbara beskrivningar innan de når svaret; utförliga stackspårningar returneras inte.
- Beskrivningar — beskrivningsfält är begränsade till 255 tecken i både modell- och källfilsscheman.