다음을 통해 공유

Postman을 사용하여 FHIR 서비스에 액세스

  • 아티클

이 문서에서는 Postman을 사용하여 Azure Health Data Services의 FHIR® 서비스에 액세스하는 단계를 보여 줍니다.

필수 조건

  • Azure에 배포된 FHIR 서비스. 자세한 내용은 FHIR 서비스 배포를 참조하세요.
  • 로컬로 설치된 Postman. 자세한 내용은 Postman 시작을 참조하세요.
  • FHIR 서비스의 역할 할당에 대한 사용자 액세스 관리자 역할입니다.

설정 단계

Postman 애플리케이션에서 FHIR 서비스에 액세스하려면 다음 단계를 검토합니다.

  1. Microsoft Entra ID에 클라이언트 애플리케이션(앱 등록)을 등록합니다.

  2. FHIR 서비스에서 FHIR 데이터 기여자 역할을 할당합니다.

  3. Postman 설정 - 작업 영역, 컬렉션 및 환경 만들기

Microsoft Entra ID에 클라이언트 애플리케이션 등록

  1. Azure Portal에서 Microsoft Entra ID 타일을 선택합니다. 스크린샷은 Azure Portal의 Microsoft Entra ID 섹션을 보여줍니다.

  2. 관리 섹션에서 앱 등록 선택합니다. 스크린샷은 Microsoft Entra ID의 관리 섹션 아래에 있는 앱 등록 메뉴를 보여줍니다.

  3. + 새 등록을 선택합니다.

  4. 앱 등록의 이름을 입력합니다. 지원되는 계정 유형에서 이 조직 디렉터리의 계정만 선택합니다. 등록을 선택합니다.

새 앱 등록의 이름을 입력하는 양식을 보여 주는 스크린샷

애플리케이션 ID(클라이언트 ID)

새 애플리케이션을 등록한 후 개요 섹션에서 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID를 찾을 수 있습니다. Postman 환경을 구성할 때 필요하므로 나중에 사용할 수 있도록 이러한 값을 기록해 둡다. 스크린샷은 애플리케이션(클라이언트) ID 및 디렉터리(테넌트) ID를 보여 주는 등록된 애플리케이션의 개요 페이지를 보여줍니다.

인증 설정: 기밀 및 공개

  • 인증을 선택하여 설정을 검토합니다. 퍼블릭 클라이언트 흐름 허용의 기본값은 “아니요”입니다.

  • 이 기본값을 유지하는 경우 애플리케이션 등록은 기밀 클라이언트 애플리케이션이며 인증서 또는 비밀이 필요합니다. 기밀 클라이언트 애플리케이션에 대해

  • 고급 설정에서 “퍼블릭 클라이언트 흐름 허용” 옵션의 기본값을 “예”로 변경하는 경우 애플리케이션 등록은 공개 클라이언트 애플리케이션이며 인증서나 비밀이 필요하지 않습니다.

  • “예” 값은 비밀 정보를 저장하지 않으려는 모바일 앱 또는 JavaScript 앱에서 클라이언트 애플리케이션을 사용하려는 경우에 유용합니다.

  • 리디렉션 URL이 필요한 도구의 경우 플랫폼 추가를 선택하여 플랫폼을 구성합니다.

  • Postman의 경우에는 모바일 및 데스크톱 애플리케이션을 선택합니다. "https://www.getpostman.com/oauth2/callback"를 입력합니다. 사용자 지정 리디렉션 URI 섹션에 있습니다. 구성 단추를 선택하여 설정을 저장합니다.

인증서 및 비밀

  1. 인증서 및 비밀을 클릭합니다. +새 클라이언트 암호를 클릭합니다.

인증서 및 비밀 섹션에서 새 클라이언트 비밀을 만들기 위한 양식을 보여 주는 스크린샷

  1. 클라이언트 암호 추가에서 설명 필드에 비밀의 이름을 입력합니다. 지침은 비밀 만료를 위해 6개월을 설정하는 것입니다. 추가를 클릭합니다.

설명 필드에 비밀의 이름을 입력하는

  1. 비밀 ID가 아닌 비밀 값을 저장하는 것이 중요합니다.

새로 만든 클라이언트 암호의 값을 보여 주는 스크린샷

참고 항목

Postman, REST 클라이언트 등의 도구를 사용하여 FHIR 서비스에 대한 액세스 토큰을 가져오려고 할 때 client_credentials의 grant_type을 사용합니다.

FHIR 서비스에서 FHIR 데이터 기여자 역할 할당

이 섹션에서는 Azure Health Data Services의 FHIR 서비스에 등록된 애플리케이션에 FHIR® 데이터 기여자 역할을 할당하는 단계를 보여 줍니다.

  1. Azure Portal에서 FHIR 서비스로 이동합니다.

  2. 왼쪽 메뉴에서 IAM(액세스 제어) 블레이드를 선택합니다. + 추가를 클릭한 다음 역할 할당 추가를 선택합니다. 역할 할당을 추가하는 옵션을 사용할 수 없는 경우 Azure 관리자에게 이 단계를 수행할 수 있는 권한을 할당하도록 요청합니다. 역할 할당을 추가하는 옵션이 있는 Azure Portal의 FHIR 서비스 IAM(액세스 제어) 블레이드를 보여 주는 스크린샷

  3. 역할 탭 아래의 역할 할당 추가에서 목록에서 아래로 스크롤하고 FHIR 데이터 기여자를 선택합니다. 그런 후 Next 를 클릭합니다.

  4. [구성원] 탭에서 [구성원 선택]을 클릭합니다. 오른쪽의 선택 필드에 Postman 서비스 클라이언트 앱의 이름을 입력합니다. app을 선택합니다. Postman 서비스 클라이언트 앱을 선택하는 옵션이 있는 역할 할당 프로세스의

  5. 마찬가지로 선택에서 사용자 이름의 이름을 입력합니다. 앱 등록과 함께 목록에 추가되도록 사용자를 선택하고 선택을 클릭합니다. 그런 후 Next 를 클릭합니다. 사용자를 선택하는 옵션이 있는 역할 할당 프로세스의

  6. 검토 + 할당 탭에서 검토 + 할당을 클릭합니다. 역할 할당 프로세스를 완료하는 단추가 있는 마지막

Postman 설정 - 작업 영역, 컬렉션 및 환경을 만듭니다.

Postman을 처음 사용하는 경우 다음 단계에 따라 작업 영역, 컬렉션 및 환경을 만듭니다.

Postman은 사용자와 팀이 API, 컬렉션, 환경 및 기타 구성 요소를 공유할 수 있도록 하는 작업 영역 개념을 소개합니다. 기본 내 작업 영역 또는 팀 작업 영역을 사용하거나 사용자 또는 팀을 위한 새 작업 영역을 만들 수 있습니다. 작업 영역 만들기를 보여 주는 스크린샷.

다음으로, 관련된 모든 REST API 요청을 그룹화할 수 있는 새 컬렉션을 만듭니다. 작업 영역에서 컬렉션 만들기를 선택합니다. 기본 이름 새 컬렉션을 유지하거나 이름을 바꿀 수 있습니다. 변경 사항은 자동으로 저장됩니다. 새 컬렉션 만들기를 보여 주는 스크린샷.

Postman 컬렉션을 가져오고 내보낼 수도 있습니다. 자세한 내용은 Postman 설명서를 참조하세요.

컬렉션 가져오기 및 내보내기를 보여 주는 스크린샷.

환경 변수 만들기 또는 업데이트

요청에 전체 URL을 사용할 수 있지만 URL 및 기타 데이터를 변수에 저장하는 것이 좋습니다.

FHIR 서비스에 액세스하려면 다음 변수를 만들거나 업데이트해야 합니다.

변수 설명 참고
tenantid FHIR 서비스가 배포된 Azure 테넌트 애플리케이션 등록 개요에 위치
subid FHIR 서비스가 배포되는 Azure 구독 FHIR 서비스 개요에 위치
clientid 애플리케이션 클라이언트 등록 ID
clientsecret 애플리케이션 클라이언트 등록 비밀
fhirurl FHIR 서비스 전체 URL(예: https://xxx.azurehealthcareapis.com) FHIR 서비스 개요에 위치
bearerToken Microsoft Entra 액세스 토큰을 스크립트에 저장합니다. 비워 둠

참고 항목

클라이언트 애플리케이션 등록에서 리디렉션 URL https://www.getpostman.com/oauth2/callback을 구성했는지 확인합니다.

환경 변수를 보여 주는 스크린샷.

기능 문 보기

GET요청에 {{fhirurl}}/metadata를 입력한 다음 Send를 선택합니다. FHIR 서비스의 기능 문이 표시됩니다. 기능 요청 매개 변수를 보여 주는 스크린샷.

저장 요청을 보여 주는 스크린샷.

Microsoft Entra 액세스 토큰 가져오기

서비스 주체 또는 Microsoft Entra 사용자 계정을 선택하여 Microsoft Entra 액세스 토큰을 가져옵니다.

클라이언트 자격 증명 부여 형식으로 서비스 주체 사용

FHIR 서비스는 Microsoft Entra ID로 보호됩니다. 기본 인증을 사용하지 않도록 설정할 수 없습니다. FHIR 서비스에 액세스하려면 먼저 Microsoft Entra 액세스 토큰을 가져와야 합니다. 자세한 내용은 Microsoft ID 플랫폼 액세스 토큰을 참조하세요.

새 POST 요청 만들기:

  1. 요청 헤더를 입력합니다. https://login.microsoftonline.com/{{tenantid}}/oauth2/token

  2. 본문 탭을 선택하고 x-www-form-urlencoded를 선택합니다. 키 및 값 섹션에 다음 값을 입력합니다.

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

참고 항목

FHIR 서비스 대상 그룹 매개 변수가 FHIR 서비스 엔드포인트 URL에 매핑되지 않는 시나리오에서는 리소스 매개 변수 값이 FHIR 서비스 인증 창의 대상 그룹 값에 매핑되어야 합니다.

  1. 테스트 탭을 선택하고 텍스트 섹션에 pm.environment.set("bearerToken", pm.response.json().access_token);을(를) 입력합니다. 컬렉션에서 값을 사용할 수 있도록 하려면 pm.collectionVariables.set 메서드를 사용합니다. set 메서드 및 해당 범위 수준에 대한 자세한 내용은 스크립트에서 변수 사용을 참조하세요.
  2. 저장을 선택하여 설정을 저장합니다.
  3. 보내기를 선택합니다. 변수 bearerToken에 자동으로 저장되는 Microsoft Entra 액세스 토큰이 있는 응답이 표시됩니다. 그러면 모든 FHIR 서비스 API 요청에서 사용할 수 있습니다. 보내기 단추를 보여 주는 스크린샷

https://jwt.ms와 같은 온라인 도구를 사용하여 액세스 토큰을 검사할 수 있습니다. 토큰의 각 클레임에 대한 자세한 설명을 보려면 클레임 탭을 선택합니다.

액세스 토큰 클레임을 보여 주는 스크린샷.

인증 코드 부여 형식으로 사용자 계정을 사용합니다.

Microsoft Entra 계정 자격 증명을 사용하고 나열된 단계에 따라 Microsoft Entra 액세스 토큰을 가져올 수 있습니다.

  1. 필요한 액세스 권한을 가진 Microsoft Entra 테넌트의 멤버인지 확인합니다.

  2. 클라이언트 애플리케이션 등록에서 웹 플랫폼에 대한 리디렉션 URL https://oauth.pstmn.io/v1/callback을 구성했는지 확인합니다. 콜백 URL을 보여 주는 스크린샷.

  3. 클라이언트 애플리케이션 등록의 API 권한 아래에서 내 조직에서 사용하는 API의 Azure Healthcare APIS에 대한 User_Impersonation 위임된 권한을 추가합니다. 애플리케이션 등록 권한을 보여 주는 스크린샷.

애플리케이션 등록 권한 화면을 보여 주는 스크린샷.

  1. Postman에서 컬렉션 또는 특정 REST 호출의 권한 부여 탭을 선택하고, OAuth 2.0으로 형식을 선택하고, 새 토큰 구성 섹션에서 다음 값을 설정합니다.

    • 콜백 URL: https://oauth.pstmn.io/v1/callback

    • 인증 URL: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/authorize

    • 액세스 토큰 URL: https://login.microsoftonline.com/{{tenantid}}/oauth2/v2.0/token

    • 클라이언트 ID: 애플리케이션 클라이언트 등록 ID

    • 클라이언트 암호: 애플리케이션 클라이언트 등록 비밀

    • 범위: {{fhirurl}}/.default

    • 클라이언트 인증: 본문에 클라이언트 자격 증명 보내기

구성 화면을 보여 주는 스크린샷.

  1. 페이지 하단에서 새 액세스 토큰 가져오기를 선택합니다.

  2. 로그인에 대한 사용자 자격 증명을 제공합니다.

  3. 토큰을 받으면 토큰 사용을 선택합니다.

  4. 토큰이 REST 호출의 인증 헤더에 있는지 확인합니다.

https://jwt.ms와 같은 온라인 도구를 사용하여 액세스 토큰을 검사합니다. 토큰의 각 클레임에 대한 자세한 설명을 보려면 클레임 탭을 선택합니다.

FHIR 서버에 연결

Postman을 열고 사용하려는 작업 영역, 컬렉션 및 환경을 선택합니다. + 아이콘을 선택하여 새 요청을 만듭니다. 새 요청 만들기를 보여 주는 스크린샷.

FHIR 서비스에 대한 상태 검사를 수행하려면 GET 요청에 {{fhirurl}}/health/check를 입력한 다음 보내기를 선택합니다. 200이고 전체 상태가 정상인 Status of FHIR service - HTTP Status 코드 응답을 볼 수 있어야 합니다. 이는 상태 검사가 성공했음을 의미합니다.

FHIR 리소스 가져오기

Microsoft Entra 액세스 토큰을 가져오는 후 FHIR 데이터에 액세스할 수 있습니다. 새 GET 요청에 {{fhirurl}}/Patient를 입력합니다.

권한 부여 유형으로 전달자 토큰을 선택합니다. 토큰 섹션에 {{bearerToken}}을 입력합니다. 보내기를 선택합니다. 응답으로 FHIR 리소스에 환자 목록이 표시됩니다. 전달자 토큰 선택을 보여 주는 스크린샷.

FHIR 리소스 만들기 또는 업데이트

Microsoft Entra 액세스 토큰을 가져오는 후 FHIR 데이터를 만들거나 업데이트할 수 있습니다. 예를 들어 새 환자를 만들거나 기존 환자를 업데이트할 수 있습니다.

새 요청을 만들고 메서드를 Post로 변경한 다음 요청 섹션에 값을 입력합니다.

{{fhirurl}}/Patient

권한 부여 유형으로 전달자 토큰을 선택합니다. 토큰 섹션에 {{bearerToken}}을 입력합니다. 본문 탭을 선택합니다. 원시 옵션을 선택하고 JSON을 본문 텍스트 형식으로 선택합니다. 다음 텍스트를 복사하여 본문 섹션에 붙여넣습니다.

{
    "resourceType": "Patient",
    "active": true,
    "name": [
        {
            "use": "official",
            "family": "Kirk",
            "given": [
                "James",
                "Tiberious"
            ]
        },
        {
            "use": "usual",
            "given": [
                "Jim"
            ]
        }
    ],
    "gender": "male",
    "birthDate": "1960-12-25"
}

보내기를 선택합니다. JSON 응답에 새 환자가 표시됩니다. 새 환자를 만들기 위한 보내기 단추를 보여 주는 스크린샷.

FHIR 데이터 내보내기

Microsoft Entra 액세스 토큰을 가져오는 후 FHIR 데이터를 Azure Storage 계정으로 내보낼 수 있습니다.

내보내기 설정을 구성하고 Data Lake Storage Gen2 계정을 만들려면 내보내기 설정 구성을 참조하세요.

새 GET 요청 만들기: {{fhirurl}}/$export?_container=export

권한 부여 유형으로 전달자 토큰을 선택합니다. 토큰 섹션에 {{bearerToken}}을 입력합니다. 헤더를 선택하여 두 개의 새로운 헤더를 추가합니다.

  • Accept: application/fhir+json

  • Prefer: respond-async

보내기를 선택합니다. 202 Accepted 응답을 확인해야 합니다. 응답의 헤더 탭을 선택하고 Content-Location에 값을 기록해 둡니다. 이 값을 사용하여 내보내기 작업 상태를 쿼리할 수 있습니다. 선택 202 승인된 응답을 보여 주는 스크린샷.

다음 단계

Postman 샘플 쿼리의 시작 컬렉션

참고 항목

FHIR®은 HL7의 등록 상표이며, HL7의 사용 허가 하에 사용됩니다.