FHIR-gegevens importeren

2025-04-30

U kunt de import bewerking gebruiken om FHIR-gegevens op te nemen in de FHIR-server® met hoge doorvoer.

Bewerkingsmodi importeren

De import-bewerking ondersteunt twee modi: initiële en incrementele. Elke modus heeft verschillende functies en gebruiksvoorbeelden.

Initiële modus

Bedoeld voor het laden van FHIR-resources in een lege FHIR-server.
Hiermee blokkeert u API-schrijfbewerkingen naar de FHIR-server.

Incrementele modus

Geoptimaliseerd voor het periodiek laden van gegevens in de FHIR-server en blokkeert schrijven via de API niet.
Hiermee kunt u lastUpdated en versionId waarden uit resourcemetagegevens laden als deze aanwezig zijn in de resource-JSON.
Hiermee kunt u resources laden in een niet-opeenvolgende volgorde van versies. Opmerking voor niet-sequentiële opname van resources
- Als er geen version- en lastUpdated veldwaarden zijn opgegeven voor importbestanden, is er geen garantie dat alle resources in de FHIR-service worden geïmporteerd.
- Als importbestanden resources bevatten met dubbele version en lastUpdated veldwaarden, wordt slechts één resource willekeurig opgenomen in de FHIR-service.
- Als tijdens parallelle uitvoering meerdere resources dezelfde resource-id delen, wordt slechts één van deze resources willekeurig geïmporteerd.

In de volgende tabel ziet u het verschil tussen de importmodi.

Gebieden	Initiële modus	Incrementele modus
Vermogen	Eerste belasting van gegevens in FHIR-service	Continue invoer van gegevens in de FHIR-service (Incrementeel of Near Real Time).
Gelijktijdige API-aanroepen	Gelijktijdige schrijfbewerkingen blokkeren	Gegevens kunnen gelijktijdig worden opgenomen tijdens het uitvoeren van API CRUD-bewerkingen op de FHIR-server.
Opname van versiebeheerbronnen	Niet ondersteund	Maakt opname van meerdere versies van FHIR-resources in één batch mogelijk, terwijl de resourcegeschiedenis behouden blijft.
Waarde van veld lastUpdated behouden	Niet ondersteund	Behoud de waarde van het veld lastUpdated in FHIR-resources tijdens het verwerkingsproces.
Facturatie	Er worden geen kosten in rekening gebracht	Kosten worden in rekening gebracht op basis van succesvol geïngeste middelen. Er worden kosten in rekening gebracht volgens de API-prijzen.

Prestatieoverwegingen

Houd rekening met de volgende factoren om de beste prestaties te behalen met de import-bewerking.

Gebruik grote bestanden voor importeren. De optimale NDJSON-bestandsgrootte voor importeren is >=50 MB (of >=20 K-resources, geen bovengrens). Overweeg kleinere bestanden samen te combineren.
Importeer FHIR-resourcebestanden als één batch. Importeer voor optimale prestaties alle FHIR-resourcebestanden die u wilt opnemen in de FHIR-server in één import bewerking. Als u alle bestanden in één bewerking importeert, vermindert u de overhead van het maken en beheren van meerdere importtaken. Optimaal moet de totale grootte van bestanden in één import groot zijn (>=100 GB of >=100M-resources, geen bovengrens).
Beperk het aantal parallelle importtaken. U kunt meerdere import taken tegelijk uitvoeren, maar kan van invloed zijn op de algehele doorvoer van de import-bewerking.

De importbewerking uitvoeren

Vereiste voorwaarden

Als u de import bewerking wilt gebruiken, hebt u de rol FHIR-gegevensimporteur nodig op de FHIR-server.
Configureer de FHIR-server. De FHIR-gegevens moeten worden opgeslagen in resourcespecifieke bestanden in FHIR NDJSON-indeling in de Azure Blob Store. Zie Importinstellingen configureren voor meer informatie.
De gegevens moeten zich in dezelfde tenant bevinden als de FHIR-service.
Zie Toegangstoken om een toegangstoken te verkrijgen

Een oproep uitvoeren

Maak een POST aanroep naar <<FHIR service base URL>>/$import met de volgende aanvraagheader en hoofdtekst.

Header van het verzoek

Prefer:respond-async
Content-Type:application/fhir+json

Lichaam

In de volgende tabellen worden de lichaamsparameters en invoer beschreven.

Parameternaam	Beschrijving	Kardinaliteit	Geaccepteerde waarden
`inputFormat`	Tekenreeks die de naam van de gegevensbronindeling vertegenwoordigt. Alleen FHIR NDJSON-bestanden worden ondersteund.	1..1	`application/fhir+ndjson`
`mode`	Waarde van de importmodus.	1..1	Gebruik de moduswaarde `InitialLoad` voor importeren in de initiële modus. Voor het importeren in incrementele modus gebruikt u de `IncrementalLoad`-moduswaarde. Als u geen moduswaarde opgeeft, wordt de `IncrementalLoad` moduswaarde standaard gebruikt.
`allowNegativeVersions`	Hiermee wordt toegestaan dat de FHIR-server negatieve versies toewijst aan resource records met een expliciete lastUpdated-waarde en geen opgegeven versie wanneer de invoer niet past in de opeenvolgende ruimte van positieve versies die in de opslag aanwezig zijn.	0..1	Als u deze functie wilt inschakelen, geeft u true door. Standaard is het onwaar.
`errorContainerName`	Tekenreeks die de naam van de container aangeeft waarin fouten tijdens het importproces worden geregistreerd.	0..1	Aangepaste containernaam voor foutenlogboeken. De naam moet tussen 3 en 63 tekens zijn en mag alleen kleine letters, cijfers en afbreekstreepjes bevatten. Als dit niet is opgegeven, wordt de standaardcontainer gebruikt.
`input`	Details van de invoerbestanden.	1..*	Een JSON-matrix met de drie onderdelen die in de volgende tabel worden beschreven.

Naam van invoeronderdeel	Beschrijving	Kardinaliteit	Geaccepteerde waarden
`type`	Resourcetype van het invoerbestand.	0..1	Een geldig FHIR-resourcetype dat overeenkomt met het invoerbestand. Dit veld is optioneel.
`url`	Azure Storage-URL van het invoerbestand.	1..1	URL-waarde van het invoerbestand. De waarde kan niet worden gewijzigd.
`etag`	ETag van het invoerbestand in Azure Storage. Wordt gebruikt om te controleren of de bestandsinhoud niet wordt gewijzigd na `import` registratie.	0..1	ETag-waarde van het invoerbestand.

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "inputFormat",
            "valueString": "application/fhir+ndjson"
        },
        {
            "name": "mode",
            "valueString": "<Use "InitialLoad" for initial mode import / Use "IncrementalLoad" for incremental mode import>"
        }, 
        {
            "name": "allowNegativeVersions",
            "valueBoolean": true
        },
        {
            "name": "errorContainerName",
            "valueString": "import-error-logs"
        },
        {
            "name": "input",
            "part": [
                { 
                    "name": "url",
                    "valueUri": "https://example.blob.core.windows.net/resources/filename.ndjson"
                },
                {
                    "name": "etag",
                    "valueUri": "\"0x8D92A7342657F4F\""
                }
            ]
        }
    ]
}

Importstatus controleren

Nadat u een import-bewerking hebt gestart, wordt een lege antwoordtekst met een callback koppeling geretourneerd in de Content-location koptekst van het antwoord, samen met een 202 Accepted statuscode. Sla de callback koppeling op om de importstatus te controleren.

Registratie van de import-bewerking wordt geïmplementeerd als een idempotente aanroep. Dezelfde nettolading voor registratie levert dezelfde registratie op, wat van invloed is op de mogelijkheid om bestanden met dezelfde naam opnieuw te verwerken. Werk geen bestanden ter plekke bij. In plaats daarvan raden we u aan een andere bestandsnaam te gebruiken voor bijgewerkte gegevens. Als een in-place update met dezelfde bestandsnaam onvermijdelijk is, voegt u ETags toe aan de registratielading.

Als u de importstatus wilt controleren, voert u de REST-aanroep uit met de methode GET naar de callback koppeling die in de vorige stap is geretourneerd.

Interpreteer het antwoord met behulp van deze tabel.

Antwoordcode	Antwoordlichaam	Beschrijving
`202 Accepted`		De bewerking wordt nog steeds uitgevoerd.
`200 OK`	`The response body doesn't contain any error.url entry`	Alle resources zijn succesvol geïmporteerd.
`200 OK`	`The response body contains some error.url entry`	Er is een fout opgetreden tijdens het importeren van sommige resources. Zie de bestanden op `error.url`voor meer informatie. De resterende resources zijn succesvol geïmporteerd.
`Other`		Er is een fatale fout opgetreden en de bewerking is gestopt. Succesvol geïmporteerde resources worden niet teruggedraaid.

In de volgende tabel worden de belangrijke velden in de hoofdtekst van het antwoord beschreven:

Veld	Beschrijving
`transactionTime`	Begintijd van de bulkbewerking `import`.
`output.count`	Het aantal resources dat succesvol is geïmporteerd.
`error.count`	Het aantal resources dat niet is geïmporteerd vanwege een fout.
`error.url`	URL van het bestand met details van de fout. Elke `error.url`-instantie is uniek voor een invoer-URL.

{
    "transactionTime": "2021-07-16T06:46:52.3873388+00:00",
    "request": "https://importperf.azurewebsites.net/$Import",
    "output": [
        {
            "type": <null in case type parameter in not populated in request. If provided, resource name will be added>,
            "count": 10000,
            "inputUrl": "https://example.blob.core.windows.net/resources/filename.ndjson"
        }
    ],
    "error": [
        { 
        "type": "OperationOutcome",
        "count": 51,
        "inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.ndjson",
        "url": "https://example.blob.core.windows.net/fhirlogs/CarePlan06b88c6933a34c7c83cb18b7dd6ae3d8.ndjson"
        }
    ]
}

Tijdelijk verwijderde bronnen opnemen

Import in de incrementele modus ondersteunt het opnemen van zacht verwijderde resources. Je moet de extensie gebruiken om zacht verwijderde resources op te nemen in de FHIR-service.

Voeg de extensie toe aan de resource om de FHIR-service te informeren dat de resource voorlopig is verwijderd.

{"resourceType": "Patient", "id": "example10", "meta": { "lastUpdated": "2023-10-27T04:00:00.000Z", "versionId": 4, "extension": [ { "url": "http://azurehealthcareapis.com/data-extensions/deleted-state", "valueString": "soft-deleted" } ] } }

Nadat de import-bewerking met succes is voltooid, controleert u de geschiedenis van de resource om zacht verwijderde resources te valideren. Als u de id van de verwijderde resource kent, gebruikt u het URL-patroon in het volgende voorbeeld.

<FHIR_URL>/<resource-type>/<resource-id>/_history

Als u de id van de resource niet weet, voert u een geschiedeniszoekopdracht uit op het resourcetype.

<FHIR_URL>/<resource-type>/_history

Problemen met de importbewerking oplossen

Hier volgen de foutberichten die optreden als de import bewerking mislukt, samen met aanbevolen acties om de problemen op te lossen.

200 OK, maar er is een fout met de URL in het antwoord

De import bewerking slaagt en retourneert 200 OK. error.url is echter aanwezig in de hoofdtekst van het antwoord. Bestanden op de error.url locatie bevatten JSON-fragmenten die vergelijkbaar zijn met het volgende voorbeeld.

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "details": {
                "text": "Given conditional reference '{0}' doesn't resolve to a resource."
            },
            "diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
        }
    ]
}

Oorzaak: NDJSON-bestanden bevatten resources met voorwaardelijke verwijzingen die import niet ondersteunt.

Oplossing: vervang de voorwaardelijke verwijzingen naar normale verwijzingen in de NDJSON-bestanden.

400 Foute Verzoek

De import bewerking mislukt en retourneert 400 Bad Request. De hoofdtekst van het antwoord bevat diagnostische inhoud

de importbewerking is om de reden mislukt: er is geen dergelijke host bekend. (example.blob.core.windows.net:443) Oplossing: Controleer of de koppeling naar de Azure-opslag juist is. Controleer de netwerk- en firewallinstellingen om ervoor te zorgen dat de FHIR-server toegang heeft tot de opslag. Als uw service zich in een virtueel netwerk bevindt, moet u ervoor zorgen dat de opslag zich in hetzelfde virtuele netwerk bevindt of in een virtueel netwerk dat is gekoppeld aan het virtuele netwerk van de FHIR-service.

SearchParameter-resources kunnen niet worden verwerkt door import Oplossing: De importbewerking retourneert een HTTP 400-fout wanneer een zoekparameterresource wordt opgenomen via het importproces. Deze wijziging is bedoeld om te voorkomen dat zoekparameters in een ongeldige status worden geplaatst wanneer ze worden opgenomen in een importbewerking.

403 Verboden

De import bewerking mislukt en retourneert 403 Forbidden. De hoofdtekst van het antwoord bevat diagnostische inhoud.

importbewerking is mislukt om de reden: de server kan de aanvraag niet verifiëren. Zorg ervoor dat de waarde van de Autorisatie-header juist is opgemaakt, inclusief de handtekening. Oorzaak: de FHIR-service maakt gebruik van een beheerde identiteit voor bronopslagverificatie. Deze fout geeft een ontbrekende of onjuiste roltoewijzing aan. Oplossing: Wijs de rol Inzender voor opslagblobgegevens toe aan de FHIR-server. Zie Azure-rollen toewijzen voor meer informatie.

500 Interne Serverfout

De import bewerking mislukt en retourneert 500 Internal Server Error. De hoofdtekst van het antwoord bevat diagnostische inhoud

de importbewerking is mislukt om de reden: de database '****' heeft het quotum voor de grootte bereikt. Partitieer of verwijder gegevens, verwijder indexen, of raadpleeg de documentatie voor mogelijke oplossingen.

Oorzaak: u hebt de opslaglimiet van de FHIR-service bereikt.

Oplossing: verklein de grootte van uw gegevens of overweeg Azure API voor FHIR, met een hogere opslaglimiet.

423 Vergrendeld

Gedrag: De import bewerking mislukt en retourneert 423 Locked. De hoofdtekst van het antwoord bevat deze inhoud:

{
    "resourceType": "OperationOutcome",
    "id": "13876ec9-3170-4525-87ec-9e165052d70d",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "import operation failed for reason: Service is locked for initial import mode."
        }
    ]
}

Oorzaak: De FHIR-service is geconfigureerd met de initiële importmodus die andere bewerkingen heeft geblokkeerd.

Oplossing: Schakel de initiële importmodus van de FHIR-service uit of selecteer incrementele modus.

Beperkingen

Het maximum aantal bestanden dat is toegestaan voor elke import bewerking is 10.000.
Het aantal bestanden dat is opgenomen in de FHIR-server met dezelfde waarde voor het veld lastUpdated tot milliseconden, mag niet groter zijn dan 10.000.
Importbewerking wordt niet ondersteund voor het resourcetype SearchParameter.
De importbewerking ondersteunt geen voorwaardelijke verwijzingen in bronnen.

Volgende stappen

Uw gegevens converteren naar FHIR

Exportinstellingen configureren en een opslagaccount instellen

Gegevens kopiëren naar Azure Synapse Analytics

Notitie

FHIR® is een geregistreerd handelsmerk van HL7 en wordt gebruikt met de machtiging HL7.