BigQuery로 DICOM 메타데이터 스트리밍

이 페이지에서는 다음 중 하나가 발생할 때마다 DICOM 인스턴스 메타데이터를 BigQuery 테이블로 내보내도록 DICOM 저장소를 구성하는 방법을 설명합니다.

Store 트랜잭션을 사용하거나 Cloud Storage 버킷에서 DICOM 객체를 가져와서 DICOM 인스턴스를 저장하는 경우
삭제 요청을 사용하여 DICOM 인스턴스를 삭제하는 경우
DICOM 인스턴스의 스토리지 클래스를 변경하는 경우

DICOM 메타데이터를 BigQuery 테이블에 스트리밍하면 테이블이 DICOM 데이터와 동기화되어 최신 버전의 DICOM 저장소에서 복잡한 쿼리를 실행할 수 있습니다.

시작하기 전에

DICOM 저장소를 구성하기 전에 다음을 수행합니다.

BigQuery 권한 설정

DICOM 메타데이터를 BigQuery로 스트리밍하기 전에 Cloud Healthcare 서비스 에이전트 서비스 계정에 필요한 권한을 부여해야 합니다. 자세한 내용은 DICOM 저장소 BigQuery 권한을 참조하세요.

DICOM 메타데이터를 BigQuery로 내보내는 방법 알아보기

스트리밍을 구성하기 전에 DICOM 메타데이터를 BigQuery로 내보내는 방법을 확인합니다.

DICOM 저장소 구성

BigQuery로 스트리밍을 사용 설정하려면 DICOM 저장소에서 StreamConfig 객체를 구성합니다. StreamConfig 객체에서 BigQueryDestination 객체를 DICOM 인스턴스 메타데이터 대상으로서 정규화된 BigQuery 테이블 URI로 설정합니다.

최대 5개의 BigQuery 대상을 쉼표로 구분된 JSON 객체로 지정할 수 있습니다.

DICOM 저장소에서 DICOM 인스턴스를 삭제해도 해당 인스턴스의 메타데이터를 포함하는 BigQuery 행이 삭제되지 않습니다.

콘솔

BigQuery 스트리밍을 사용 설정하도록 DICOM 저장소를 업데이트하려면 다음 단계를 완료합니다.

Google Cloud 콘솔에서 데이터 세트 페이지로 이동합니다.
데이터 세트로 이동
수정할 DICOM 저장소가 포함된 데이터 세트를 선택합니다.
스트리밍 구성을 추가할 DICOM 저장소를 선택합니다.
Datastore 세부정보 페이지의 개요 탭에서 새 스트리밍 구성 추가를 클릭합니다.
새 스트리밍 구성 필드에서 찾아보기를 클릭합니다.
1. 테이블 선택 창에서 BigQuery 테이블을 선택합니다.
2. 선택을 클릭합니다.
완료를 클릭합니다.

REST

다음 샘플은 BigQuery 스트리밍을 사용 설정하도록 DICOM 저장소를 업데이트하는 방법을 보여줍니다. 이 샘플에서 DICOM 저장소 및 BigQuery 테이블은 동일한 프로젝트에 있습니다. DICOM 메타데이터를 다른 프로젝트로 내보내려면 DICOM 메타데이터를 다른 프로젝트로 내보내기를 참조하세요.

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

PROJECT_ID: Google Cloud 프로젝트의 ID
LOCATION: 데이터 세트 위치
DATASET_ID: DICOM 저장소의 상위 데이터 세트
DICOM_STORE_ID: DICOM 저장소 ID
BIGQUERY_DATASET_ID: 기존 BigQuery 데이터 세트의 이름
BIGQUERY_TABLE_ID: BigQuery 데이터 세트에 있는 테이블의 고유한 이름입니다. 이름 지정 요구사항은 테이블 이름 지정을 참조하세요. BigQuery 데이터 세트가 있어야 하지만 Cloud Healthcare API는 기존 테이블을 업데이트하거나 새 테이블을 만들 수 있습니다.

JSON 요청 본문:

{
  'streamConfigs': [{
     'bigqueryDestination': {
      'tableUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID'
     }
  }]
}

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

curl

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

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

cat > request.json << 'EOF'
{
  'streamConfigs': [{
     'bigqueryDestination': {
      'tableUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID'
     }
  }]
}
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=streamConfigs"

PowerShell

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

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

@'
{
  'streamConfigs': [{
     'bigqueryDestination': {
      'tableUri': 'bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID'
     }
  }]
}
'@  | 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=streamConfigs" | Select-Object -Expand Content

API 탐색기

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

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

응답

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/dicomStores/DICOM_STORE_ID",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "tableUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID.BIGQUERY_TABLE_ID"
      }
    }
  ]
}

삭제 메타데이터

이전 Cloud Healthcare API 버전에서 DICOM 인스턴스 메타데이터는 DICOM 인스턴스가 DICOM 저장소에 삽입되었을 때만 BigQuery로 내보내졌습니다. 삭제할 메타데이터를 작성할 때 Type 및 LastUpdated라는 두 개의 새 열이 DICOM 메타데이터가 포함된 생성 테이블에 추가되었습니다.

삭제 메타데이터를 도입하기 전에 있던 테이블의 메타데이터에는 이러한 열에 대한 NULL 값이 포함되어 있습니다. NULL은 가장 낮은 값이며 내림차순으로 정렬할 때 마지막으로 나타납니다.

생성된 BigQuery 뷰

DICOM 저장소에서 DICOM 인스턴스를 삽입하거나 삭제하면 구성된 BigQuery 테이블이 업데이트됩니다.

테이블의 뷰가 존재하지 않으면 뷰가 생성됩니다. 뷰가 존재하는 경우에는 뷰가 업데이트됩니다.

제한사항 및 추가 동작

일부 DICOM 태그가 내보낸 메타데이터에서 누락될 수 있습니다. 이 경우 누락된 태그는 대상 BigQuery 테이블의 DroppedTags.TagName이라는 별도의 열에 추가됩니다.

다음 이유 중 하나로 인해 태그가 누락됩니다.

DICOM 태그가 제외된 VR에 나열된 지원되지 않는 VR인 경우
DICOM 태그가 약 1MB를 초과하는 경우
대상 BigQuery 테이블의 열 수가 최대 열 수를 초과하는 경우. DICOM 메타데이터를 BigQuery 테이블로 내보낼 때 열 제한을 초과하면 기존 열과 일치하지 않는 DICOM 태그가 DroppedTags.Name 열에 추가됩니다. DroppedTags 열을 추가할 수 없으면 알림 없이 DICOM 태그가 삭제되고 경고 로그가 생성됩니다. 자세한 내용은 로그 보기를 위한 DICOM 스트리밍 요청 문제 해결을 참조하세요.

기존 테이블에 삭제 메타데이터 통합

생성된 뷰 동작은 삭제 메타데이터 기능이 도입되기 전에 추가된 메타데이터가 기본 테이블에 포함되어 있는지 여부에 따라 달라집니다.

삭제 메타데이터가 지원되기 전에 DICOM 메타데이터가 BigQuery 테이블에 포함되었다고 가정하면 다음 상황이 발생합니다.

DICOM 인스턴스를 DICOM 저장소에 삽입합니다.
DICOM 저장소에서 DICOM 인스턴스를 삭제합니다.
원래 DICOM 인스턴스의 태그를 수정하고 수정된 DICOM 인스턴스를 DICOM 저장소에 삽입합니다.

삭제 메타데이터가 지원되기 전 BigQuery 테이블에는 원래 메타데이터가 포함되었기 때문에 원래 DICOM 인스턴스와 수정된 버전은 동일한 연구, 시리즈, 인스턴스 고유 식별자(UID)를 갖습니다. 생성된 뷰에는 원본 DICOM 인스턴스 또는 가장 최근의 DICOM 인스턴스가 포함될 수 있습니다. LastUpdated 열이 없으면 뷰에서 최신 DICOM 인스턴스를 식별할 수 없습니다.

최신 DICOM 인스턴스 메타데이터를 쿼리하도록 보장하려면 다음 중 하나를 수행합니다.

뷰 대신 기본 테이블을 쿼리합니다. 수정된 DICOM 인스턴스에서 업데이트된 태그를 쿼리로 검색하는지 확인합니다.
DICOM 메타데이터가 포함된 기존 테이블을 삭제한 다음 DICOM 메타데이터를 BigQuery로 수동으로 내보내서 다시 만듭니다. 다시 생성된 테이블에는 LastUpdated 열이 포함됩니다.

이 옵션은 이전 스트리밍 메타데이터를 삭제하지만 테이블에 유효한 값이 있는 LastUpdated 열이 포함되도록 합니다.

DICOM 스트리밍 요청 문제 해결

DICOM에서 BigQuery 요청으로 메타데이터 내보내기 중에 오류가 발생하면 오류가 Cloud Logging에 로깅됩니다. 자세한 내용은 Cloud Logging에서 오류 로그 보기를 참조하세요.

Google Cloud 콘솔에서 스트리밍 DICOM 메타데이터 오류 로그를 필터링하려면 다음 단계를 완료하세요.

로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동

쿼리 필드에 다음 쿼리를 입력합니다.

logName="healthcare.googleapis.com%2Fdicom_stream"

쿼리 실행을 클릭합니다.

모든 오류 로그가 쿼리 결과 섹션에 표시됩니다.