Import dat FHIR

2025-06-23

Tuto import operaci můžete použít k ingestování dat FHIR® na server FHIR s vysokou propustností.

Režimy operací importu

Operace import podporuje dva režimy: počáteční a přírůstkový. Každý režim má jiné funkce a případy použití.

Počáteční režim

Určeno pro načítání prostředků FHIR na prázdný server FHIR.
Blokuje zápisy rozhraní API na server FHIR.

Přírůstkový režim

Je optimalizován pro pravidelné načítání dat na server FHIR a neblokuje zápisy prostřednictvím rozhraní API.
Umožňuje načíst lastUpdated hodnoty a versionId hodnoty z metadat prostředků, pokud jsou přítomny ve formátu JSON prostředku.
Umožňuje načítat prostředky v nesekvenčním pořadí verzí. Poznámka k nesekvenčnímu příjmu prostředků
- Pokud soubory importu version nemají zadané hodnoty polí a lastUpdated , neexistuje žádná záruka importu všech prostředků ve službě FHIR.
- Pokud importované soubory obsahují prostředky s duplicitními version hodnotami a lastUpdated hodnotami polí, ve službě FHIR se náhodně ingestuje pouze jeden prostředek.
- Pokud během paralelního spouštění sdílí více prostředků stejné ID prostředku, náhodně se importuje pouze jeden z těchto prostředků.

Následující tabulka ukazuje rozdíl mezi režimy importu.

Oblasti	Počáteční režim	Přírůstkový režim
Schopnost	Počáteční načtení dat do služby FHIR	Průběžný příjem dat do služby FHIR (přírůstkový nebo téměř v reálném čase).
Souběžná volání rozhraní API	Blokuje souběžné operace zápisu	Data je možné ingestovat souběžně při provádění operací rozhraní API CRUD na serveru FHIR.
Příjem prostředků s verzí	Nepodporováno	Umožňuje příjem více verzí prostředků FHIR v jedné dávce při zachování historie prostředků.
Zachovat hodnotu pole lastUpdated	Nepodporováno	Během procesu příjmu dat zachovejte hodnotu pole lastUpdated v prostředcích FHIR.
Fakturování	Není zpoplatněn	Na základě úspěšně přijatých prostředků se účtují poplatky. Poplatky se účtují za jednotlivé ceny rozhraní API.

Důležité informace o výkonu

Chcete-li dosáhnout nejlepšího výkonu operace import , zvažte následující faktory.

Pro import použijte velké soubory. Optimální velikost souboru NDJSON pro import je >=50 MB (nebo >=20 kB zdrojů, bez horního limitu). Zvažte kombinování menších souborů dohromady.
Importujte soubory prostředků FHIR jako jednu dávku. Pro zajištění optimálního výkonu importujte všechny soubory prostředků FHIR, které chcete ingestovat na serveru FHIR, v jedné import operaci. Import všech souborů v jedné operaci snižuje režii spojenou s vytvářením a správou více úloh importu. V optimálním případě by měla být celková velikost souborů v jednom importu velká (>= 100 GB nebo >= 100 milionů zdrojů, bez horního limitu).
Omezte počet úloh paralelního importu. Můžete spustit více import úloh současně, ale může to ovlivnit celkovou propustnost import operace.

Proveďte operaci importu

Požadavky

Abyste mohli tuto import operaci použít, potřebujete na serveru FHIR roli importéra dat FHIR .
Nakonfigurujte server FHIR. Data FHIR musí být uložená v souborech specifických pro prostředky ve formátu FHIR NDJSON v úložišti objektů blob Azure. Další informace naleznete v tématu Konfigurace nastavení importu.
Data musí být ve stejném tenantovi jako služba FHIR.
Informace o získání přístupového tokenu naleznete v tématu Přístupový token

Volání

POST Proveďte volání s <<FHIR service base URL>>/$import následující hlavičkou a textem požadavku.

Hlavička požadavku

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

Tělo

Následující tabulky popisují parametry těla a vstupy.

Název parametru	Popis	Kardinalita	Přípustné hodnoty
`inputFormat`	Řetězec představující název formátu zdroje dat. Podporovány jsou pouze soubory FHIR NDJSON.	1..1	`application/fhir+ndjson`
`mode`	Hodnota režimu importu.	1..1	Pro import v počátečním režimu použijte `InitialLoad` hodnotu mode. Pro import v přírůstkovém `IncrementalLoad` režimu použijte hodnotu mode. Pokud nezadáte hodnotu režimu, `IncrementalLoad` použije se ve výchozím nastavení hodnota režimu.
`allowNegativeVersions`	Umožňuje serveru FHIR přiřazovat záporné verze pro záznamy o prostředcích s explicitní hodnotou lastUpdated a bez zadané verze, pokud se vstup nevejde do souvislého prostoru kladných verzí existujících v úložišti.	0..1	Chcete-li tuto funkci povolit, předejte hodnotu true. Ve výchozím nastavení je to false.
`errorContainerName`	Řetězec představující název kontejneru, ve kterém budou protokolovány chyby zjištěné během procesu importu.	0..1	Vlastní název kontejneru pro protokoly chyb. Název by měl mít 3 až 63 znaků a měl by obsahovat pouze malá písmena, číslice a spojovníky. Pokud není zadaný, použije se výchozí kontejner.
`input`	Podrobnosti o vstupních souborech.	1..*	Pole JSON se třemi částmi popsanými v následující tabulce.

Název vstupní části	Popis	Kardinalita	Přípustné hodnoty
`type`	Typ prostředku vstupního souboru.	0..1	Platný typ prostředku FHIR , který odpovídá vstupnímu souboru. Toto pole je volitelné.
`url`	Adresa URL vstupního souboru služby Azure Storage.	1..1	Hodnota URL vstupního souboru. Hodnotu nelze změnit.
`etag`	Značka ETag vstupního souboru v úložišti Azure. Slouží k ověření, zda se obsah souboru po `import` registraci nezměnil.	0..1	ETag vstupního souboru.

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

Kontrola stavu importu

Po spuštění import operace se v callback hlavičce odpovědi vrátí prázdný text Content-location odpovědi s odkazem spolu se stavovým kódem202 Accepted. callback Uložte odkaz a zkontrolujte stav importu.

Registrace import operace je implementována jako idempotentní volání. Stejná datová část registrace poskytuje stejnou registraci, což ovlivňuje schopnost znovu zpracovat soubory se stejným názvem. Neaktualizujte soubory na místě. Místo toho doporučujeme použít pro aktualizovaná data jiný název souboru. Nebo, pokud je místní aktualizace se stejným názvem souboru nevyhnutelná, přidejte značky ETag do datové části registrace.

Chcete-li zkontrolovat stav importu, proveďte volání REST s GET metodou k odkazu vrácenému callback v předchozím kroku.

Interpretujte odpověď pomocí této tabulky.

Kód odpovědi	Obsah odpovědi	Popis
`202 Accepted`		Operace je stále spuštěná.
`200 OK`	`The response body doesn't contain any error.url entry`	Všechny prostředky byly úspěšně importovány.
`200 OK`	`The response body contains some error.url entry`	Při importu některých zdrojů došlo k chybě. Podrobnosti naleznete v souborech umístěných na adrese `error.url`. Zbývající prostředky byly úspěšně importovány.
`Other`		Došlo k závažné chybě a operace byla zastavena. Úspěšně importované prostředky se nevrátí zpět.

Následující tabulka popisuje důležitá pole v textu odpovědi:

Obor	Popis
`transactionTime`	Čas zahájení hromadné `import` operace.
`output.count`	Počet prostředků, které byly úspěšně importovány.
`error.count`	Počet prostředků, které nebyly importovány kvůli chybě.
`error.url`	Adresa URL souboru, který obsahuje podrobnosti o chybě. Každá `error.url` instance je jedinečná pro vstupní adresu 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"
        }
    ]
}

Ingestování obnovitelně odstraněných prostředků

Import v přírůstkovém režimu podporuje příjem obnovitelně odstraněných prostředků. Rozšíření musíte použít k ingestování obnovitelně odstraněných prostředků ve službě FHIR.

Přidejte rozšíření do prostředku, abyste informovali službu FHIR, že byl prostředek obnovitelně odstraněn.

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

import Po úspěšném dokončení operace proveďte vyhledávání v historii prostředku a ověřte obnovitelně odstraněné prostředky. Pokud znáte ID odstraněného prostředku, použijte vzor adresy URL v následujícím příkladu.

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

Pokud neznáte ID zdroje, proveďte hledání v historii podle typu zdroje.

<FHIR_URL>/<resource-type>/_history

Řešení problémů s operací importu

Zde jsou uvedeny chybové zprávy, které se zobrazí v případě import selhání operace, spolu s doporučenými akcemi k vyřešení problémů.

200 OK, ale v odpovědi je chyba s adresou URL

Operace import je úspěšná a vrátí .200 OK error.url Je však přítomen v textu odpovědi. Soubory přítomné v tomto error.url umístění obsahují fragmenty JSON podobné následujícímu příkladu.

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

Příčina: Soubory NDJSON obsahují prostředky s podmíněnými odkazy, které import nepodporují.

Řešení: Nahraďte podmíněné odkazy za normální odkazy v souborech NDJSON.

400 – Chybný požadavek

Operace import se nezdaří a vrátí soubor 400 Bad Request. Tělo odpovědi obsahuje diagnostický obsah.

Operace importu se nezdařila z důvodu: Žádný takový hostitel není znám. (example.blob.core.windows.net:443) Řešení: Ověřte, zda je odkaz na úložiště Azure správný. Zkontrolujte nastavení sítě a brány firewall a ujistěte se, že server FHIR má přístup k úložišti. Pokud je vaše služba ve virtuální síti, zajistěte, aby úložiště bylo ve stejné virtuální síti nebo ve virtuální síti, která je propojena s virtuální sítí služby FHIR.

Prostředky SearchParameter nelze zpracovat importem Řešení: Operace importu vrátí chybu HTTP 400 při ingestování prostředku parametru vyhledávání prostřednictvím procesu importu. Cílem této změny je zabránit tomu, aby se parametry hledání při ingestování s operací importu umístily do neplatného stavu.

403 Zakázáno

Operace import se nezdaří a vrátí soubor 403 Forbidden. Tělo odpovědi obsahuje diagnostický obsah.

Operace importu se nezdařila z důvodu: Serveru se nepodařilo ověřit požadavek. Ujistěte se, že má autorizační hlavička správný formát včetně podpisu. Příčina: Služba FHIR používá k ověřování zdrojového úložiště spravovanou identitu. Tato chyba značí chybějící nebo nesprávné přiřazení role. Řešení: Přiřaďte roli Přispěvatel dat objektů blob úložiště k serveru FHIR. Další informace najdete v tématu Přiřazení rolí Azure.

500 – Vnitřní chyba serveru

Operace import se nezdaří a vrátí soubor 500 Internal Server Error. Tělo odpovědi obsahuje diagnostický obsah.

Operace importu se nezdařila z důvodu: Databáze '****' dosáhla své kvóty velikosti. Vytvořte oddíl nebo odstraňte data, přetáhněte indexy nebo najděte možná řešení v dokumentaci.

Příčina: Dosáhli jste limitu úložiště služby FHIR.

Řešení: Zmenšete velikost dat nebo zvažte rozhraní Azure API for FHIR, které má vyšší limit úložiště.

423 Uzamčeno

Chování: Operace import se nezdaří a vrátí soubor 423 Locked. Tělo odpovědi zahrnuje tento obsah:

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

Příčina: Služba FHIR je nakonfigurovaná s režimem počátečního importu, který zablokoval jiné operace.

Řešení: Vypněte režim počátečního importu služby FHIR nebo vyberte přírůstkový režim.

Omezení

Maximální počet souborů povolených pro každou import operaci je 10 000.
Počet souborů ingestovaných na serveru FHIR se stejnou hodnotou pole lastUpdated až do milisekund nesmí překročit 10 000.
Operace importu není pro typ prostředku SearchParameter podporovaná.
Operace importu nepodporuje podmíněné reference v prostředcích.

Další kroky

Převod dat na FHIR

Konfigurace nastavení exportu a nastavení účtu úložiště

Kopírování dat do Azure Synapse Analytics

Poznámka:

FHIR® je registrovaná ochranná známka HL7 a používá se s povolením HL7.