Acessar o serviço FHIR usando o Postman
Este artigo mostra as etapas para acessar o serviço FHIR® nos Serviços de Dados de Saúde do Azure com o Postman.
Pré-requisitos
- Serviço FHIR implantado no Azure. Para obter mais informações, confira Implantar um serviço FHIR.
- Um aplicativo cliente registrado para acessar o serviço FHIR. Para obter mais informações, confira Registrar um aplicativo cliente de serviço no Microsoft Entra ID.
- Permissões de Colaborador de Dados do FHIR concedidas ao aplicativo cliente e sua conta de usuário.
- Postman instalado localmente. Para obter mais informações, confira Introdução ao Postman.
Criar um espaço de trabalho, uma coleção e um ambiente
Se estiver apenas começando a usar o Postman, siga essas etapas para criar um espaço de trabalho, uma coleção e um ambiente.
O Postman introduz o conceito de espaço de trabalho para permitir que você e sua equipe compartilhem APIs, coleções, ambientes e outros componentes. Você pode usar o Meu espaço de trabalho ou o Espaço de trabalho de equipe padrão ou criar um novo espaço de trabalho para você ou sua equipe.
Em seguida, crie uma nova coleção na qual você pode agrupar todas as solicitações de API REST relacionadas. No espaço de trabalho, selecione Criar Coleções. Você pode manter o nome padrão Nova coleção ou renomeá-la. A alteração é salva automaticamente.
Você também pode importar e exportar coleções do Postman. Para saber mais, confira a Documentação do Postman.
Criar ou atualizar variáveis de ambiente
Embora você possa usar a URL completa na solicitação, recomendamos que armazene a URL e outros dados em variáveis.
Para acessar o serviço FHIR, você precisa criar ou atualizar essas variáveis:
Variável | Descrição | Observações |
---|---|---|
tenantid | Locatário do Azure em que o serviço FHIR está implantado | Localizado na visão geral do registro do Aplicativo |
subid | Assinatura do Azure em que o serviço FHIR está implantado | Localizada na visão geral do serviço FHIR |
clientid | ID de registro do cliente do aplicativo | - |
clientsecret | Segredo do registro do cliente do aplicativo | - |
fhirurl | A URL completa do serviço FHIR (por exemplo, https://xxx.azurehealthcareapis.com ) |
Localizada na visão geral do serviço FHIR |
bearerToken | Armazena o token de acesso do Microsoft Entra no script | Deixar em branco |
Observação
Certifique-se de que você configurou a URL de redirecionamento https://www.getpostman.com/oauth2/callback
no registro do aplicativo cliente.
Obter a instrução de funcionalidade
Insira {{fhirurl}}/metadata
na solicitação GET
e, em seguida, escolha Send
. Você deverá ver a instrução de funcionalidade do serviço FHIR.
Obter um token de acesso do Microsoft Entra
Obtenha um token de acesso do Microsoft Entra usando uma entidade de serviço ou uma conta de usuário do Microsoft Entra. Escolha um dos dois métodos.
Usar uma entidade de serviço com um tipo de concessão "credencial de cliente"
O serviço FHIR é protegido pelo Microsoft Entra ID. A autenticação padrão não pode ser desabilitada. Para acessar o serviço FHIR, primeiro você precisa obter um token de acesso do Microsoft Entra. Para obter mais informações, consulte Tokens de acesso da plataforma de identidade da Microsoft.
Criar uma nova solicitação POST
:
Insira o cabeçalho da solicitação:
https://login.microsoftonline.com/{{tenantid}}/oauth2/token
Selecione a guia Corpo e selecione x-www-form-urlencoded. Insira os seguintes valores na seção chave e valor:
- grant_type:
Client_Credentials
- client_id:
{{clientid}}
- client_secret:
{{clientsecret}}
- resource:
{{fhirurl}}
- grant_type:
Observação
Nos cenários em que o parâmetro de público-alvo do serviço FHIR não é mapeado para a URL do ponto de extremidade do serviço FHIR, o valor do parâmetro de recurso deve ser mapeado para o valor de público-alvo no painel Autenticação do serviço FHIR.
- Selecione a guia Teste e insira
pm.environment.set("bearerToken", pm.response.json().access_token);
na seção de texto para disponibilizar o valor para a coleção. Use o método pm.collectionVariables.set. Para obter mais informações sobre o método configurado e seu nível de escopo, confira Como usar variáveis em scripts. - Clique em Salvar para salvar as configurações.
- Selecione Enviar. Você deverá ver uma resposta com o token de acesso do Microsoft Entra, que é salvo na variável
bearerToken
automaticamente. Em seguida, você pode usá-lo em todas as solicitações de API do serviço FHIR.
Você pode examinar o token de acesso usando ferramentas online como, por exemplo, https://jwt.ms. Selecione a guia Declarações para ver descrições detalhadas de cada declaração no token.
Usar uma conta de usuário com o tipo de concessão "código de autorização"
Você pode obter o token de acesso do Microsoft Entra usando suas credenciais de conta do Entra e seguindo as etapas listadas.
Verifique se você é membro do locatário do Microsoft Entra com as permissões de acesso necessárias.
Certifique-se de que você configurou a URL de redirecionamento
https://oauth.pstmn.io/v1/callback
para a plataforma web no registro do aplicativo cliente.No registro do aplicativo cliente, em Permissões de API, adicione a permissão delegada User_Impersonation para APIs de Serviços de Saúde do Azure em APIs que minha organização usa.
No Postman, selecione a guia Autorização de uma coleção ou de uma chamada REST específica, selecione o Tipo como OAuth 2.0 e, na seção Configurar Novo Token, defina os seguintes valores:
URL de retorno de chamada:
https://oauth.pstmn.io/v1/callback
URL de autenticação:
https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize
URL do Token de Acesso:
https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token
ID do cliente: ID de registro do cliente do aplicativo
Segredo do Cliente: segredo do registro do cliente do aplicativo
Escopo:
{{fhirurl}}/.default
Autenticação do Cliente: enviar credenciais do cliente no corpo
Escolha Obter Novo Token de Acesso na parte inferior da página.
Você vê uma solicitação das suas credenciais de Usuário para entrar.
Você recebe o token. Escolha Usar Token.
Certifique-se de que o token esteja no Cabeçalho de Autorização da chamada REST.
Examine o token de acesso usando ferramentas online como, por exemplo, https://jwt.ms. Selecione a guia Declarações para ver descrições detalhadas de cada declaração no token.
Conectar-se ao servidor do FHIR
Abra o Postman e selecione o espaço de trabalho, a coleção e o ambiente que você quiser usar. Selecione o ícone +
para criar uma nova solicitação.
Para executar a verificação de integridade no serviço FHIR, insira {{fhirurl}}/health/check
na solicitação GET e, em seguida, escolha Enviar. Você deve conseguir ver a resposta do código Status of FHIR service - HTTP Status
como 200 e o OverallStatus como Íntegro na resposta, o que significa que sua verificação de integridade foi bem-sucedida.
Obter o recurso do FHIR
Após obter um token de acesso do Microsoft Entra, você poderá acessar os dados do FHIR. Em uma nova solicitação GET
, insira {{fhirurl}}/Patient
.
Selecione Token de Portador como tipo de autorização. Insira {{bearerToken}}
na seção Token. Selecione Enviar. Como resposta, você deverá ver uma lista de pacientes no seu recurso do FHIR.
Criar ou atualizar o recurso do FHIR
Após obter um token de acesso do Microsoft Entra, você poderá criar ou atualizar os dados do FHIR. Por exemplo, você pode criar um novo paciente ou atualizar um paciente existente.
Crie uma nova solicitação, altere o método para Post e, a seguir, insira o valor na seção de solicitação.
{{fhirurl}}/Patient
Selecione Token de Portador como o tipo de autorização. Insira {{bearerToken}}
na seção Token. Selecione a guia Corpo. Selecione a opção bruto e JSON como formato de texto do corpo. Copie e cole o texto no corpo.
{
"resourceType": "Patient",
"active": true,
"name": [
{
"use": "official",
"family": "Kirk",
"given": [
"James",
"Tiberious"
]
},
{
"use": "usual",
"given": [
"Jim"
]
}
],
"gender": "male",
"birthDate": "1960-12-25"
}
Selecione Enviar. Você deverá ver um novo paciente na resposta JSON.
Exportar dados do FHIR
Após obter um token de acesso do Microsoft Entra, você poderá exportar dados do FHIR para uma conta de armazenamento do Azure.
Criar uma nova solicitaçãoGET
: {{fhirurl}}/$export?_container=export
Selecione Token de Portador como tipo de autorização. Insira {{bearerToken}}
na seção Token. Selecione Cabeçalhos para adicionar dois novos cabeçalhos:
Aceitar:
application/fhir+json
Preferir:
respond-async
Selecione Enviar. Você deverá perceber uma resposta 202 Accepted
. Selecione a guia Cabeçalhos da resposta e anote o valor do Content-Location. Você poderá usar o valor para consultar o status do trabalho de exportação.
Próximas etapas
Coleção inicial de mostras de consultas do Postman
Observação
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.