Capacidades da API REST FHIR para a API do Azure para FHIR
Neste artigo, vamos abordar algumas das nuances das interações RESTful da API do Azure para FHIR.
Criação/atualização condicional
A API do Azure para FHIR suporta a criação, criação condicional, atualização e atualização condicional, conforme definido pela especificação FHIR. Um cabeçalho útil nestes cenários é o cabeçalho If-Match . O If-Match cabeçalho é utilizado e validará a versão que está a ser atualizada antes de efetuar a atualização. Se o ETag não corresponder ao esperado ETag, produzirá a mensagem de erro 412 Falha na Pré-condição.
Eliminar e Eliminar Condicional
A API do Azure para FHIR oferece dois tipos de eliminação. Existe a opção Eliminar, que também é conhecido como Hard + Soft Delete e Conditional Delete.
Eliminar (Hard + Soft Delete)
A eliminação definida pela especificação FHIR requer que, após eliminar um recurso, as leituras específicas subsequentes não relacionadas com a versão de um recurso devolvam um código de estado HTTP 410. Por conseguinte, o recurso já não é encontrado através da pesquisa. Além disso, a API do Azure para FHIR permite-lhe eliminar totalmente (incluindo todo o histórico) do recurso. Para eliminar totalmente o recurso, pode transmitir as definições de parâmetros hardDelete para true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Se não transmitir este parâmetro ou definir hardDelete como falso, as versões históricas do recurso continuarão disponíveis.
Nota
Se apenas quiser eliminar o histórico, a API do Azure para FHIR suporta uma operação personalizada chamada $purge-history. Esta operação permite-lhe eliminar o histórico de um recurso.
Eliminação Condicional
A Eliminação Condicional permite-lhe transmitir critérios de pesquisa para eliminar um recurso. Por predefinição, a Eliminação Condicional permite-lhe eliminar um item de cada vez. Também pode especificar o _count parâmetro para eliminar até 100 itens de cada vez. Seguem-se alguns exemplos de utilização da Eliminação Condicional.
Para eliminar um único item com a Eliminação Condicional, tem de especificar critérios de pesquisa que devolvem um único item.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Pode fazer a mesma pesquisa, mas incluir hardDelete=true também para eliminar todo o histórico.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Para eliminar vários recursos, inclua o _count=100 parâmetro . Este parâmetro eliminará até 100 recursos que correspondam aos critérios de pesquisa.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Recuperação de ficheiros eliminados
Se não utilizar o parâmetro de eliminação dura, os registos na API do Azure para FHIR ainda deverão existir. Os registos podem ser encontrados ao fazer uma pesquisa de histórico no recurso e à procura da última versão com dados.
Se o ID do recurso que foi eliminado for conhecido, utilize o seguinte padrão de URL:
<FHIR_URL>/<resource-type>/<resource-id>/_history
Por exemplo: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/123456789/_history
Se o ID do recurso não for conhecido, efetue uma pesquisa de histórico em todo o tipo de recurso:
<FHIR_URL>/<resource-type>/_history
Por exemplo: https://myworkspace-myfhirserver.fhir.azurehealthcareapis.com/Patient/_history
Depois de encontrar o registo que pretende restaurar, utilize a PUT operação para recriar o recurso com o mesmo ID ou utilize a POST operação para criar um novo recurso com as mesmas informações.
Nota
Não existe expiração baseada no tempo para dados de histórico/eliminação recuperável. A única forma de remover dados de histórico/eliminação recuperável é com uma eliminação rápida ou a operação do histórico de remoção.
Patch e Patch Condicional
Patch é uma operação RESTful valiosa quando precisa de atualizar apenas uma parte do recurso FHIR. A utilização de patch permite-lhe especificar os elementos que pretende atualizar no recurso sem ter de atualizar todo o registo. O FHIR define três formas de Corrigir recursos: Patch JSON, Patch XML e FHIRPath Patch. O Serviço FHIR suporta patch JSON e FHIRPath Patch juntamente com Patch JSON Condicional e Patch FHIRPath Condicional (que lhe permite Corrigir um recurso com base em critérios de pesquisa em vez de um ID de recurso). Para ver alguns exemplos, veja o ficheiro REST de Patch FHIRPath de exemplo e o ficheiro REST de Patch JSON para cada abordagem. Para obter detalhes adicionais, leia a documentação do HL7 para operações de patch com fHIR.
Nota
Ao utilizar PATCH o STU3 e, se estiver a pedir um pacote Histórico, o recurso Bundle.entry.request.method corrigido é mapeado para PUT. Isto deve-se ao facto de o STU3 não conter uma definição para o PATCH verbo no conjunto de valores HTTPVerb.
Patch com FHIRPath Patch
Este método de patch é o mais poderoso, uma vez que tira partido do FHIRPath para selecionar o elemento a atingir. Um cenário comum é utilizar o Patch FHIRPath para atualizar um elemento numa lista sem saber a ordem da lista. Por exemplo, se quiser eliminar as informações de telecomunicações domésticas de um paciente sem conhecer o índice, pode utilizar o exemplo abaixo.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo de conteúdo: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "operation",
"part": [
{
"name": "type",
"valueCode": "delete"
},
{
"name": "path",
"valueString": "Patient.telecom.where(use = 'home')"
}
]
}
]
}
Todas as operações de Patch FHIRPath têm de ter o application/fhir+json cabeçalho Tipo de Conteúdo definido. O Patch FHIRPatch suporta operações de adicionar, inserir, eliminar, remover e mover. As operações de Patch FHIRPatch também podem ser facilmente integradas em Pacotes. Para obter mais exemplos, veja o ficheiro REST do Patch FHIRPath de exemplo.
Patch com Patch JSON
O Patch JSON no Serviço FHIR está em conformidade com a especificação bem utilizada definida pela Força-Tarefa de Engenharia da Internet. O formato payload não utiliza recursos FHIR e, em vez disso, utiliza um documento JSON que tira partido JSON-Pointers para a seleção de elementos. O Patch JSON é mais compacto e tem uma operação de teste que lhe permite validar que uma condição é verdadeira antes de efetuar o patch. Por exemplo, se quiser definir um paciente como falecido apenas se ainda não estiver marcado como falecido, pode utilizar o exemplo abaixo.
PATCH http://{FHIR-SERVICE-HOST-NAME}/Patient/{PatientID}
Tipo de conteúdo: application/json-patch+json
[
{
"op": "test",
"path": "/deceasedBoolean",
"value": false
},
{
"op": "replace",
"path": "/deceasedBoolean",
"value": true
}
]
Todas as operações de Patch JSON têm de ter o application/json-patch+json cabeçalho Tipo de Conteúdo definido. O Patch JSON suporta operações de adicionar, remover, substituir, copiar, mover e testar. Para obter mais exemplos, veja o ficheiro REST de Patch JSON de exemplo.
Patch JSON em Pacotes
Por predefinição, o Patch JSON não é suportado nos recursos do Pacote. Isto acontece porque um Pacote só suporta recursos FHIR e o payload de Patch JSON não é um recurso FHIR. Para resolver este problema, vamos utilizar recursos binários com um Tipo de "application/json-patch+json" Conteúdo e a codificação base64 do payload JSON dentro de um Pacote. Para obter informações sobre esta solução, veja este tópico no Zulip de Chat FHIR.
No exemplo abaixo, queremos mudar o sexo do paciente para feminino. Tomámos o patch [{"op":"replace","path":"/gender","value":"female"}] JSON e codificamo-lo para base64.
POST https://{FHIR-SERVICE-HOST-NAME}/
Tipo de Conteúdo: application/json
{
"resourceType": "Bundle",
"id": "bundle-batch",
"type": "batch",
"entry": [
{
"fullUrl": "Patient/{PatientID}",
"resource": {
"resourceType": "Binary",
"contentType": "application/json-patch+json",
"data": "W3sib3AiOiJyZXBsYWNlIiwicGF0aCI6Ii9nZW5kZXIiLCJ2YWx1ZSI6ImZlbWFsZSJ9XQ=="
},
"request": {
"method": "PATCH",
"url": "Patient/{PatientID}"
}
}
]
}
Passos seguintes
Neste artigo, ficou a conhecer algumas das capacidades REST da API do Azure para FHIR. Em seguida, pode saber mais sobre os principais aspetos da pesquisa de recursos no FHIR.
(FHIR®) é uma marca registada do HL7 e é utilizada com a permissão de HL7.