Partilhar via

Aceda ao serviço FHIR utilizando 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, consulte Implantar um serviço FHIR.
  • Carteiro instalado localmente. Para obter mais informações, consulte Introdução ao Postman.
  • Função de Administrador de Acesso de Usuário para atribuições de função no serviço FHIR.

Passos de configuração

Para aceder ao serviço FHIR a partir da aplicação Postman , reveja os passos:

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

  2. Atribua a função de Contribuidor de Dados FHIR no serviço FHIR.

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

Registar uma aplicação 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 Registos de aplicações na secção Gerir . A captura de tela mostra o menu Registros do aplicativo na seção Gerenciar do ID do Microsoft Entra.

  3. Selecione + Novos registos.

  4. Introduza um nome para o registo da aplicação. Em Tipos de conta suportados, selecione Contas apenas neste diretório da organização. selecione Registrar.

Captura de ecrã que mostra o formulário para introduzir um nome para o registo da nova aplicação.

ID do aplicativo (ID do cliente)

Depois de 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 versus pública

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

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

  • Se você alterar o valor padrão para "Sim" para a opção "Permitir fluxos de clientes públicos" na configuração avançada, o registro do aplicativo será um aplicativo cliente público e um certificado ou segredo não será necessário.

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

  • 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 Postman, selecione Aplicativos móveis e de desktop. Digite "https://www.getpostman.com/oauth2/callback" na seção URIs de redirecionamento personalizado. 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 & 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 expiração secreta. Clique em Adicionar.

Captura de tela que mostra o formulário

  1. É importante que guarde o valor secreto, não o ID secreto.

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

Nota

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

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

Esta seção mostra as etapas para atribuir a função de Colaborador de Dados FHIR a um aplicativo registrado para o serviço FHIR® nos Serviços de Dados de Saúde do Azure.

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

  2. No menu à esquerda, selecione a folha Controle de acesso (IAM). Clique em + Adicionar e, em seguida, 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 esta etapa. Captura de ecrã que mostra a folha de Controlo 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 Colaborador de Dados FHIR. Clique depois em Seguinte. Captura de ecrã que mostra a janela

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

  5. Da mesma forma, digite o nome do seu nome de usuário em Selecionar. Selecione seu usuário para que ele seja adicionado à lista junto com o registro do aplicativo e clique em Selecionar. Clique depois em Seguinte. Captura de tela que mostra a guia

  6. No separador Rever + atribuir, clique em Rever + atribuir. Captura de ecrã que mostra o separador final

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

Se você é novo no Postman, siga estas etapas para criar um espaço de trabalho, uma coleção e um ambiente.

O Postman apresenta 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 espaço de trabalho padrão Meu espaço de trabalho ou o espaço de trabalho de equipe 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 onde 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 é guardada 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 obter mais informações, consulte a documentação do Postman.

Captura de tela mostrando a importação e 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 estas variáveis:

Variável Descrição Notas
inquilino Locatário do Azure onde o serviço FHIR é implantado Localizado na visão geral do registro do aplicativo
Subid Assinatura do Azure onde o serviço FHIR é implantado Localizado na visão geral do serviço FHIR
ID do cliente ID de registro do cliente do aplicativo
ClientSecret Segredo de registro do cliente do aplicativo
Fhirurl O URL completo do serviço FHIR (por exemplo, https://xxx.azurehealthcareapis.com) Localizado na visão geral do serviço FHIR
portadorToken Armazena o token de acesso do Microsoft Entra no script Deixar em branco

Nota

Certifique-se de configurar a URL https://www.getpostman.com/oauth2/callback de redirecionamento no registro do aplicativo cliente.

Captura de tela mostrando ambientes variáveis.

Obtenha a declaração de capacidade

Introduza {{fhirurl}}/metadata o GET pedido e, em seguida, selecione Send. Você deve ver a declaração de capacidade do serviço FHIR. Captura de tela mostrando os parâmetros de solicitação de capacidade.

Captura de ecrã a mostrar um pedido de guarda.

Obter um 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 de credenciais 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, você precisa obter um token de acesso do Microsoft Entra primeiro. Para obter mais informações, consulte Tokens de acesso à plataforma de identidade da Microsoft.

Crie um novo POST pedido:

  1. Digite 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 de chave e valor:

    • grant_type: Client_Credentials
    • client_id: {{clientid}}
    • client_secret: {{clientsecret}}
    • Recurso: {{fhirurl}}

Nota

Em cenários em que o parâmetro FHIR service audience não é mapeado para a URL do ponto de extremidade do serviço FHIR, o valor do parâmetro resource deve ser mapeado para o valor audience 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 set e seu nível de escopo, consulte Usando variáveis em scripts.
  2. Selecione Guardar para guardar as definições.
  3. Selecione Enviar. Você 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 de serviço FHIR. Captura de ecrã a mostrar o botão enviar.

Você pode examinar o token de acesso usando ferramentas on-line como 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 de token de acesso.

Usar uma conta de usuário com o tipo de concessão de 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ê é um membro do locatário do Microsoft Entra com as permissões de acesso necessárias.

  2. Certifique-se de configurar a URL https://oauth.pstmn.io/v1/callback de redirecionamento para a plataforma Web no registro do aplicativo cliente. Captura de tela mostrando o 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 do Azure Healthcare de APIs que minha organização usa. Captura de tela mostrando as permissões de registro do aplicativo.

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

  1. Em Postman, selecione a guia Autorização de uma coleção ou de uma chamada REST específica, selecione Tipo como OAuth 2.0 e, na seção Configurar Novo Token , defina estes 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 de registro do cliente do aplicativo

    • Âmbito de aplicação: {{fhirurl}}/.default

    • Autenticação de cliente: Enviar credenciais de 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 credenciais de usuário para entrar.

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

  4. Verifique se o token está no cabeçalho de autorização da chamada REST.

Examine o token de acesso usando ferramentas on-line como https://jwt.ms. Selecione a guia Declarações para ver descrições detalhadas de cada declaração no token.

Conectar-se ao servidor FHIR

Abra o Postman, selecione o espaço de trabalho, a coleção e o ambiente que deseja usar. Selecione o + ícone para criar uma nova solicitação. Captura de tela mostrando a criação de uma nova solicitação.

Para executar uma verificação de integridade no serviço FHIR, insira {{fhirurl}}/health/check a solicitação GET e escolha Enviar. Você deve ser capaz de ver a resposta do código com 200 e OverallStatus como Saudável em resposta, o Status of FHIR service - HTTP Status que significa que sua verificação de integridade foi bem-sucedida.

Obter o recurso FHIR

Depois de obter um token de acesso do Microsoft Entra, você pode acessar os dados FHIR. Em uma nova GET solicitação, digite {{fhirurl}}/Patient.

Selecione Token ao portador como tipo de autorização. Entre {{bearerToken}} na seção Token . Selecione Enviar. Como resposta, você deve ver uma lista de pacientes em seu recurso FHIR. Captura de tela mostrando a seleção do token de portador.

Criar ou atualizar o recurso FHIR

Depois de obter um token de acesso do Microsoft Entra, você pode criar ou atualizar os dados 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 insira o valor na seção de solicitação.

{{fhirurl}}/Patient

Selecione Token ao portador como o tipo de autorização. Entre {{bearerToken}} na seção Token . Selecione a guia Corpo . Selecione a opção raw e JSON como formato de corpo de texto. Copie e cole o texto a seguir 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ê deve ver um novo paciente na resposta JSON. Captura de tela mostrando o botão enviar para criar um novo paciente.

Exportar dados do FHIR

Depois de obter um token de acesso do Microsoft Entra, você pode exportar dados FHIR para uma conta de armazenamento do Azure.

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

Crie um novo GET pedido: {{fhirurl}}/$export?_container=export

Selecione Token ao portador como tipo de autorização. Entre {{bearerToken}} na seção Token . Selecione Cabeçalhos para adicionar dois novos cabeçalhos:

  • Aceitar: application/fhir+json

  • Prefira: respond-async

Selecione Enviar. Você deve notar uma 202 Accepted resposta. Selecione a guia Cabeçalhos da resposta e anote o valor no Local do conteúdo. Você pode usar esse valor para consultar o status do trabalho de exportação. Captura de tela mostrando a seleção 202 respostas aceitas.

Próximos passos

Coleção inicial de consultas de amostra do Postman

Nota

FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.