DICOM Pub/Sub 알림 구성

이 페이지에서는 Pub/Sub를 사용하여 DICOM 저장소에서 임상 이벤트에 대한 알림을 받는 방법을 설명합니다. 새 DICOM 인스턴스가 DICOM 저장소에 저장되거나 Cloud Storage에서 가져올 때 Pub/Sub 알림을 받을 수 있습니다.

다운스트림 처리 트리거 또는 새 데이터 분석과 같은 다양한 용도로 Pub/Sub 알림을 사용할 수 있습니다. 예를 들어 머신러닝 모델은 새 데이터를 학습에 사용할 수 있을 때 알림을 받고 통계를 생성하여 환자 치료를 개선할 수 있습니다.

다음 그림은 Pub/Sub 알림을 생성하고 게시하는 방법을 보여줍니다.

그림 1. DICOM 저장소에서 임상 이벤트에 대한 Pub/Sub 알림을 수신합니다.

그림 1은 다음 단계를 보여줍니다.

1. 호출자가 DICOM 인스턴스를 저장하거나 가져오도록 요청을 수행합니다.
2. DICOM 저장소는 요청을 수신하고 Pub/Sub 메시지를 생성하여 DICOM 저장소에 구성된 Pub/Sub 주제로 전송합니다.
3. Pub/Sub가 해당 주제에 연결된 구독으로 메시지를 전달합니다.
4. 구독자가 해당 구독으로부터 메시지를 수신합니다. 각 구독에는 동시 로드 향상을 위해 하나 이상의 구독자가 있을 수 있습니다.

시작하기 전에

1. 주제 만들기
2. pull 구독 만들기

Pub/Sub 게시자 권한 추가

Cloud Healthcare API에서 Pub/Sub로 메시지를 게시하려면 프로젝트의 Cloud Healthcare 서비스 에이전트 서비스 계정에 pubsub.publisher 역할을 추가해야 합니다. 자세한 내용은 DICOM, FHIR, HL7v2 저장소 Pub/Sub 권한을 참조하세요.

알림 형식 및 콘텐츠

Pub/Sub 알림에는 임상 이벤트에 대한 정보가 포함된 Message 객체가 포함됩니다. DICOM Pub/Sub 알림에는 attributes 필드가 포함되지 않습니다. Message 객체는 다음과 유사합니다.

{
  "message": {
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

data 필드의 값은 다음과 같이 base 64로 인코딩된 문자열인 식별자입니다. projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID/dicomWeb/studies/STUDY_UID/series/SERIES_UID/instances/INSTANCE_UID

각 Pub/Sub 메시지에 포함된 필드에 대한 자세한 내용은 ReceivedMessage 및 PubsubMessage를 참조하세요.

알림 구성 및 보기

이 섹션에서는 DICOM 저장소에서 Pub/Sub 알림을 사용 설정하고, 알림을 게시하기 위해 DICOM 인스턴스를 저장하거나 가져오고, 알림을 보는 방법을 설명합니다.

DICOM 저장소 구성

이 태스크에 필요한 권한

이 태스크를 수행하려면 다음 권한 또는 다음 Identity and Access Management(IAM) 역할을 부여 받아야 합니다.

권한

• healthcare.dicomStores.update

역할

• Healthcare DICOM 저장소 관리자(roles/healthcare.dicomStoreAdmin)

관리자에게 이러한 Identity and Access Management 역할을 부여해 달라고 요청할 수 있습니다. 역할 부여에 대한 안내는 액세스 관리 또는 Cloud Healthcare API 리소스 액세스 제어를 참조하세요. 커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

참고: 이 가이드에서 Google Cloud 프로젝트를 만들었으면 프로젝트 생성자에게 해당 권한이 있는 소유자(roles/owner) IAM 역할이 자동으로 부여됩니다. 추가 IAM 역할을 부여할 필요가 없습니다.

다음 샘플은 새 DICOM 인스턴스를 저장하거나 Cloud Storage에서 가져올 때 DICOM 저장소에서 Pub/Sub 알림을 사용 설정하는 방법을 보여줍니다.

REST

projects.locations.datasets.dicomStores.patch 메서드를 사용합니다.

NotificationConfig.sendForBulkImport 값이 true이므로 Cloud Storage에서 데이터를 가져올 때 알림이 전송됩니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트의 ID
• LOCATION: 데이터 세트 위치
• DATASET_ID: DICOM 저장소의 상위 데이터 세트
• DICOM_STORE_ID: DICOM 저장소 ID
• PUBSUB_TOPIC: 데이터 스토어에서 이벤트가 발생할 때 메시지가 게시되는 Pub/Sub 주제

JSON 요청 본문:

{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

cat > request.json << 'EOF'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}
EOF

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

@'
{
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

그런 후 다음 명령어를 실행하여 REST 요청을 전송합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID?updateMask=notificationConfig" | Select-Object -Expand Content

API 탐색기

요청 본문을 복사하고 메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 요청 본문을 이 도구에 붙여넣고 다른 필수 필드를 입력한 후 실행을 클릭합니다.

다음과 비슷한 응답이 표시됩니다.

DicomStore 리소스에서 필드를 구성한 경우 응답에도 표시됩니다.

응답

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
  "notificationConfig": {
    "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    "sendForBulkImport": "true"
  },
}

gcloud

gcloud healthcare dicom-stores update 명령어를 실행합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: Google Cloud 프로젝트의 ID
• LOCATION: 데이터 세트 위치
• DATASET_ID: DICOM 저장소의 상위 데이터 세트
• DICOM_STORE_ID: DICOM 저장소 ID
• PUBSUB_TOPIC: 데이터 스토어에서 이벤트가 발생할 때 메시지가 게시되는 Pub/Sub 주제

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud healthcare dicom-stores update DICOM_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC \
  --send-for-bulk-import

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud healthcare dicom-stores update DICOM_STORE_ID `
  --dataset=DATASET_ID `
  --location=LOCATION `
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC `
  --send-for-bulk-import

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud healthcare dicom-stores update DICOM_STORE_ID ^
  --dataset=DATASET_ID ^
  --location=LOCATION ^
  --pubsub-topic=projects/PROJECT_ID/topics/PUBSUB_TOPIC ^
  --send-for-bulk-import

다음과 비슷한 응답이 표시됩니다.

응답

Updated dicomStore [DICOM_STORE_ID].
...
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID
notificationConfig:
  pubsubTopic: projects/PROJECT_ID/topics/PUBSUB_TOPIC
  sendForBulkImport: true

DICOM 인스턴스 저장 또는 가져오기 및 Pub/Sub 알림 보기

이 태스크에 필요한 권한

이 태스크를 수행하려면 다음 권한 또는 다음 Identity and Access Management(IAM) 역할을 부여 받아야 합니다.

권한

• 요청된 DICOM 저장소에 DICOM 인스턴스를 저장하기 위한 healthcare.dicomStores.dicomWebWrite
• 요청된 DICOM 저장소로 DICOM 인스턴스를 가져오기 위한 healthcare.dicomStores.import

역할

• Healthcare DICOM 편집자(roles/healthcare.dicomEditor)

관리자에게 이러한 Identity and Access Management 역할을 부여해 달라고 요청할 수 있습니다. 역할 부여에 대한 안내는 액세스 관리 또는 Cloud Healthcare API 리소스 액세스 제어를 참조하세요. 커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

참고: 이 가이드에서 Google Cloud 프로젝트를 만들었으면 프로젝트 생성자에게 해당 권한이 있는 소유자(roles/owner) IAM 역할이 자동으로 부여됩니다. 추가 IAM 역할을 부여할 필요가 없습니다.

DICOM 인스턴스를 저장하거나 가져오고 생성된 Pub/Sub 메시지를 가져오려면 다음 단계를 수행합니다.

1. DICOM 인스턴스를 저장하거나 import를 수행합니다. 요청으로 인해 Cloud Healthcare API가 메시지를 구성된 Pub/Sub 주제에 게시합니다.

2. 메시지를 가져옵니다. 단일 요청으로 여러 DICOM 인스턴스를 가져올 경우 각 DICOM 인스턴스에 대해 메시지가 생성됩니다.

   Pub/Sub 메시지를 가져오는 데 필요한 Identity and Access Management 권한을 보려면 Pub/Sub 액세스 제어를 참조하세요.

   REST

   projects.subscriptions.pull 메서드를 사용합니다. 다음 샘플은 ?maxMessages=10 쿼리 매개변수를 사용하여 요청에 반환할 최대 메시지 수를 지정합니다. 이 값을 사용 사례에 맞게 조정합니다.

   요청 데이터를 사용하기 전에 다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 ID
   • PUBSUB_SUBSCRIPTION_ID: DICOM 저장소에 구성된 Pub/Sub 주제에 연결된 구독 ID

   요청을 보내려면 다음 옵션 중 하나를 선택합니다.

   curl

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   다음 명령어를 실행합니다.

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d "" \
        "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10"

   PowerShell

   참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

   다음 명령어를 실행합니다.

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -Uri "https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID:pull?maxMessages=10" | Select-Object -Expand Content

   API 탐색기

   메서드 참조 페이지를 엽니다. 페이지 오른쪽에 API 탐색기 패널이 열립니다. 이 도구를 사용하여 요청을 보낼 수 있습니다. 모든 필수 필드를 입력하고 실행을 클릭합니다.

   다음과 비슷한 JSON 응답이 표시됩니다.

   응답

   {
     "receivedMessages": [
       {
         "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
         "ackStatus": "SUCCESS",
         "message": {
           "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
           "messageId": "7586159156345265",
           "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
         }
       }
     ]
   }
   

   gcloud

   gcloud pubsub subscriptions pull 명령어를 실행합니다.

   이 샘플은 다음과 같은 Google Cloud CLI 플래그를 사용합니다.

   • --limit=10: 최대 10개의 메시지를 반환합니다. 이 값을 사용 사례에 맞게 조정합니다.
   • --format=json: 출력을 JSON으로 렌더링합니다.
   • --auto-ack: 가져온 모든 메시지를 자동으로 확인합니다.

   아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

   • PROJECT_ID: Google Cloud 프로젝트의 ID
   • PUBSUB_SUBSCRIPTION_ID: DICOM 저장소에 구성된 Pub/Sub 주제에 연결된 구독 ID

   다음 명령어를 실행합니다.

   Linux, macOS 또는 Cloud Shell

   참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

   gcloud pubsub subscriptions pull \
       projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \
       --limit=10 \
       --auto-ack \
       --format=json

   Windows(PowerShell)

   참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

   gcloud pubsub subscriptions pull `
       projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID `
       --limit=10 `
       --auto-ack `
       --format=json

   Windows(cmd.exe)

   참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

   gcloud pubsub subscriptions pull ^
       projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID ^
       --limit=10 ^
       --auto-ack ^
       --format=json

   다음과 비슷한 응답이 표시됩니다.

   [
     {
       "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
       "ackStatus": "SUCCESS",
       "message": {
         "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
         "messageId": "7586159156345265",
         "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
       }
     }
   ]
   

Cloud Healthcare API 및 Pub/Sub 메시지 스토리지 정책

Cloud Healthcare API 데이터와 Pub/Sub 메시지의 관련 데이터가 동일한 리전에 있는지 확인하려면 Pub/Sub 메시지 스토리지 정책을 설정해야 합니다.

데이터가 동일한 리전에 유지되도록 하려면 데이터 스토어에 구성된 Pub/Sub 주제에 메시지 스토리지 정책을 명시적으로 설정해야 합니다. 예를 들어 Cloud Healthcare API 데이터 세트 및 FHIR 저장소가 us-central1에 있으면 메시지 스토리지 정책에서 us-central1 리전만 허용해야 합니다.

메시지 스토리지 정책을 구성하려면 메시지 저장소 정책 구성을 참조하세요.

누락된 Pub/Sub 메시지 문제 해결

Pub/Sub에 알림을 게시할 수 없는 경우 Cloud Logging에 오류가 로깅됩니다. 자세한 내용은 Cloud Logging에서 오류 로그 보기를 참조하세요.

오류 생성 속도가 한도를 초과하면 한도를 초과한 오류는 Cloud Logging에 제출되지 않습니다.

다음 단계

• 흐름 제어로 일시적인 급증 처리
• 메시지 처리 실패
• 메시지 재생 및 삭제
• Pub/Sub의 아키텍처 개요