Compartilhar via

Acessar o serviço FHIR usando o Postman

  • Artigo

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.
  • Postman instalado localmente. Para obter mais informações, confira Introdução ao Postman.
  • Administrador de acesso do usuário função para atribuições de função no serviço FHIR.

Etapas de configuração

Para acessar o serviço FHIR do aplicativo Postman, revise as etapas:

  1. Registre um aplicativo cliente (Registro de aplicativo) no Microsoft Entra ID.

  2. Atribuir a função Contribuidor de dados FHIR no serviço FHIR.

  3. Configurar o Postman - Criar espaço de trabalho, coleção e ambiente

Registrar um Aplicativo cliente no Microsoft Entra ID

  1. No portal do Azure, selecione o bloco ID do Microsoft Entra. A captura de tela mostra a seção Microsoft Entra ID do portal do Azure.

  2. Selecione Registros de aplicativo na seção Gerenciar. A captura de tela mostra o menu de Registros de aplicativo na seção Gerenciar do Microsoft Entra ID.

  3. Selecione + Novos registros.

  4. Insira um nome para o registro do aplicativo. Em Tipos de conta com suporte, selecione Contas somente neste diretório da organização. selecione Registrar.

Captura de tela que mostra o formulário para inserir um nome para o registro do novo aplicativo.

ID de aplicativo (ID do cliente)

Após registrar um novo aplicativo, você pode encontrar o ID do aplicativo (cliente) e o ID do diretório (locatário) na seção Visão geral. Anote esses valores para uso posterior, pois você precisará deles ao configurar seu ambiente Postman. A captura de tela mostra a página Visão geral do aplicativo registrado, mostrando o ID do aplicativo (cliente) e o ID do diretório (locatário).

Configuração de autenticação: confidencial vs. pública

  • Selecione Autenticação para revisar as configurações. O valor padrão para Permitir fluxos de cliente público é "Não".

  • Se você mantiver esse valor padrão, o registro do aplicativo será um aplicativo cliente confidencial e será necessário um certificado ou segredo. Captura de tela que mostra as configurações de autenticação onde

  • Se você alterar o valor padrão para "Sim" na opção "Permitir fluxos de cliente público' nas configurações avançadas, o registro do aplicativo se torna um aplicativo cliente público e um certificado ou segredo não é necessário.

  • O valor "Sim" é útil quando você deseja usar o aplicativo cliente em seu aplicativo móvel ou em um aplicativo JavaScript em que não deseja armazenar nenhum segredo.

  • Para ferramentas que exigem uma URL de redirecionamento, selecione Adicionar uma plataforma para configurar a plataforma. Captura de tela que mostra a seção

  • Para o Postman, selecione Aplicativos móveis e de área de trabalho. Digite "https://www.getpostman.com/oauth2/callback" na seção URIs de redirecionamento personalizados. Selecione o botão Configurar para salvar a configuração. Captura de tela que mostra a seção

Certificados e segredos

  1. Clique em Certificados e segredos. Clique em +Novo segredo do cliente.

Captura de tela que mostra o formulário para criar um novo segredo de cliente na seção Certificados e Segredos.

  1. Em Adicionar um segredo do cliente, insira um nome para o segredo no campo Descrição. A orientação é definir 6 meses para a expiração do segredo. Clique em Adicionar.

Captura de tela que mostra o formulário

  1. É importante que você salve o valor secreto, não o ID secreto.

Captura de tela que mostra o valor do segredo do cliente recém-criado.

Observação

Use grant_type de client_credentials ao tentar obter um token de acesso para o serviço FHIR usando ferramentas como Postman ou Cliente REST.

Atribuir a função de Colaborador de Dados FHIR no serviço FHIR

Essa seção mostra as etapas para atribuir a função FHIR Data Contributor a um aplicativo registrado para o serviço FHIR® no Serviços de Dados de Saúde do Azure.

  1. No portal do Azure, navegue até seu serviço FHIR.

  2. No menu à esquerda, selecione a lâmina Serviço de Controle de Acesso do Microsoft Azure AD (IAM). Clique em + Adicionar e selecione Adicionar atribuição de função. Se a opção para adicionar uma atribuição de função não estiver disponível, peça ao administrador do Azure para lhe atribuir permissão para executar essa etapa. Captura de tela que mostra a lâmina de Controle de Acesso (IAM) do serviço FHIR do portal do Azure com a opção de adicionar uma atribuição de função.

  3. Em Adicionar atribuição de função na guia Função, role para baixo na lista e selecione Contribuidor de dados FHIR. Em seguida, clique em Próximo. Captura de tela que mostra a janela

  4. Na aba Membros, clique em +Selecionar membros. Digite o nome do seu aplicativo cliente de serviço Postman no campo Selecionar à direita. Selecione o aplicativo. Captura de tela que mostra a aba

  5. Da mesma forma, digite o nome do seu nome de usuário no Selecionar. Selecione seu usuário para que ele seja adicionado à lista junto com o registro do aplicativo e clique em Selecionar. Em seguida, clique em Próximo. Captura de tela que mostra a aba

  6. Na aba Revisar + atribuir, clique em Revisar + atribuir. Captura de tela que mostra a aba final

Configurar o Postman - Criar espaço de trabalho, coleção e 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. Captura de tela mostrando a criação do espaço de trabalho.

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. Captura de tela mostrando a criação de uma nova coleção.

Você também pode importar e exportar coleções do Postman. Para saber mais, confira a Documentação do Postman.

Captura de tela mostrando a importação e a exportação de coleções.

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.

Captura de tela mostrando a variável de ambientes.

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. Captura de tela mostrando os parâmetros de solicitação de funcionalidade.

Captura de tela mostrando uma solicitação de salvamento.

Obter um token de acesso do Microsoft Entra

Obtenha um token de acesso do Microsoft Entra escolhendo uma entidade de serviço ou uma conta de usuário do Microsoft Entra.

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:

  1. Insira o cabeçalho da solicitação: https://login.microsoftonline.com/{{tenantid}}/oauth2/token

  2. 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}}

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.

  1. 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.
  2. Clique em Salvar para salvar as configurações.
  3. Selecione Enviar. Você deverá ver uma resposta com o token de acesso do Microsoft Entra, que é salvo automaticamente na variável bearerToken. Em seguida, você pode usá-lo em todas as solicitações de API do serviço FHIR. Captura de tela mostrando o botão Enviar.

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.

Captura de tela mostrando declarações do token de acesso.

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 Microsoft Entra e seguindo as etapas listadas.

  1. Verifique se você é membro do locatário do Microsoft Entra com as permissões de acesso necessárias.

  2. 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. Captura de tela mostrando a URL de retorno de chamada.

  3. 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. Captura de tela mostrando as permissões do registro do aplicativo.

Captura de tela mostrando a tela de permissões do registro do aplicativo.

  1. 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

Captura de tela mostrando a tela de configuração.

  1. Escolha Obter Novo Token de Acesso na parte inferior da página.

  2. Forneça as credenciais do usuário para entrar.

  3. Depois de receber o token, escolha Usar Token.

  4. 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. Captura de tela mostrando a criação de 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. Captura de tela mostrando a seleção do token de portador.

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 solicitação, altere o método para Post e 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 na seção do 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. Captura de tela mostrando o botão Enviar para criar um novo paciente.

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.

Para configurar as definições de exportação e criar uma conta do Data Lake Storage Gen2, consulte Configurar definições para exportação.

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 esse valor para consultar o status do trabalho de exportação. Captura de tela mostrando a resposta aceita 202 da seleçã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.