Dela via

Importera FHIR-data

Du kan använda åtgärden import för att mata in FHIR-data® till FHIR-servern med högt dataflöde.

Importdriftslägen

Åtgärden import stöder två lägen: inledande och inkrementell. Varje läge har olika funktioner och användningsfall.

Inledande läge

  • Avsedd för inläsning av FHIR-resurser till en tom FHIR-server.

  • Blockerar API-skrivningar till FHIR-servern.

Inkrementellt läge

  • Optimerad för att läsa in data till FHIR-servern med jämna mellanrum och blockerar inte skrivningar via API:et.

  • Gör att du kan läsa in lastUpdated och versionId värden från resursmetadata om de finns i resursens JSON.

  • Gör att du kan läsa in resurser i en icke-sekventiell ordning av versioner. Notering för icke-sekventiell inmatning av resurser

    • Om importfilerna inte har angett fältvärdena version och lastUpdated finns det ingen garanti för att importera alla resurser i FHIR-tjänsten.
    • Om importfiler har resurser med duplicerade version värden och lastUpdated fältvärden matas endast en resurs in slumpmässigt i FHIR-tjänsten.
    • Om flera resurser delar samma resurs-ID under parallell körning importeras bara en av dessa resurser slumpmässigt.

I följande tabell visas skillnaden mellan importlägen.

Områden Inledande läge Inkrementellt läge
Kapacitet Inledande datainläsning i FHIR-tjänsten Kontinuerlig inmatning av data till FHIR-tjänsten (inkrementell eller nära realtid).
Samtidiga API-anrop Blockerar samtidiga skrivåtgärder Data kan matas in samtidigt när API CRUD-åtgärder körs på FHIR-servern.
Inmatning av versionshanterade resurser Stöds inte Möjliggör inmatning av flera versioner av FHIR-resurser i en enda batch samtidigt som resurshistoriken bibehålls.
Behåll lastUpdated-fältvärde Stöds inte Behåll värdet för fältet lastUpdated i FHIR-resurser under inmatningsprocessen.
Fakturering Debiteras inte Debiteras avgifter baserat på resurser som har matats in. Avgifter tillkommer per API-prissättning.

Prestandaöverväganden

Tänk på följande faktorer för att uppnå bästa prestanda med import åtgärden.

  • Använd stora filer för import. Den optimala NDJSON-filstorleken för import är >=50 MB (eller >=20 K resurser, ingen övre gräns). Överväg att kombinera mindre filer tillsammans.

  • Importera FHIR-resursfiler som en enda batch. För optimal prestanda importerar du alla FHIR-resursfiler som du vill mata in i FHIR-servern i en import åtgärd. Om du importerar alla filer i en åtgärd minskar kostnaderna för att skapa och hantera flera importjobb. Optimalt bör den totala storleken på filer i en enskild import vara stor (>=100 GB eller >=100M resurser, ingen övre gräns).

  • Begränsa antalet parallella importjobb. Du kan köra flera import jobb samtidigt, vilket kan påverka processens övergripande dataflöde import.

Utför importåtgärden

Förutsättningar

  • Om du vill använda åtgärden import behöver du rollen FHIR Data Importer på FHIR-servern.

  • Konfigurera FHIR-servern. FHIR-data måste lagras i resursspecifika filer i FHIR NDJSON-format i Azure Blob Store. Mer information finns i Konfigurera importinställningar.

  • Data måste finnas i samma klientorganisation som FHIR-tjänsten.

  • Information om hur du hämtar en åtkomsttoken finns i Åtkomsttoken

Ringa ett samtal

Gör ett POST anrop till <<FHIR service base URL>>/$import med följande begärandehuvud och brödtext.

Förfrågningshuvudrad

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

Kropp

I följande tabeller beskrivs kroppsparametrar och indata.

Parameternamn Beskrivning Kardinalitet Godkända värden
inputFormat Sträng som representerar namnet på datakällans format. Endast FHIR NDJSON-filer stöds. 1..1 application/fhir+ndjson
mode Importläge värde. 1..1 Använd lägesvärdet InitialLoad för en inledningsimport. För import i inkrementellt läge använder du lägesvärdet IncrementalLoad . Om du inte anger något lägesvärde används lägesvärdet IncrementalLoad som standard.
allowNegativeVersions Tillåter att FHIR-servern kan tilldela negativa versioner för resursuppgifter med ett explicit lastUpdated-värde och där ingen version anges när indata inte får plats i det sammanhängande utrymmet för positiva versioner som finns i lagret. 0..1 Om du vill aktivera den här funktionen skickar du true. Som standard är det falskt.
errorContainerName Sträng som representerar namnet på containern där fel påträffades under importprocessen loggas. 0..1 Anpassat containernamn för felloggar. Namnet ska vara mellan 3 och 63 tecken och innehålla endast gemener, siffror och bindestreck. Om det inte anges används standardcontainern.
input Information om indatafilerna. 1..* En JSON-matris med de tre delarna som beskrivs i följande tabell.
Namn på komponent Beskrivning Kardinalitet Godkända värden
type Resurstyp för indatafilen. 0..1 En giltig FHIR-resurstyp som matchar indatafilen. Det här fältet är valfritt.
url Azure Storage-URL:en för indatafilen. 1..1 URL-värdet för indatafilen. Det går inte att ändra värdet.
etag ETag för indatafilen i Azure Storage. Används för att verifiera att filinnehållet inte ändras efter import registreringen. 0..1 ETag-värdet för indatafilen. 
{
    "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\""
                }
            ]
        }
    ]
}

Kontrollera importstatus

När du har startat en import åtgärd returneras en tom svarstext med en callback länk i svarets Content-location-huvud, med en 202 Accepted statuskod. Lagra länken callback för att kontrollera importstatusen.

Registreringen av åtgärden import implementeras som ett idempotent-anrop. Samma registreringsnyttolast ger samma registrering, vilket påverkar möjligheten att bearbeta filer med samma namn. Avstå från att uppdatera filer på plats. I stället föreslår vi att du använder ett annat filnamn för uppdaterade data. Om det inte går att undvika en uppdatering på plats med samma filnamn lägger du till ETags i registreringsnyttolasten.

Kontrollera importstatusen genom att göra REST-anropet GET med metoden till länken callback som returnerades i föregående steg.

Tolka svaret med hjälp av den här tabellen.

Svarskod Svarsdel Beskrivning
202 Accepted Åtgärden körs fortfarande.
200 OK The response body doesn't contain any error.url entry Alla resurser har importerats framgångsrikt.
200 OK The response body contains some error.url entry Ett fel uppstod under importen av några av resurserna. Mer information finns i filerna som finns på error.url. De återstående resurserna har importerats framgångsrikt.
Other Ett allvarligt fel uppstod och åtgärden stoppades. Framgångsrikt importerade resurser återställs inte.

I följande tabell beskrivs de viktiga fälten i svarstexten:

Fält Beskrivning
transactionTime Starttid för den omfattande import operationen.
output.count Antal resurser som har importerats.
error.count Antal resurser som inte importerades på grund av ett fel.
error.url URL för filen som innehåller information om felet. Varje error.url instans är unik för en indata-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"
        }
    ]
}

Importera mjukraderade resurser

Import i inkrementellt läge stöder inmatning av mjukt borttagna resurser. Du måste använda tillägget för att mata in mjukt borttagna resurser i FHIR-tjänsten.

Lägg till tillägget till resursen för att informera FHIR-tjänsten om att resursen har tagits bort mjukt.

{"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" } ] } }

När åtgärden import har slutförts utför du en historiksökning på resursen för att verifiera mjukt borttagna resurser. Om du känner till ID:t för den borttagna resursen använder du URL-mönstret i följande exempel.

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

Om du inte känner till resursens ID gör du en historiksökning på resurstypen.

<FHIR_URL>/<resource-type>/_history

Felsöka importåtgärden

Här följer de felmeddelanden som uppstår om åtgärden import misslyckas, tillsammans med rekommenderade åtgärder för att lösa problemen.

200 OK, men det finns ett fel med URL:en i svaret

Åtgärden import lyckas och returnerar 200 OK. Finns dock error.url i svarstexten. Filer som finns på platsen error.url innehåller JSON-fragment som liknar följande exempel.

{
    "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}"
        }
    ]
}

Orsak: NDJSON-filer innehåller resurser med villkorsstyrda referenser som import inte stöder.

Lösning: Ersätt de villkorsstyrda referenserna till normala referenser i NDJSON-filerna.

400 Felaktig begäran

Åtgärden import misslyckas och returnerar 400 Bad Request. Svarstexten innehåller diagnostikinnehåll

importåtgärden misslyckades av orsak: Ingen sådan värd är känd. (example.blob.core.windows.net:443) Lösning: Kontrollera att länken till Azure Storage är korrekt. Kontrollera nätverks- och brandväggsinställningarna för att se till att FHIR-servern kan komma åt lagringen. Om tjänsten finns i ett virtuellt nätverk kontrollerar du att lagringen finns i samma virtuella nätverk eller i ett virtuellt nätverk som är peerkopplat med FHIR-tjänstens virtuella nätverk.

SearchParameter-resurser kan inte bearbetas genom import Lösning: Importåtgärden returnerar ett HTTP 400-fel när en sökparameterresurs matas in via importprocessen. Den här ändringen är avsedd att förhindra att sökparametrar placeras i ett ogiltigt tillstånd när de matas in med en importåtgärd.

403 – Förbjuden

Åtgärden import misslyckas och returnerar 403 Forbidden. Svarstexten innehåller diagnostikinnehåll.

importåtgärden misslyckades av orsak: Servern kunde inte autentisera begäran. Kontrollera att värdet i auktoriseringshuvudet är rätt formaterat, inklusive signaturen. Orsak: FHIR-tjänsten använder en hanterad identitet för källlagringsautentisering. Det här felet anger en rolltilldelning som saknas eller är felaktig. Lösning: Tilldela rollen Storage Blob Data Contributor till FHIR-servern. Mer information finns i Tilldela Azure-roller.

500 Internt fel på servern

Åtgärden import misslyckas och returnerar 500 Internal Server Error. Svarstexten innehåller diagnostikinnehåll

importåtgärden misslyckades av orsak: Databasen ***** har nått sin storlekskvot. Partition eller ta bort data, ta bort index eller se dokumentationen för möjliga lösningar.

Orsak: Du har nått lagringsgränsen för FHIR-tjänsten.

Lösning: Minska storleken på dina data eller överväg Azure API för FHIR, som har en högre lagringsgräns.

423 Låst

Uppförande: Åtgärden import misslyckas och returnerar 423 Locked. Svarstexten innehåller följande innehåll:

{
    "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."
        }
    ]
}

Orsak: FHIR-tjänsten är konfigurerad med inledande importläge som blockerade andra åtgärder.

Lösning: Stäng av FHIR-tjänstens inledande importläge eller välj Inkrementellt läge.

Begränsningar

  • Det maximala antalet filer som tillåts för varje import åtgärd är 10 000.
  • Antalet filer som matas in på FHIR-servern med samma lastUpdated-fältvärde upp till millisekunder får inte överstiga 10 000.
  • Importåtgärden stöds inte för resurstypen SearchParameter.
  • Importåtgärden stöder inte villkorsstyrda referenser i resurser.

Nästa steg

Konvertera dina data till FHIR

Konfigurera exportinställningar och konfigurera ett lagringskonto

Kopiera data till Azure Synapse Analytics

Anmärkning

FHIR® är ett registrerat varumärke som tillhör HL7 och används med tillstånd av HL7.