Operacja importowania
Operacja importowania umożliwia ładowanie danych Fast Healthcare Interoperability Resources (FHIR) do serwera FHIR® o wysokiej przepływności przy użyciu operacji $import. Importowanie obsługuje zarówno początkowe, jak i przyrostowe ładowanie danych do serwera FHIR.
Korzystanie z operacji $import
Uwaga
Aby używać $import, musisz mieć rolę importera danych FHIR na serwerze FHIR.
Aby użyć $import, należy skonfigurować serwer FHIR, korzystając z instrukcji w artykule Konfigurowanie ustawień importu . Dane FHIR do zaimportowania muszą być przechowywane w plikach specyficznych dla zasobów w formacie FHIR NDJSON w magazynie obiektów blob platformy Azure.
W przypadku operacji importowania upewnij się, że
- Wszystkie zasoby w pliku muszą być tego samego typu. Być może istnieje wiele plików na typ zasobu.
- Dane do zaimportowania muszą znajdować się w tej samej dzierżawie co usługa FHIR.
- Maksymalna liczba plików do zaimportowania na operację wynosi 10 000.
Uwaga:
- Operacja importowania nie obsługuje odwołań warunkowych w zasobach.
- Podczas operacji importowania, jeśli wiele zasobów współużytkuje ten sam identyfikator zasobu, importuje się losowo tylko jeden z tych zasobów. Dla zasobów współużytkowanych ten sam identyfikator zasobu jest rejestrowany błąd.
Wywoływanie $import
Wywołaj metodę za <<FHIR service base URL>>/$import pomocą nagłówka POST żądania i wyświetlanej treści:
Nagłówek żądania
Prefer:respond-async
Content-Type:application/fhir+json
Treść
| Nazwa parametru | Opis | Karty. | Dopuszczalne wartości |
|---|---|---|---|
| inputFormat | Ciąg reprezentujący nazwę formatu źródła danych. Obecnie obsługiwane są tylko pliki FHIR NDJSON. | 1..1 | application/fhir+ndjson |
| tryb | Wartość trybu importu | 1..1 | W przypadku początkowej wartości trybu użycia InitialLoad importu. W przypadku wartości trybu importu przyrostowego użyj IncrementalLoad wartości trybu. Jeśli nie zostanie podana żadna wartość trybu, wartość trybu incrementalLoad jest domyślnie uznawana za wartość. |
| wejście | Szczegóły plików wejściowych. | 1..* | Tablica JSON z trzema częściami opisanymi w poniższej tabeli. |
| Nazwa części wejściowej | Opis | Karty. | Dopuszczalne wartości |
|---|---|---|---|
| typ | Typ zasobu pliku wejściowego | 1..1 | Prawidłowy typ zasobu FHIR zgodny z plikiem wejściowym. |
| Adres URL | Adres URL usługi Azure Storage pliku wejściowego | 1..1 | Wartość adresu URL pliku wejściowego, którego nie można zmodyfikować. |
| Etag | Etag pliku wejściowego w usłudze Azure Storage używany do sprawdzania, czy zawartość pliku nie została zmieniona. | 0..1 | Wartość Etag pliku wejściowego, którego nie można zmodyfikować. |
Przykładowa treść importu początkowego obciążenia:
{
"resourceType": "Parameters",
"parameter": [
{
"name": "inputFormat",
"valueString": "application/fhir+ndjson"
},
{
"name": "mode",
"valueString": "InitialLoad"
},
{
"name": "input",
"part": [
{
"name": "type",
"valueString": "Patient"
},
{
"name": "url",
"valueUri": "https://example.blob.core.windows.net/resources/Patient.ndjson"
},
{
"name": "etag",
"valueUri": "0x8D92A7342657F4F"
}
]
},
{
"name": "input",
"part": [
{
"name": "type",
"valueString": "CarePlan"
},
{
"name": "url",
"valueUri": "https://example.blob.core.windows.net/resources/CarePlan.ndjson"
}
]
}
]
}
Sprawdzanie stanu importu
Po zainicjowaniu $import pusta treść odpowiedzi z linkiem wywołania zwrotnego jest zwracana w Content-location nagłówku odpowiedzi wraz z 202-Accepted kodem stanu. Zapisz ten link wywołania zwrotnego, aby sprawdzić stan importu.
Aby sprawdzić stan importu, wykonaj wywołanie REST za pomocą GET metody do linku wywołania zwrotnego zwróconego w poprzednim kroku.
Odpowiedź można interpretować przy użyciu poniższej tabeli:
| Kod odpowiedzi | Treść odpowiedzi | Opis |
|---|---|---|
| Zaakceptowano 202 | Operacja jest nadal uruchomiona. | |
| 200 OK | Treść odpowiedzi nie zawiera wpisu error.url | Wszystkie zasoby zostały pomyślnie zaimportowane. |
| 200 OK | Treść odpowiedzi zawiera wpis error.url | Wystąpił błąd podczas importowania niektórych zasobów. Aby uzyskać szczegółowe informacje, zobacz pliki znajdujące się pod adresem error.url. Pozostałe zasoby zostały pomyślnie zaimportowane. |
| Inne | Wystąpił błąd krytyczny i operacja została zatrzymana. Pomyślnie zaimportowane zasoby nie zostały wycofane. |
Poniższa tabela zawiera niektóre z ważnych pól w treści odpowiedzi:
| Pole | Opis |
|---|---|
| transactionTime | Godzina rozpoczęcia operacji importu zbiorczego. |
| output.count | Liczba zasobów, które zostały pomyślnie zaimportowane |
| error.count | Liczba zasobów, które nie zostały zaimportowane z powodu błędu |
| error.url | Adres URL pliku zawierającego szczegóły błędu. Każdy adres error.url jest unikatowy dla wejściowego adresu URL. |
Przykładowa odpowiedź:
{
"transactionTime": "2021-07-16T06:46:52.3873388+00:00",
"request": "https://importperf.azurewebsites.net/$Import",
"output": [
{
"type": "Patient",
"count": 10000,
"inputUrl": "https://example.blob.core.windows.net/resources/Patient.ndjson"
},
{
"type": "CarePlan",
"count": 199949,
"inputUrl": "https://example.blob.core.windows.net/resources/CarePlan.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"
}
]
}
Rozwiązywanie problemów
Umożliwia przewodnik po rozwiązaniach niektórych kodów błędów, które mogą wystąpić podczas operacji importowania.
200 OK, ale w odpowiedzi występuje błąd z adresem URL
Zachowanie: Operacja importowania kończy się powodzeniem i zwraca wartość 200 OK. error.url Jednak są obecne w treści odpowiedzi. Pliki obecne w error.url lokalizacji zawierają fragmenty JSON podobne do poniższego przykładu:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"details": {
"text": "Given conditional reference '{0}' does'nt resolve to a resource."
},
"diagnostics": "Failed to process resource at line: {0} with stream start offset: {1}"
}
]
}
Spowodować: Pliki NDJSON zawierają zasoby z odwołaniami warunkowymi, które nie są obecnie obsługiwane przez $import.
Rozwiązanie: Zastąp odwołania warunkowe do normalnych odwołań w plikach NDJSON.
400 Nieprawidłowe żądanie
Zachowanie: Operacja importowania nie powiodła się i 400 Bad Request została zwrócona. Treść odpowiedzi ma następującą zawartość:
{
"resourceType": "OperationOutcome",
"id": "13876ec9-3170-4525-87ec-9e165052d70d",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: No such host is known. (example.blob.core.windows.net:443)"
}
]
}
Rozwiązanie: Sprawdź, czy łącze do usługi Azure Storage jest poprawne. Sprawdź ustawienia sieci i zapory, aby upewnić się, że serwer FHIR może uzyskać dostęp do magazynu. Jeśli twoja usługa znajduje się w sieci wirtualnej, upewnij się, że magazyn znajduje się w tej samej sieci wirtualnej lub w sieci wirtualnej, która ma komunikację równorzędną z siecią wirtualną usługi FHIR.
403 Zabronione
Zachowanie: Operacja importowania nie powiodła się i 403 Forbidden została zwrócona. Treść odpowiedzi zawiera następującą zawartość:
{
"resourceType": "OperationOutcome",
"id": "bd545acc-af5d-42d5-82c3-280459125033",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: Server failed to authenticate the request. Make sure the value of Authorization header is formed correctly including the signature."
}
]
}
Spowodować: Do uwierzytelniania magazynu źródłowego używamy tożsamości zarządzanej. Ten błąd może być spowodowany brakiem lub nieprawidłowym przypisaniem roli.
Rozwiązanie: Przypisz rolę Współautor danych obiektu blob usługi Storage do serwera FHIR, postępując zgodnie z przewodnikiem RBAC.
500 Wewnętrzny błąd serwera
Zachowanie: Operacja importowania nie powiodła się i 500 Internal Server Error została zwrócona. Treść odpowiedzi ma następującą zawartość:
{
"resourceType": "OperationOutcome",
"id": "0d0f007d-9e8e-444e-89ed-7458377d7889",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "import operation failed for reason: The database '****' has reached its size quota. Partition or delete data, drop indexes, or consult the documentation for possible resolutions."
}
]
}
Spowodować: Osiągnięto limit magazynu usługi FHIR.
Rozwiązanie: Zmniejsz rozmiar danych lub rozważ użycie interfejsu API platformy Azure dla platformy FHIR, który ma wyższy limit magazynu.
Następne kroki
W tym artykule przedstawiono sposób, w jaki operacja importowania umożliwia importowanie danych FHIR do serwera FHIR przy wysokiej przepływności. Aby uzyskać więcej informacji na temat konwertowania danych na FHIR, eksportowania ustawień w celu skonfigurowania konta magazynu i przenoszenia danych do Azure Synapse, zobacz
FHIR® jest zastrzeżonym znakiem towarowym HL7 i jest używany z uprawnieniem HL7 .