Recursos da API REST do FHIR para a API do Azure para FHIR
Neste artigo, abordaremos algumas das nuances das interações RESTful da API do Azure para FHIR.
Criação/atualização condicional
A API do Azure para FHIR dá suporte à criação, criação condicional, atualização e atualização condicional, conforme definido pela especificação FHIR. Um cabeçalho útil nesses cenários é o cabeçalho If-Match . O If-Match cabeçalho é usado e validará a versão que está sendo atualizada antes de fazer a atualização. Se o ETag não corresponder ao esperado ETag, ele produzirá a mensagem de erro 412 Precondition Failed.
Excluir e Excluir Condicional
A API do Azure para FHIR oferece dois tipos de exclusão. Há Delete, que também é conhecido como Hard + Soft Delete e Exclusão Condicional.
Excluir (Exclusão Reversível + Exclusão Temporária)
A exclusão definida pela especificação FHIR exige que, após a exclusão de um recurso, as leituras específicas subsequentes não da versão de um recurso retornem um código de status HTTP 410. Portanto, o recurso não é mais encontrado por meio da pesquisa. Além disso, a API do Azure para FHIR permite que você exclua totalmente (incluindo todo o histórico) do recurso. Para excluir totalmente o recurso, você pode passar uma configuração hardDelete de parâmetro para true (DELETE {{FHIR_URL}}/{resource}/{id}?hardDelete=true). Se você não passar esse parâmetro ou definir hardDelete como false, as versões históricas do recurso ainda estarão disponíveis.
Observação
Se você quiser apenas excluir o histórico, a API do Azure para FHIR dá suporte a uma operação personalizada chamada $purge-history. Essa operação permite que você exclua o histórico de um recurso.
Exclusão condicional
A Exclusão Condicional permite que você passe os critérios de pesquisa para excluir um recurso. Por padrão, a Exclusão Condicional permite que você exclua um item por vez. Você também pode especificar o _count parâmetro para excluir até 100 itens por vez. Abaixo estão alguns exemplos de como usar a Exclusão Condicional.
Para excluir um único item usando Exclusão Condicional, você deve especificar critérios de pesquisa que retornam um único item.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704
Você pode fazer a mesma pesquisa, mas incluir hardDelete=true para também excluir todo o histórico.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&hardDelete=true
Para excluir vários recursos, inclua _count=100 o parâmetro . Esse parâmetro excluirá até 100 recursos que correspondem aos critérios de pesquisa.
DELETE https://{{FHIR_URL}}/Patient?identifier=1032704&_count=100
Recuperação de arquivos excluídos
Se você não usar o parâmetro hard delete, os registros na API do Azure para FHIR ainda deverão existir. Os registros podem ser encontrados fazendo uma pesquisa de histórico no recurso e procurando a última versão com dados.
Se a ID do recurso que foi excluído for conhecida, use 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 a ID do recurso não for conhecida, faça 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 registro que deseja restaurar, use a PUT operação para recriar o recurso com a mesma ID ou use a POST operação para criar um novo recurso com as mesmas informações.
Observação
Não há expiração baseada em tempo para dados de histórico/exclusão temporária. A única maneira de remover dados excluídos de histórico/soft é com uma exclusão rígida ou a operação de histórico de limpeza.
Patch e Patch Condicional
Patch é uma operação RESTful valiosa quando você precisa atualizar apenas uma parte do recurso FHIR. O uso de patch permite que você especifique os elementos que deseja atualizar no recurso sem precisar atualizar todo o registro. O FHIR define três maneiras de corrigir recursos: Patch JSON, Patch XML e Patch FHIRPath. O Serviço FHIR dá suporte ao Patch JSON e ao Patch FHIRPath juntamente com patch JSON condicional e patch FHIRPath condicional (que permite corrigir um recurso com base em critérios de pesquisa em vez de uma ID de recurso). Para percorrer alguns exemplos, consulte o arquivo REST de patch FHIRPath de exemplo e o arquivo REST de Patch JSON para cada abordagem. Para obter detalhes adicionais, leia a documentação HL7 para operações de patch com FHIR.
Observação
Ao usar PATCH no STU3 e se você estiver solicitando um pacote de Histórico, o do recurso Bundle.entry.request.method corrigido será mapeado para PUT. Isso ocorre porque o STU3 não contém uma definição para o PATCH verbo no conjunto de valores HTTPVerb.
Patch com patch FHIRPath
Esse método de patch é o mais poderoso, pois aproveita o FHIRPath para selecionar qual elemento deve ser direcionado. Um cenário comum é usar o Patch FHIRPath para atualizar um elemento em uma lista sem saber a ordem da lista. Por exemplo, se você quiser excluir as informações de telecomunicações domésticas de um paciente sem saber o índice, poderá usar 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 devem ter o application/fhir+json cabeçalho Content-Type definido. O Patch FHIRPatch dá suporte a operações de adição, inserção, exclusão, remoção e movimentação. As operações de Patch FHIRPatch também podem ser facilmente integradas aos Pacotes. Para obter mais exemplos, examine o arquivo REST de patch FHIRPath de exemplo.
Patch com Patch JSON
O Patch JSON no Serviço FHIR está em conformidade com a especificação bem usada definida pela Força-Tarefa de Engenharia da Internet. O formato de carga não usa recursos FHIR e, em vez disso, usa um documento JSON aproveitando JSON-Pointers para seleção de elementos. O Patch JSON é mais compacto e tem uma operação de teste que permite validar se uma condição é verdadeira antes de fazer o patch. Por exemplo, se você quiser definir um paciente como falecido somente se ele ainda não estiver marcado como falecido, poderá usar 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 devem ter o application/json-patch+json cabeçalho Tipo de Conteúdo definido. O Patch JSON dá suporte a operações de adicionar, remover, substituir, copiar, mover e testar. Para obter mais exemplos, examine o arquivo REST de patch JSON de exemplo.
Patch JSON em pacotes
Por padrão, não há suporte para Patch JSON em Recursos de pacote. Isso ocorre porque um Pacote só dá suporte a recursos FHIR e o conteúdo do Patch JSON não é um recurso FHIR. Para contornar isso, usaremos recursos binários com um Tipo de Conteúdo de "application/json-patch+json" e a codificação base64 da carga JSON dentro de um Pacote. Para obter informações sobre essa solução alternativa, exiba este tópico no Chat Zulip do FHIR.
No exemplo a seguir, queremos alterar o gênero do paciente para o feminino. Usamos o patch [{"op":"replace","path":"/gender","value":"female"}] JSON e o codificamos 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}"
}
}
]
}
Próximas etapas
Neste artigo, você aprendeu sobre alguns dos recursos REST da API do Azure para FHIR. Em seguida, você pode saber mais sobre os principais aspectos para pesquisar recursos no FHIR.
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.