Pub/Sub를 사용하여 Cloud Healthcare API 데이터 저장소에서 임상 이벤트가 발생할 때 알림을 수신할 수 있습니다. 이러한 알림은 다음 상황을 알려줍니다.
- DICOM 인스턴스는
dicomStores.dicomWeb.studies.storeInstances를 사용하여 DICOM 저장소에 저장됩니다. 하지만 DICOM 리소스를 Cloud Storage에서 가져올 때 알림은 전송되지 않습니다. - FHIR 리소스가 FHIR 저장소에서 생성, 업데이트 또는 삭제된 경우. 하지만 FHIR 리소스를 Cloud Storage에서 가져올 때 알림이 전송되지 않습니다.
- HL7v2 메시지가 처음으로 HL7v2 저장소에서 수집되거나 생성된 경우. 중복 메시지는 알림을 트리거하지 않습니다.
이러한 이벤트 중 하나가 발생하면 Cloud Healthcare API는 주제라는 이름이 지정된 Pub/Sub 리소스에 메시지를 게시합니다. 그런 다음 이 주제를 구독하는 애플리케이션에서 메시지를 수신할 수 있습니다.
DICOM 및 HL7v2의 경우 이러한 메시지에 개인 정보가 포함되지 않습니다. 다음 항목만 포함됩니다.
- 생성된 메시지의 프로젝트
- 메시지 ID
- HL7v2 메시지의 HL7v2 메시지 유형
FHIR Pub/Sub 메시지에는 개인 정보가 포함될 수 있습니다. 자세한 내용은 FHIR 리소스 데이터가 포함된 FHIR 알림을 참조하세요.
Cloud Healthcare API에서 Pub/Sub 알림 사용에 대한 개요는 Pub/Sub 알림을 참조하세요.
기본 요건
이 기능을 사용하려면 다음 섹션을 완료하세요.
Pub/Sub 할당량 검토
Pub/Sub 알림을 구성하기 전에 Pub/Sub 할당량 및 한도를 숙지합니다. 할당량 확인 방법, 추가 할당량 요청 방법, 할당량 부족 시 발생하는 결과에 대한 자세한 내용은 할당량 작업을 참조하세요.
Pub/Sub API 사용 설정
Pub/Sub API를 사용 설정하려면 다음 버튼을 클릭합니다.
Pub/Sub 권한 구성
Cloud Healthcare API에서 Pub/Sub로 메시지를 게시하려면 프로젝트의 Cloud Healthcare 서비스 에이전트 서비스 계정에 pubsub.publisher 역할을 추가해야 합니다.
필요한 역할을 추가하는 단계는 DICOM, FHIR, HL7v2 저장소 Pub/Sub 권한을 참조하세요.
Pub/Sub 주제 만들기
알림을 수신할 각 데이터 저장소에 대해 Pub/Sub 주제를 구성해야 합니다. 개별 데이터 저장소에는 자체 Pub/Sub 주제가 있거나 여러 데이터 저장소가 동일한 주제를 공유할 수 있습니다. Google Cloud Console 또는 Google Cloud CLI를 사용하여 주제를 만들 수 있습니다.
주제를 만들거나 데이터 저장소 구성에서 주제를 참조할 때는 다음 형식의 정규화된 URI를 사용해야 합니다.
projects/PROJECT_ID/topics/TOPIC_NAME
여기서 PROJECT_ID는 Google Cloud 프로젝트 ID이고 TOPIC_NAME은 주제의 이름입니다.
주제를 만들려면 다음 단계를 완료합니다.
콘솔
Google Cloud 콘솔에서 Pub/Sub 주제 페이지로 이동합니다.
주제 만들기를 클릭합니다.
URI와 함께 주제 이름을 입력합니다.
projects/PROJECT_ID/topics/TOPIC_NAME여기서 PROJECT_ID는 Google Cloud 프로젝트 ID입니다.
만들기를 클릭합니다.
gcloud
주제를 만들려면 gcloud pubsub topics create 명령어를 실행합니다.
gcloud pubsub topics create projects/PROJECT_ID/topics/TOPIC_NAME
요청이 성공하면 명령어는 다음 출력을 반환합니다.
Created topic [projects/PROJECT_ID/topics/TOPIC_NAME].
Pub/Sub 구독 만들기
주제에 게시된 메시지를 받으려면 Pub/Sub 구독을 만들어야 합니다. 모든 Pub/Sub 주제에는 하나 이상의 Pub/Sub 구독이 있어야 합니다.
구독은 주제에 게시된 메시지를 수신하고 처리하는 구독자 애플리케이션과 주제를 연결합니다.
구독은 내보내기 모델이나 가져오기 모델을 이용하도록 구성할 수 있습니다.
구독을 만들려면 다음 단계를 완료하세요.
콘솔
Google Cloud 콘솔에서 Pub/Sub 주제 페이지로 이동합니다.
프로젝트 주제를 클릭합니다.
구독 만들기를 클릭합니다.
구독 이름을 입력합니다.
projects/PROJECT_ID/subscriptions/SUBSCRIPTION_NAME전송 유형을 가져오기로 설정합니다.
만들기를 클릭합니다.
gcloud
주제를 만들려면 gcloud pubsub subscriptions create 명령어를 실행합니다.
gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME
요청이 성공하면 명령어는 다음 출력을 반환합니다.
Created subscription [projects/PROJECT_ID/subscriptions/TOPIC_NAME].
DICOM 알림 보기
DicomStore 리소스에는 Pub/Sub 주제를 지정할 수 있는 notificationConfig 객체가 포함됩니다. 원하는 경우 notificationConfig 객체를 사용하면 일괄 가져오기 중에 Pub/Sub 알림 전송 여부를 지정할 수도 있습니다. 이 필드는 v1beta1 버전에서만 사용할 수 있습니다.
DICOM 저장소에 새 DICOM 인스턴스를 저장하면 Cloud Healthcare API가 메시지를 DICOM 저장소의 Pub/Sub 주제에 게시합니다.
저장된 DICOM 인스턴스에 대한 알림을 보려면 다음 단계를 완료합니다.
- DICOM 저장소를 만들거나 수정하여 Pub/Sub 주제로 구성합니다. 선택적으로 일괄 가져오기 중에 Pub/Sub 알림을 보낼지 여부를 나타냅니다(v1beta1 API에서만 이 기능을 사용할 수 있음).
- 프로젝트의 서비스 계정에 필요한
pubsub.publisher역할을 추가합니다. - DICOM 저장소에 인스턴스를 저장합니다. 이렇게 하면 Cloud Healthcare API가 메시지를 구성된 Pub/Sub 주제에 게시합니다.
gcloud pubsub subscriptions pull명령어를 실행하여 Pub/Sub 주제에 게시된 메시지를 확인합니다.gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
이 명령어는 저장된 DICOM 인스턴스에 대해 다음 출력을 반환합니다.
┌----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┐ | DATA | MESSAGE_ID | ATTRIBUTES | ├---------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|------------| | projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID | 123456789012345 | | └----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------┘
FHIR 알림 보기
FHIR Pub/Sub 알림을 구성할 때 다음 옵션을 사용할 수 있습니다.
FHIR 리소스 데이터가 없는 FHIR 알림(모든 API 버전)
Pub/Sub 알림에는 작업이 발생한 FHIR 리소스 유형과 일부 추가 정보가 포함됩니다.
NotificationConfig객체에서 구성됩니다.FHIR 리소스 데이터가 있는 FHIR 알림(v1alpha2 및 v1beta1만 해당)
Pub/Sub 알림에는 작업이 발생한 FHIR 리소스 유형, 작업 종류, 작업 발생 시간과 같은 정보가 포함됩니다. Pub/Sub 알림에서 FHIR 리소스의 콘텐츠를 표시할지 여부를 지정할 수도 있습니다.
FhirNotificationConfig객체에서 구성됩니다.
다음 테이블은 환자 FHIR 리소스를 만든 후 각 옵션의 Pub/Sub 메시지에 포함된 정보를 보여줍니다.
NotificationConfig(FHIR 리소스 데이터 제외) |
|---|
|
FhirNotificationConfig(FHIR 리소스 데이터 포함) |
|
FHIR 리소스 데이터가 없는 FHIR 알림
FhirStore 리소스에는 Pub/Sub 주제를 지정할 수 있는 NotificationConfig 객체가 포함됩니다.
FHIR 저장소에서 FHIR 리소스가 생성, 업데이트, 삭제되면 Cloud Healthcare API가 메시지를 FHIR 저장소의 Pub/Sub 주제에 게시합니다.
생성된 FHIR 리소스의 알림을 보려면 다음 단계를 완료하세요.
- FHIR 저장소를 만들거나 수정하고 Pub/Sub 주제로 구성합니다.
- 프로젝트의 서비스 계정에 필요한
pubsub.publisher역할을 추가합니다. - FHIR 저장소에서 FHIR 리소스를 만듭니다. 이렇게 하면 Cloud Healthcare API가 메시지를 구성된 Pub/Sub 주제에 게시합니다.
gcloud pubsub subscriptions pull명령어를 실행하여 Pub/Sub 주제에 게시된 메시지를 확인합니다.gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
이 명령어는 생성된 FHIR 리소스에 대한 다음 출력을 반환합니다.
┌----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┐ | DATA | MESSAGE_ID | ATTRIBUTES | ├----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------| | projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/resources/Patient/PATIENT_ID | 123456789012345 | action=CreateResource | | | | resourceType=Patient | └----------------------------------------------------------------------------------------------------------------|-----------------|-----------------------┘
FHIR 리소스 데이터가 포함된 FHIR 알림
Cloud Healthcare API의 v1beta1 버전에서 FhirStore 리소스에는 다음 정보를 지정할 수 있는 FhirNotificationConfig 객체가 포함되어 있습니다.
- FHIR 저장소에 연결할 Pub/Sub 주제
- 변경된 FHIR 리소스의 전체 콘텐츠를 Pub/Sub 주제로 전송할지 여부
FHIR 리소스의 전체 콘텐츠를 보내면 Pub/Sub 메시지에서 직접 FHIR 리소스에 대한 모든 정보를 가져올 수 있습니다. 이렇게 하면 Pub/Sub 메시지를 쿼리한 후 Cloud Healthcare API를 별도로 쿼리하여 FHIR 리소스에 대한 세부정보를 가져올 필요가 없습니다.
FHIR Pub/Sub 메시지의 attributes 필드에는 다음 정보가 포함됩니다.
- FHIR 리소스의 유형(
resourceType) - 메시지를 발생시킨 작업(
action) - 메시지의 페이로드 유형(
payloadType),nameOnly또는fullResource중 하나 - 작업이 발생한 FHIR 저장소의 전체 리소스 이름(
storeName) - RCF1123 형식을 사용하여 FHIR 리소스를 수정한 가장 최근의 타임스탬프(
lastUpdatedTime)
생성된 FHIR 리소스의 알림을 보고 FHIR 리소스의 전체 콘텐츠를 보려면 다음 단계를 완료하세요.
FHIR 저장소를 만들거나 수정하고
notificationConfigs객체로 구성합니다. 다음 샘플에서는 FHIR 저장소를 만듭니다.요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID
- LOCATION: 상위 데이터 세트의 위치
- DATASET_ID: FHIR 저장소의 상위 데이터 세트
- FHIR_STORE_ID: FHIR 저장소 ID
- PUBSUB_TOPIC_ID: Pub/Sub 주제 ID
JSON 요청 본문:
{ "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true } ], "version": "R4" }요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
- 요청 본문을
request.json파일에 저장합니다. 다음 명령어를 복사하고 터미널에서 실행하여 이 파일을 만듭니다.cat > request.json << 'EOF' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true } ], "version": "R4" } EOF - 터미널에서 다음 명령어를 실행합니다. 방금 만든
request.json파일을 참조합니다.curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/fhir+json" \
-d @request.json \
"https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/?fhirStoreId=FHIR_STORE_ID"
PowerShell
- 요청 본문을
request.json파일에 저장합니다. 다음 명령어를 복사하고 터미널에서 실행하여 이 파일을 만듭니다.@' { "notificationConfigs": [ { "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_ID", "sendFullResource": true } ], "version": "R4" } '@ | Out-File -FilePath request.json -Encoding utf8 - 터미널에서 다음 명령어를 실행합니다. 방금 만든
request.json파일을 참조합니다.$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/fhir+json" `
-InFile request.json `
-Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/?fhirStoreId=FHIR_STORE_ID" | Select-Object -Expand Content
다음과 비슷한 JSON 응답이 표시됩니다.
FHIR 저장소에서 FHIR 리소스를 만듭니다. 이렇게 하면 Cloud Healthcare API가 메시지를 구성된 Pub/Sub 주제에 게시합니다.
Pub/Sub 주제에 게시된 메시지를 확인합니다. 다음 메시지는 FHIR 저장소에 환자 리소스가 생성될 때 생성되었습니다.
REST 및 명령줄
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID
- PUBSUB_SUBSCRIPTION_ID: FHIR 저장소에 구성된 Pub/Sub 주제에 연결된 구독의 ID
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
다음 명령어를 실행합니다.
curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d "" \
"https://pubsub.googleapis.com/v1beta1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=1"PowerShell
다음 명령어를 실행합니다.
$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-Uri "https://pubsub.googleapis.com/v1beta1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=1" | Select-Object -Expand Content다음과 유사한 JSON 응답이 표시됩니다.
gcloud
아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID
- PUBSUB_SUBSCRIPTION_ID: FHIR 저장소에 구성된 Pub/Sub 주제에 연결된 구독의 ID
다음 명령어를 실행합니다.
Linux, macOS 또는 Cloud Shell
gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
Windows(PowerShell)
gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
Windows(cmd.exe)
gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
다음과 비슷한 응답이 표시됩니다.
┌────────────────────────────────────────────────────────┬──────────────────┬──────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────┬──────────────────┐ │ DATA │ MESSAGE_ID │ ORDERING_KEY │ ATTRIBUTES │ DELIVERY_ATTEMPT │ ├────────────────────────────────────────────────────────┼──────────────────┼──────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────────────────┤ │ { │ 4300088465623331 │ │ action=CreateResource │ │ │ "birthDate": "1970-01-01", │ │ │ lastUpdatedTime=LAST_UPDATED_TIME │ │ │ "gender": "female", │ │ │ payloadType=FullResource │ │ │ "id": "3fbfac80-6357-44ad-b886-80f92a64bf7b", │ │ │ resourceType=Patient │ │ │ "meta": { │ │ │ storeName=projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID │ │ │ "lastUpdated": "LAST_UPDATED", │ │ │ │ │ │ "versionId": "MTY0ODc1NTk3MDMzODU3MzAwMA" │ │ │ │ │ │ }, │ │ │ │ │ │ "name": [ │ │ │ │ │ │ { │ │ │ │ │ │ "family": "Smith", │ │ │ │ │ │ "given": [ │ │ │ │ │ │ "Darcy" │ │ │ │ │ │ ], │ │ │ │ │ │ "use": "official" │ │ │ │ │ │ } │ │ │ │ │ │ ], │ │ │ │ │ │ "resourceType": "Patient" │ │ │ │ │ │ } │ │ │ │ │ └────────────────────────────────────────────────────────┴──────────────────┴──────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────────┘
FHIR 리소스가 너무 크거나 트래픽이 높은 경우의 동작
다음 경우에는 sendFullResource가 true로 설정된 경우에도 attributes 필드에 리소스 이름(projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/FHIR_RESOURCE/FHIR_RESOURCE_ID 형식)만 포함될 수 있습니다.
- FHIR 리소스의 크기가 너무 큼
- Cloud Healthcare API 서버에 높은 트래픽 발생
Pub/Sub 알림 보기를 통해 응답에서 payloadType 필드를 확인합니다. payloadType이 nameOnly로 설정된 경우 attributes 필드가 FHIR 리소스 데이터를 완전히 채우지 않았으므로 Pub/Sub 메시지 대신 FHIR 저장소에서 FHIR 리소스의 콘텐츠를 수동으로 가져와야 합니다.
HL7v2 알림 보기
Hl7V2Store 리소스에는 Pub/Sub 주제 및 필터링 기준을 지정할 수 있는 notificationConfigs 배열이 포함됩니다.
HL7v2 메시지가 HL7v2 저장소에서 수집되거나 생성되면 Cloud Healthcare API는 HL7v2 메시지와 일치하는 필터가 있는 Pub/Sub 주제에 메시지를 게시합니다.
수집된 HL7v2 메시지의 알림을 보려면 다음 단계를 완료하세요.
- HL7v2 저장소를 만들거나 수정하고 Pub/Sub 주제로 구성합니다.
- 프로젝트의 서비스 계정에 필요한
pubsub.publisher역할을 추가합니다. - HL7v2 저장소에 HL7v2 메시지를 수집합니다. 이렇게 하면 Cloud Healthcare API가 메시지를 구성된 Pub/Sub 주제에 게시합니다.
Pub/Sub 주제에 게시된 메시지를 보려면
gcloud pubsub subscriptions pull명령어를 실행합니다.gcloud pubsub subscriptions pull --auto-ack projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION
명령어는 수집된 HL7v2 메시지에 대한 다음 출력을 반환합니다.
┌--------------------------------------------------------------------------------------------------------------------|-----------------|---------------┐ | DATA | MESSAGE_ID | ATTRIBUTES | ├--------------------------------------------------------------------------------------------------------------------|-----------------|---------------| | projects/PROJECT_ID/locations/us-central1/datasets/DATASET_ID/hl7V2Stores/HL7V2_STORE_ID/messages/HL7V2_MESSAGE_ID | 123456789012345 | msgType=TYPE | └--------------------------------------------------------------------------------------------------------------------|-----------------|---------------┘
Cloud Healthcare API 및 Pub/Sub 메시지 스토리지 정책
Cloud Healthcare API 데이터와 Pub/Sub 메시지의 관련 데이터가 동일한 리전에 있는지 확인하려면 Pub/Sub 메시지 스토리지 정책을 설정해야 합니다.
데이터가 동일한 리전에 유지되도록 FHIR 저장소에 구성된 Pub/Sub 주제에 메시지 스토리지 정책을 명시적으로 설정해야 합니다. 예를 들어 Cloud Healthcare API 데이터 세트 및 FHIR 저장소가 us-central1에 있는 경우 메시지 스토리지 정책에서 us-central1 리전만 허용해야 합니다.
메시지 스토리지 정책을 구성하려면 메시지 저장소 정책 구성을 참조하세요.
누락된 Pub/Sub 메시지 문제 해결
Pub/Sub에 알림을 게시할 수 없는 경우 Cloud Logging에 오류가 로깅됩니다. 자세한 내용은 Cloud Logging에서 오류 로그 보기를 참조하세요.
오류 생성 속도가 한도를 초과하면 이 한도를 초과하는 오류는 Cloud Logging에 제출되지 않습니다.
다음 단계
Pub/Sub 주제를 구성하는 방법 알아보기: