DICOM Pub/Sub 알림 구성

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

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

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

DICOM 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 권한을 참조하세요.

알림 구성

DICOM 저장소의 DicomNotificationConfig 객체에서 Pub/Sub 알림 및 해당 동작을 구성할 수 있습니다. 각 DICOM 저장소에 여러 개의 DicomNotificationConfig 객체를 구성할 수 있습니다.

다음 표는 DicomNotificationConfig 객체의 필드를 설명합니다.

필드 설명 예
pubsubTopic DICOM 저장소에 연결할 Pub/Sub 주제 지정된 주제로 알림이 전송됩니다. projects/my-project/topics/my-topic

알림 형식 및 콘텐츠

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

{
  "message": {
    "attributes": {
      "action": "ACTION",
      "lastUpdatedTime": "RFC_1123_FORMAT_DATETIME",
      "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
      "studyInstanceUID": "STUDY_UID",
      "seriesInstanceUID": "SERIES_UID",
      "sopInstanceUID": "INSTANCE_UID",
      "versionId": "VERSION_ID",
      "modality": "MODALITY",
      "storageClass": "STORAGE_CLASS",
      "previousStorageClass": "PREVIOUS_STORAGE_CLASS"
    },
    "data": "BASE_64_ENCODED_DATA",
    "messageId": "MESSAGE_ID",
    "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
  }
}

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

다음 표에서는 attributes 객체의 각 필드를 설명합니다.

속성 설명 예
action DICOM 리소스에서 발생한 작업입니다. 가능한 값은 다음과 같습니다.
  • StoreInstances
  • ImportDicomData
  • SetBlobSettings
  • DeleteInstances
 StoreInstances
lastUpdatedTime DICOM 리소스가 수정된 가장 최근 시간의 타임스탬프입니다. 타임스탬프에는 RFC 1123 형식이 사용됩니다. Mon, 01 Jan 2020 00:00:00 UTC
storeName 작업이 발생한 DICOM 저장소의 전체 리소스 이름입니다. projects/my-project/locations/us/datasets/my-dataset/dicomStores/my-dicom-store
studyInstanceUID DICOM 연구 인스턴스 고유 식별자 (UID)입니다. 1.2.3.4.5.6
seriesInstanceUID DICOM 시리즈 인스턴스 고유 식별자 (UID)입니다. 1.2.3.4.5.6
sopInstanceUID DICOM SOP 인스턴스 고유 식별자 (UID)입니다. 1.2.3.4.5.6
versionId 작업이 발생한 DICOM 리소스의 최신 버전 ID입니다. MTY4MzA2MDQzOTI5NjIxMDAwMA
modality DICOM 리소스의 모달리티 태그입니다. 가능한 값은 다음과 같습니다(이에 국한되지 않음).
  • CT
  • MR
  • MG
 CT
storageClass DICOM 리소스의 스토리지 클래스입니다. 가능한 값은 다음과 같습니다.
  • STANDARD
  • NEARLINE
  • COLDLINE
  • ARCHIVE
 STANDARD
previousStorageClass DICOM 리소스의 이전 스토리지 클래스입니다. 가능한 값은 다음과 같습니다.
  • STANDARD
  • NEARLINE
  • COLDLINE
  • ARCHIVE
 NEARLINE

다음 표에서는 message 객체의 나머지 필드를 설명합니다.

필드 설명
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
messageId Pub/Sub 메시지의 식별자입니다.
publishTime Pub/Sub 서버가 메시지를 게시한 시간입니다.

알림 구성 및 보기

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

DICOM 저장소 구성

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

REST

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

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

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

JSON 요청 본문:

{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    }
  ]
}

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

curl

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

cat > request.json << 'EOF'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    }
  ]
}
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=notificationConfigs"

PowerShell

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

@'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC",
    }
  ]
}
'@  | 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=notificationConfigs" | Select-Object -Expand Content

API 탐색기

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

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

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

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 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 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 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 알림 보기

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

  1. DICOM 인스턴스를 저장하거나 가져오기를 수행합니다. 요청으로 인해 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

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

    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

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

    $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 응답이 표시됩니다.

    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 pubsub subscriptions pull \
    projects/PROJECT_ID/subscriptions/PUBSUB_SUBSCRIPTION_ID \
    --limit=10 \
    --auto-ack \
    --format=json

    Windows(PowerShell)

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

    Windows(cmd.exe)

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

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

    [
  {
    "ackId": "RFAGFixdRkhRNxkIaFEOT14jPzUgKEUaAggUBXx9cEFLdVhUcGhRDRlyfWB9bQ5GAgpGWixfURsHaE5tdR",
    "ackStatus": "SUCCESS",
    "message": {
      "attributes": {
        "action": "ImportDicomData",
        "lastUpdatedTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
        "storeName": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
        "studyInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857604",
        "seriesInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857605",
        "sopInstanceUID": "1.3.6.1.4.1.1129.5.111396399361969898205364400549799252857606",
        "versionId": "MTY4MzA2MDQzOTI5NjIxMDAwMA",
        "modality": "CT",
        "storageClass": "STANDARD",
      },
      "data": "cHJvamVjdHMvbXlwcm9qZWN0L2xvY2F0aW9ucy91cy1jZW50cmFsMS9kYXRhc2V0cy9teS1kYXRhc2V0L2RpY29tU3RvcmVzL215LWRpY29tLXN0b3JlL2RpY29tV2ViL3N0dWRpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjExMTM5NjM5OTM2MTk2OTg5ODIwNTM2NDQwMDU0OTc5OTI1Mjg1NzYwNC9zZXJpZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE5NTYyODIxMzY5NDMwMDQ5ODk0Njc2MDc2NzQ4MTI5MTI2MzUxMTcyNC9pbnN0YW5jZXMvMS4zLjYuMS40LjEuMTExMjkuNS41LjE1Mzc1MTAwOTgzNTEwNzYxNDY2NjgzNDU2MzI5NDY4NDMzOTc0NjQ4MA==",
      "messageId": "7586159156345265",
      "publishTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ"
    }
  }
]

notificationConfig에서 notificationConfigs로 마이그레이션

기존 DICOM 저장소 사용자의 경우 notificationConfig 필드를 사용하여 Pub/Sub 주제를 구성하는 경우 notificationConfigs 필드로 마이그레이션해야 합니다. 주요 차이점은 다음과 같습니다.

  1. dicomStore.notificationConfig는 구독자 한 명만 지원하는 반면 dicomStore.notificationConfigs는 여러 구독자를 지원합니다.

  2. dicomStore.notificationConfig는 지원 중단되고 DicomNotificationConfig로 대체되는 NotificationConfig를 사용합니다.

  3. dicomStore.notificationConfigs는 ImportDicomData, DeleteInstances 등 사용 가능한 모든 DICOM 작업에 대한 알림을 자동으로 전송하는 기능을 지원합니다. 따라서 NotificationConfig.sendForBulkImport이 더 이상 지원되지 않습니다.

  4. 특정 구독자의 수신할 메시지를 선택하거나 원치 않는 메시지를 필터링하려면 구독에서 메시지 필터링 기능을 사용하세요. 예를 들어 attributes.action != "ImportDicomData"를 사용하여 ImportDicomData 작업에서 전송된 모든 메시지를 필터링할 수 있습니다.

    REST

    dicomStores.patch 메서드를 사용합니다. notificationConfig를 사용하여 매장에 주제가 이미 설정되어 있다고 가정합니다.

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

    • PROJECT_ID: Google Cloud 프로젝트 ID
    • LOCATION: 데이터 세트 위치
    • DATASET_ID: DICOM 저장소의 상위 데이터 세트
    • DICOM_STORE_ID: DICOM 저장소 ID

    JSON 요청 본문:

    {
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_1",
    },
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_2",
    }
  ]
}

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

    curl

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

    cat > request.json << 'EOF'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_1",
    },
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_2",
    }
  ]
}
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,notificationConfigs"

    PowerShell

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

    @'
{
  "notificationConfigs": [
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_1",
    },
    {
      "pubsubTopic": "projects/PROJECT_ID/topics/PUBSUB_TOPIC_SAMPLE_2",
    }
  ]
}
'@  | 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,notificationConfigs" | Select-Object -Expand Content

    API 탐색기

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

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

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

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에 제출되지 않습니다.

다음 단계