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 주제를 구성하는 방법 알아보기: