Skip to main content

Inmatning

Det här avsnittet ger vägledning om hur man konfigurerar anslutningar, exporterar data, automatiserar dataextraktion och förstår de tekniska specifikationerna för INGEST-komponenten.

Det här lär du dig här:

Anslutningar: Hur du konfigurerar en anslutning till ett källsystem på sidan INGEST → Connections i Config UI. Det omfattar att registrera ett nytt källsystem, välja anslutningstyp och operator, tillämpa en konfigurationsmall och ange autentiseringsuppgifter.

Exporter: Hur du konfigurerar en exportdefinition på sidan INGEST → Exports. En export läser en tabell, en endpoint, en katalog eller en kö och skriver resultatet till landningszonen.

Kodkonfiguration: En guide för att automatisera dataextraktion och laddning till landningszonen enligt ett schema när användning av UI:t inte är genomförbart. Avsnittet täcker JSON-definitionerna och de API-endpoints de skickas till.

Tekniska detaljer: Detaljerad information om de tekniska specifikationerna för INGEST-komponenten, inklusive containerinställning, Python-beroenden och distributions- och exekveringsriktlinjer.

Konfigurera anslutningen via UI​

Sidan INGEST → Connections (/systems) definierar hur PDQ når ett källsystem. Systemen listas i den sökbara sidopanelen till vänster; när du väljer ett öppnas dess anslutning, och Add new system skapar ett nytt.

Överst på sidan finns knappen Connections Guide som fäller ut en kort sammanfattning av samma material direkt i appen.

Lägga till ett nytt system

    Ett system är den logiska källa som allt annat hänger på — anslutningar, exporter, källfiler och mappningar refererar alla till det med namn.

    Källsystemets namn (system): Ett unikt namn i ett ord som representerar källsystemet. Namnet används internt för spårning och hantering av data från källsystemet och kan inte ändras i efterhand.

    Källsystemets beskrivning (description): En textuell förklaring av källsystemets sammanhang och detaljer. Beskrivningen visas genomgående i systemdokumentationen.

Välja anslutningstyp

    Ett system som ännu inte har någon anslutning visar de fyra anslutningstyperna som knappar. Typen avgör vilket kontrakt anslutningen sparas under och vilket formulär du får:

    • DB — en relationsdatabas som nås med SQL.
    • API — en HTTP-endpoint som returnerar JSON.
    • FILE — ett filsystem: lokal disk, S3, Azure Data Lake Gen2 eller SFTP.
    • CUSTOM — allt annat. I dag är det köfamiljen (SQS, Azure Service Bus, Redis) plus den enkla custom-mallen.

    När en anslutning väl finns är typen låst, och rubriken visar operatorn tillsammans med märket Connected.

Välja operator

    Inom en anslutningstyp kör inmatningsmotorn exakt en operatorklass per källsystem. Operatorn avgör vilka fält som läses, vilka som krävs och vilka som ignoreras — formuläret frågar därför bara efter det som operatorn behöver, markerar det som krävs och flaggar det som kommer att ignoreras i stället för att dölja det.

    TypOperatorer
    DBPostgreSQL, SQL Server, Oracle, MySQL samt en generisk basklass
    APIGeneric REST, Heartpace, Salesforce Service Cloud, Talkdesk, SharePoint (Graph), Microsoft Teams, Google Drive / Sheets
    FILELokalt filsystem, Amazon S3, Azure Data Lake Gen2, SFTP
    CUSTOMAWS SQS, Azure Service Bus, Redis samt en custom-mall

    Var valet lagras. Bara två anslutningstyper kan spara sin operator:

    TypLagras iVad som gäller
    FILEfältet StorageTypeden sparade anslutningen
    CUSTOM (köer)anslutningsegenskapen queue_typeden sparade anslutningen
    DBingenstans — den ligger i agentens settings.yamldetekteras från porten, kan överstyras per webbläsare
    APIingenstans — som ovandetekteras från API-URL:en, kan överstyras per webbläsare

    För DB och API berättar väljaren hur den kom fram till sitt svar — detekterat från porten eller URL:en, eller ihågkommet från ett tidigare val i den här webbläsaren — i stället för att presentera en gissning som fakta. Valet formar bara formuläret; det skickas inte vidare någonstans.

    Ett fåtal operatorer som skrivits för en enskild kunds källa erbjuds inte i väljaren, men ett system som redan är kopplat till en av dem känns fortfarande igen och får rätt formulär.

    Databasoperatorer

    Operatorväljare för databasanslutningar: PostgreSQL, SQL Server, Oracle, MySQL och Generic (base class)

    API-operatorer

    Operatorväljare för API-anslutningar: Generic REST, Heartpace, Salesforce Service Cloud, Talkdesk, SharePoint (Graph), Microsoft Teams och Google Drive / Sheets

    Filoperatorer

    Operatorväljare för filanslutningar: Local file system, Amazon S3, Azure Data Lake Gen2 och SFTP

    Custom-operatorer

    Operatorväljare för custom-anslutningar: AWS SQS, Azure Service Bus, Redis, Queue (base class) och Custom (template)

Konfigurationsmallar

    Det mesta som en ny anslutning behöver är identiskt för alla kunder till en given källa: porten, avgränsarna, grant-typen, kontrollheadrarna, scope. När du väljer operator erbjuds en eller flera mallar som fyller i detta och sedan listar vad de medvetet lämnat till dig, med en notering om var varje värde finns.

    • Fill empty fields skriver bara där formuläret är tomt, så en mall kan aldrig skriva över något du själv har fyllt i.
    • Reset to these values är en separat åtgärd för fallet "börja om från standardvärdena".
    • En mall innehåller aldrig ett lösenord, en hemlighet eller en nyckel, och hittar aldrig på ett värde den inte kan känna till. Sådant hamnar i stället på checklistan över vad som återstår.

    Det finns mallar för PostgreSQL, SQL Server, Oracle och MySQL; för OAuth 2.0 client credentials, OAuth med klientcertifikat och statiska bearer-tokens på den generiska REST-operatorn; för Talkdesk, Salesforce (password- och client-credentials-grant), SharePoint och Teams via Graph; samt för S3, SFTP (lösenord och privat nyckel), Azure Data Lake Gen2 och det lokala filsystemet.

Autentiseringsuppgifter — läs detta innan du sparar

    API:et krypterar varje värde det tar emot. Allt annat följer av det:

    • en sparad uppgift kommer tillbaka krypterad, och originalet går inte att läsa ut;
    • att posta tillbaka det krypterade värdet skulle kryptera det en andra gång;
    • anslutningen slutar då fungera vid nästa export, utan att UI:t visar varför — värdet ser oförändrat ut eftersom det är oförändrat, bara inslaget ett lager djupare än vad körningen förväntar sig.

    En sparad uppgift återanvänds därför aldrig. Att spara en anslutning innebär att ange den riktiga uppgiften på nytt, och det du anger blir det som lagras. Det gäller lösenord för databaser och lagring, och krypterade värden inne i anslutningsegenskaperna — en client_secret för OAuth rensas till exempel när anslutningen laddas, och formuläret talar om vilka värden som rensades.

    Förhandsgranskningen Show JSON innehåller alltid lösenordsnyckeln så att payloaden går att posta, men fyller den aldrig med det lagrade värdet. En nedladdad förhandsgranskning innehåller en skarp autentiseringsuppgift så snart en har skrivits in — behandla den som en hemlighet, inte som en konfigurationsfil.

Databasanslutningsdetaljer

    Databasnamn (DBNm): Namnet på databasen som ska anslutas. Obligatoriskt. För Oracle är detta service name, inte ett schema — det skickas som service_name.

    Databasalias (DBAlias): Endast informativt. Det används inte för att nå servern.

    Serveradress (DBServerAddr): Värdnamn eller IP till databasservern. Obligatoriskt.

    Serverport (DBServerPort): Porten servern lyssnar på. Obligatoriskt. Formuläret förifyller operatorns standard: 5432 för PostgreSQL, 1433 för SQL Server, 1521 för Oracle, 3306 för MySQL. Det är också värdet som används för att detektera vilken databasoperator anslutningen kör.

    Användare (DBUsr): Användarnamnet som används för autentisering. Obligatoriskt.

    Lösenord (DBUsrPwd): Lösenordet för den användaren. Obligatoriskt och aldrig förifyllt — se Autentiseringsuppgifter ovan.

    Krypterad anslutning (DBEncryptedConnection): yes begär en krypterad anslutning till servern.

    Lita på serverns certifikat (DBTrustCertificate): yes accepterar serverns certifikat utan att validera det — vad en intern server med ett självsignerat certifikat behöver. På SQL Server blir detta TrustServerCertificate i anslutnings-URL:en.

    Databasanslutningsformulär i Ingest: operator, databasinställningar, autentiseringsuppgifter, transportsäkerhet och alternativ

API-anslutningsdetaljer

    API-URL (APIUrl): Bas-URL:en. Varje exportdefinitions API-sökväg läggs till efter den. Obligatoriskt.

    Autentiseringsmetod (APIAuthMethod): Avgör allt annat. Värdena som agenten jämför mot är:

    • OAuth 2.0 — postar anslutningsegenskaperna till token-URL:en och bygger Authorization-headern från svaret.
    • Token — gör inget nätverksanrop och använder anslutningsegenskapen bearer_token direkt.
    • Basic — beter sig som OAuth när en token-URL är satt, och faller tillbaka på bearer-token när den inte är det.

    Anslutningar som sparats av en äldre version av UI:t kan bära värden med små bokstäver (oauth, bearer, apikey, none) som agenten inte känner igen — ingen Authorization-header hade byggts för dem. Formuläret flaggar detta och sparar den nuvarande stavningen när du sparar.

    Att välja OAuth 2.0 skriver in de egenskaper som konfigurationen kräver i egenskapslistan, så att formuläret och den sparade payloaden är överens.

    Token-URL (APITokenUrl): Endpointen som anslutningsegenskaperna postas till i utbyte mot en access token. Obligatoriskt för OAuth 2.0; valfritt för Basic, där ett tomt värde innebär att en statisk bearer-token används.

    API-headrar (APIHeader): Skickas som HTTP-headrar vid varje dataförfrågan, med tre undantag som läses som kontrollflaggor:

    NyckelEffekt
    methodpost skickar filtervillkoren som en JSON-body; allt annat skickar en GET med query-parametrar.
    allow_redirectsTa bort nyckeln för att sluta följa omdirigeringar. Den testas på sanningsvärde, så strängen false aktiverar dem fortfarande — ta bort raden i stället.
    verify_sslTas bort enbart från token-förfrågan. Den skickas fortfarande som en bokstavlig HTTP-header vid dataförfrågningar; använd anslutningsegenskapen verify_ssl i stället.

    De headrar de flesta källor behöver erbjuds i lägg-till-menyn — Accept, Content-Type, User-Agent och X-API-Key för API-nyckelautentisering. Headernamn är inte standardiserade, så kontrollera leverantörens egen stavning.

    Anslutningsegenskaper (APIConnectionProperties): Postas som token-förfrågans body, så de flesta nycklar kommer från din identitetsleverantör snarare än från agenten:

    NyckelAnvänds för
    grant_typeVilket OAuth-flöde som används. client_credentials flyttar klient-id och hemlighet till en HTTP Basic-header; password behåller allt i bodyn. Postas ordagrant, så ett leverantörsspecifikt grant kan skrivas in.
    client_id / client_secretUppgiftsparet, för client-credentials- och password-grant.
    username / passwordResursägarens uppgifter, för password-grant.
    refresh_tokenDen långlivade token, för refresh-token-grant. Fungerar bara där leverantören ger ut en icke-roterande token.
    scopeVad token får nå. Krävs av vissa leverantörer, valfritt för andra.
    audienceNamnger API:et som token gäller. Auth0 kräver det; utan det kommer token tillbaka ogenomskinlig och källan avvisar den.
    assertionDen signerade JWT:n, för JWT-bearer-grant.
    client_assertion / client_assertion_typeEn signerad JWT som autentiserar klienten i stället för en hemlighet — Entra ID med certifikat till exempel.
    resourceKrävs av vissa äldre identitetsleverantörer.
    token_auth_methodVar klientuppgifterna placeras, för leverantörer som erbjuder ett val.
    bearer_tokenDen statiska token, för autentiseringsmetoden Token.
    verify_sslSätt false för att stänga av TLS-verifiering vid varje förfrågan. Exponerar anslutningen för avlyssning — endast mot ett känt trasigt internt certifikat.
    cert_file / key_fileKlientcertifikat och nyckel inne i containern, för ömsesidig TLS.

    Vilka av dessa som är obligatoriska följer autentiseringsmetoden och grant-typen, inte operatorn — en client secret behövs för ett client-credentials-utbyte och är meningslös för en statisk bearer-token. Redigeraren grupperar de obligatoriska först.

    Källor bakom en gateway. Om källan nås via en gateway (till exempel Azure API Management) upphör leverantörens egen vägledning att gälla: scope, grant-typ och autentiseringsuppgifter blir vad gatewayen förväntar sig. Formuläret märker detta på token-URL:en, drar tillbaka de leverantörsspecifika förslagen och säger varför. Azure API Management behöver dessutom oftast en Ocp-Apim-Subscription-Key-header, som erbjuds på alla API-operatorer.

    API-anslutningsformulär i Ingest: operator, API-URL, headers, autentiseringsmetod och anslutningsegenskaper

Filanslutningsdetaljer

    Storage name (StorageName): Bucket-namnet för S3, lagringskontot för Azure Data Lake Gen2. Informativt för SFTP och en lokal sökväg.

    Region (StorageRegion): AWS-regionen. Obligatoriskt för S3; används inte i övrigt — ADLS-endpointen härleds från kontonamnet.

    Storage type (StorageType): Skrivskyddat. Det bär den valda operatorn och är det värde både körningen och den här sidan läser.

    Serveradress / Serverport (StorageServerAddr, StorageServerPort): Endast SFTP; porten är 22 som standard. S3 och ADLS adresseras med region, bucket och kontonamn i stället för med värdnamn.

    Användare / Lösenord (StorageUsr, StorageUsrPwd): Betydelsen beror på operatorn — access key id och secret access key för S3, inloggningsanvändare och lösenord (eller nyckelns lösenfras) för SFTP, samt kontonyckel eller SAS-uppgift för ADLS. För ADLS måste användarfältet vara ifyllt för att klienten alls ska byggas, men själva värdet används aldrig.

    Base path (StorageBasePath): Rotkatalogen för en lokal sökväg, nyckelprefixet för S3, Gen2-filsystemets (containerns) namn för ADLS. Den slås ihop med exportdefinitionens filsökväg.

    Anslutningsegenskaper (StorageConnectionProperties): SFTP kräver connection_method (user/pass eller private_ssh_id) och läser private_ssh_id_path. Alla filoperatorer exponerar dessutom prestandainställningar under Show advanced — minne per hämtningsbatch, skrivbatchstorlek, gzip-nivå och nedladdningsblockets storlek.

    Filanslutningsformulär i Ingest för en SFTP-källa: lagringsinställningar, anslutningsdetaljer, autentiseringsuppgifter, alternativ och anslutningsegenskaper

Custom- och köanslutningsdetaljer

    Köanslutningar levereras som CUSTOM, så varje koordinat färdas som en anslutningsegenskap i formen nyckel=värde.

    Queue type (queue_type): SQS, SERVICEBUS eller REDIS. Det är så sidan vet vilken broker du konfigurerar. Obligatoriskt.

    Queue name (queue_name): SQS löser upp kö-URL:en från detta vid anslutning; för Redis är det stream- eller listnyckeln. Obligatoriskt.

    Brokeruppgifter är namngivna för att matcha körningens dekrypteringsregel, som fungerar på delsträngsmatchning av nyckeln — access_id, access_key och connection_token dekrypteras, medan varje inställningsparameter medvetet är namngiven för att undvika regeln. SQS behöver region, access_id och access_key; Service Bus behöver connection_token och, för ett topic, topic_name och subscription_name; Redis tar antingen en connection_token-URL eller host/port/access_id/access_key/db, plus sina consumer group-inställningar.

    Batchgränser — max_batch_bytes (30 MB), max_batch_seconds (15 minuter), max_batches_per_run (0 = obegränsat), receive_batch_size och receive_wait_seconds — avgör när en batchfil stängs. De tre första kan överstyras per export.

    Custom-anslutningsformulär i Ingest för en kökälla: operatorväljare och anslutningsegenskaper

Inställningar som delas av alla anslutningstyper

    Add service col val (AddServiceColVal): När värdet är satt får varje exporterad post en __service-kolumn med det värdet.

    Column delimiter (ColumnDelimiter): Fältavgränsare som används när CDC skriver CSV-utdata. Ignoreras för JSON.

    Line delimiter (LineDelimiter): Läses men respekteras inte av de flesta operatorer — de tvingar \n oavsett värde. Formuläret märker fältet som Not used där så är fallet.

Att spara

    Show JSON öppnar exakt den payload som kommer att postas, med en nedladdningsknapp. Add connection / Update connection sparar den. Obligatoriska fält, och de egenskaper som den valda operatorn inte kan köra utan, valideras innan förfrågan skickas, och eventuella fel rapporteras intill knappen.