Troubleshoot $convert-data

Artykuł
2025-04-12

Uwaga

In May 2024 we released a stand-alone FHIR® converter API decoupled from the FHIR service and packaged as a container (Docker) image for preview. Oprócz możliwości konwersji danych ze źródła rekordu na pakiety FHIR R4, konwerter FHIR oferuje wiele całkowicie nowych funkcji, takich jak:

Bidirectional data conversion from source of record to FHIR R4 bundles and back. Na przykład konwerter FHIR może konwertować dane z formatu FHIR R4 z powrotem na format HL7v2.
Ulepszone środowisko dostosowywania domyślnych szablonów Liquid .
Samples that demonstrate how to create an ETL (extract, transform, load) pipeline with Azure Data Factory (ADF).

Aby zaimplementować obraz kontenera FHIR Converter, zobacz projekt GitHub FHIR Converter.

In this article, learn how to troubleshoot $convert-data.

Wydajność

Two main factors come into play that determine how long a $convert-data operation call can take:

The size of the message.
The complexity of the template.

Any loops or iterations in the templates can have large impacts on performance. The $convert-data operation has a post processing step that is run after the template is applied. In particular, the deduping step can mask template issues that cause performance problems. Updating the template so duplicates aren’t generated can greatly increase performance. For more information and details about the post processing step, see Post processing.

Post processing

The $convert-data operation applies post processing logic after the template is applied to the input. This post processing logic can result in the output looking different, or unexpected errors compared to running the default Liquid template directly. Post processing ensures the output is valid JSON and removes any duplicates based on the ID properties generated for resources in the template. To see the post processing logic in more detail, see the FHIR-Converter GitHub repository.

Rozmiar komunikatu

There isn’t a hard limit on the size of the messages allowed for the $convert-data operation. However, for content with a request size greater than 10 MB, server errors 500 are possible. If you're receiving 500 server errors, ensure your requests are under 10 MB.

Template size and complexity

If you receive 504 Gateway Timeout errors, it may be the result of template processing time. Updating templates to reduce loops and iterations can greatly increase performance. Consider retrying your request with a smaller or simpler template.

Dlaczego daty są konwertowane podczas przekształcania danych JSON?

Istnieje możliwość zwracania dat podanych w danych JSON w innym formacie niż zostały podane. Podczas deserializacji ładunku JSON ciągi rozpoznawane jako daty są konwertowane na obiekty data/godzina platformy .NET. Te obiekty są następnie konwertowane z powrotem na ciągi przed przejściem przez silnik szablonów Liquid. This conversion can cause the date value to be reformatted, and represented in the local timezone of the FHIR service.

The coercion of strings to .NET DateTime objects can be disabled using the boolean parameter jsonDeserializationTreatDatesAsStrings. Po ustawieniu truewartości parametru podane dane są traktowane jako ciąg i nie zostaną zmodyfikowane przed dostarczeniem do silnika Liquid.

Default templates and customizations

Default template implementations for many common scenarios can be found on the FHIR-Converter GitHub repository. The default templates can be used as a guide and reference for customizing and creating your own templates. In addition to the default templates, the $convert-data operation supports several customer Liquid filters and tags that help simplify common scenarios.

Debugowanie i testowanie

In addition to testing templates on an instance of the service, a Visual Studio Code extension is available. The extension can be used to modify templates and test them with sample data payloads. There are also several existing test scenarios in the FHIR Converter GitHub repository that can be used as a reference.

Troubleshooting Azure Container Registry

When using Azure Container Registry (ACR) for custom template storage, if you encounter a "Failed to get access token for Azure Container Registry" error when reading templates, check to make sure that the correct role assignments are configured for the managed identity. Configure settings for $convert-data