PITR(point-in-time recovery)로 FHIR 리소스 복구

이 페이지에서는 PITR(point-in-time recovery)을 사용하여 FHIR 저장소의 FHIR 리소스를 지난 21일 이내의 상태로 복구하는 방법을 설명합니다. PITR을 사용하면 FHIR 리소스를 실수로 삭제한 경우와 같은 원치 않는 변경사항을 복구할 수 있습니다.

시작하기 전에

PITR 요청은 고급 작업 요청으로 분류되고 그에 따라 요금이 청구됩니다. PITR을 사용하기 전에 고급 작업 요청의 가격 책정을 검토하세요.

PITR 및 FHIR 리소스 버전 기록

PITR은 FHIR 리소스 버전 기록에 의존하지 않습니다. FHIR 저장소의 disableResourceVersioning 필드가 true이거나 FHIR 리소스의 이전 버전이 삭제된 경우에도 PITR을 사용할 수 있습니다.

복구 워크플로

프로덕션 복구가 예상대로 실행되도록 하려면 먼저 테스트 실행을 수행합니다. 테스트 실행은 복구할 FHIR 리소스의 ID 및 유형이 포함된 하나 이상의 파일을 출력합니다. 출력 파일이 정확한지 확인한 후에 프로덕션에서 복구를 다시 실행하세요.

특정 리소스를 복구하거나 필터링 기준에 따라 리소스를 복구하려면 필터를 지정합니다.

테스트 실행

프로덕션에서 FHIR 리소스를 복구하기 전에 테스트 실행을 수행합니다.

다음 샘플은 fhirStores.rollback 메서드를 사용하여 테스트 실행을 수행하는 방법을 보여줍니다.

REST

  1. FHIR 리소스를 복구합니다.

    테스트 실행을 수행하려면 force 필드가 false인지 확인합니다.

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

    • PROJECT_ID: Google Cloud 프로젝트의 ID
    • LOCATION: 데이터 세트 위치
    • DATASET_ID: FHIR 저장소의 상위 데이터 세트
    • FHIR_STORE_ID: FHIR 저장소 ID
    • RECOVERY_TIMESTAMP: 지난 21일 이내의 복구 지점. RFC 3339 형식을 사용합니다. 시간을 초 단위로 지정하고 시간대를 포함합니다(예: 2015-02-07T13:28:17.239+02:00 또는 2017-01-01T00:00:00Z).
    • CLOUD_STORAGE_BUCKET: 출력 파일이 기록되는 Cloud Storage 폴더 또는 버킷의 정규화된 URI

    JSON 요청 본문:

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}

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

    curl

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

    cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
EOF

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

    curl -X POST \
         -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/fhirStores/FHIR_STORE_ID:rollback"

    PowerShell

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

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "false"
}
'@  | Out-File -FilePath request.json -Encoding utf8

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

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

    Invoke-WebRequest `
        -Method POST `
        -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/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    API 탐색기

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

    출력은 다음과 같습니다. 응답에는 장기 실행 작업(LRO)의 식별자가 포함됩니다. 장기 실행 작업은 메서드 호출을 완료하는 데 추가 시간이 걸릴 수 있는 경우에 반환됩니다. OPERATION_ID의 값을 확인합니다. 다음 단계에서 이 값이 필요합니다.

  2. projects.locations.datasets.operations.get 메서드를 사용하여 장기 실행 작업의 상태를 가져옵니다.

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

    • PROJECT_ID: Google Cloud 프로젝트의 ID
    • DATASET_ID: 데이터 세트 ID
    • LOCATION: 데이터 세트 위치
    • OPERATION_ID: 장기 실행 작업에서 반환된 ID

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

    curl

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

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

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

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

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    API 탐색기

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

    출력은 다음과 같습니다. 응답에 "done": true가 포함되었으면 장기 실행 작업이 완료된 것입니다.

테스트 실행 출력 파일 보기

각 테스트 실행은 복구할 FHIR 리소스의 ID 및 유형이 포함된 하나 이상의 파일을 출력합니다. 대상 Cloud Storage 버킷의 rollback_resources 폴더에 있는 하위 폴더에 파일이 생성됩니다. 하위 폴더 이름은 fhirStores.rollback 응답에서 반환되는 LRO ID입니다. 파일을 확인하고 복구가 예상대로 작동하는지 확인하려면 객체 메타데이터 보기를 참조하세요.

파일 수는 복구된 FHIR 리소스 수에 비례합니다.

파일 이름은 trial-NUMBER-of-TOTAL_NUMBER.txt 형식을 사용합니다. 여기서 NUMBER는 파일 번호이고 TOTAL_NUMBER는 총 파일 수입니다.

테스트 실행 출력 파일 스키마

테스트 실행 복구의 출력 파일에 사용되는 스키마는 다음 표와 같습니다.

RESOURCE_TYPE RESOURCE_ID TIMESTAMP
FHIR 리소스 유형 FHIR 리소스 ID FHIR 저장소에서 FHIR 리소스가 생성되었거나 업데이트된 시간

프로덕션에서 복구

프로덕션에서 복구하기 전에 테스트 실행을 수행하고 시험 이전 출력 파일을 검사하여 프로덕션 복구가 예상대로 실행되는지 확인합니다.

다음 샘플은 fhirStores.rollback 메서드를 사용하여 프로덕션에서 FHIR 리소스를 복원하는 방법을 보여줍니다.

REST

  1. FHIR 리소스를 복구합니다.

    force 필드가 true인지 확인합니다.

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

    • PROJECT_ID: Google Cloud 프로젝트의 ID
    • LOCATION: 데이터 세트 위치
    • DATASET_ID: FHIR 저장소의 상위 데이터 세트
    • FHIR_STORE_ID: FHIR 저장소 ID
    • RECOVERY_TIMESTAMP: 지난 21일 이내의 복구 지점. RFC 3339 형식을 사용합니다. 시간을 초 단위로 지정하고 시간대를 포함합니다(예: 2015-02-07T13:28:17.239+02:00 또는 2017-01-01T00:00:00Z).
    • CLOUD_STORAGE_BUCKET: 출력 파일이 기록되는 Cloud Storage 폴더 또는 버킷의 정규화된 URI

    JSON 요청 본문:

    {
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}

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

    curl

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

    cat > request.json << 'EOF'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
EOF

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

    curl -X POST \
         -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/fhirStores/FHIR_STORE_ID:rollback"

    PowerShell

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

    @'
{
  "rollbackTime": "RECOVERY_TIMESTAMP",
  "resultGcsBucket": "gs://CLOUD_STORAGE_BUCKET",
  "force": "true"
}
'@  | Out-File -FilePath request.json -Encoding utf8

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

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

    Invoke-WebRequest `
        -Method POST `
        -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/fhirStores/FHIR_STORE_ID:rollback" | Select-Object -Expand Content

    API 탐색기

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

    출력은 다음과 같습니다. 응답에는 장기 실행 작업(LRO)의 식별자가 포함됩니다. 장기 실행 작업은 메서드 호출을 완료하는 데 추가 시간이 걸릴 수 있는 경우에 반환됩니다. OPERATION_ID의 값을 확인합니다. 다음 단계에서 이 값이 필요합니다.

  2. projects.locations.datasets.operations.get 메서드를 사용하여 장기 실행 작업의 상태를 가져옵니다.

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

    • PROJECT_ID: Google Cloud 프로젝트의 ID
    • DATASET_ID: 데이터 세트 ID
    • LOCATION: 데이터 세트 위치
    • OPERATION_ID: 장기 실행 작업에서 반환된 ID

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

    curl

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

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"

    PowerShell

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

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

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" | Select-Object -Expand Content

    API 탐색기

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

    출력은 다음과 같습니다. 응답에 "done": true가 포함되었으면 장기 실행 작업이 완료된 것입니다.

프로덕션 복구 출력 파일 보기

프로덕션 복구는 다음 파일을 출력합니다. 대상 Cloud Storage 버킷의 rollback_resources 폴더에 있는 하위 폴더에 파일이 생성됩니다. 하위 폴더 이름은 fhirStores.rollback 응답에서 반환되는 LRO ID입니다. 파일을 보려면 객체 메타데이터 보기를 참조하세요.

  • success-NUMBER-of-TOTAL_NUMBER.txt: 성공적으로 복구된 FHIR 리소스를 포함합니다.
  • fail-NUMBER-of-TOTAL_NUMBER.txt: 복구에 실패한 FHIR 리소스를 포함합니다. 실패가 없더라도 빈 파일이 생성됩니다.

파일 이름에서 NUMBER는 파일 번호이고 TOTAL_NUMBER는 총 파일 수입니다.

프로덕션 출력 파일 스키마

프로덕션 복구의 성공 및 실패 파일은 다음 스키마를 사용합니다. 오류 파일에는 ERROR_MESSAGE 열이 추가로 포함됩니다.

RESOURCE_TYPE RESOURCE_ID ROLLBACK_VERSION_ID NEW_VERSION_ID ERROR_MESSAGE(오류 파일만 해당)
FHIR 리소스 유형 FHIR 리소스 ID 복구가 시작된 시점에 리소스의 현재 버전 ID 복구 후 리소스의 현재 버전 ID. disableResourceVersioning이 true이거나 리소스를 복구하면 리소스가 삭제되는 경우 ROLLBACK_VERSION_ID 및 NEW_VERSION_ID는 비어 있습니다. 오류 파일만 해당. FHIR 리소스를 복구해야 하는 이유를 설명합니다.

필터를 사용하여 특정 FHIR 리소스 복구

다음 섹션에서는 필터를 사용하여 필터 기준에 따라 FHIR 리소스를 복구하는 방법을 설명합니다. fhirStores.rollback 요청을 보낼 때 RollbackFhirResourceFilteringFields 객체에 필터를 지정합니다.

다음과 같은 여러 사용 사례에서 필터를 결합하거나 개별적으로 사용할 수 있습니다.

  • 특정 FHIR 리소스를 실수로 삭제한 후 다른 리소스를 변경하지 않고 복구하기
  • FHIR 저장소를 특정 가져오기 작업에서 특정 FHIR 리소스를 가져오기 전의 상태로 복원하기

필터 파일 사용

기본적으로 PITR은 FHIR 저장소의 모든 FHIR 리소스를 복구합니다. 특정 FHIR 리소스를 복구하려면 파일에 리소스 유형과 리소스 ID를 지정한 후 Cloud Storage에 파일을 업로드합니다. inputGcsObject 필드에 파일 위치를 지정합니다.

Cloud Storage에서 필터 파일을 읽으려면 Cloud Healthcare 서비스 에이전트 서비스 계정에 권한을 부여해야 합니다. 자세한 내용은 Cloud Storage에서 필터 파일 읽기를 참조하세요.

필터 파일의 확장자에는 제한이 없습니다. FHIR 리소스를 한 줄에 하나씩 포함하여 다음 스키마를 사용해야 합니다.

FHIR_RESOURCE_TYPE/FHIR_RESOURCE_ID

예를 들어 ID가 8f25b0ac인 환자 리소스와 ID가 d507417e90e 및 e9950d90e인 관찰 리소스 두 개를 복구하려면 필터 파일에 다음을 지정합니다.

Patient/8f25b0ac
Observation/d507417e90e
Observation/e9950d90e

커스텀 함수 사용

Cloud Healthcare API는 다음과 같은 커스텀 필터링 함수를 제공합니다. 커스텀 함수를 rollbackTime 필드와 결합하여 추가 필터를 적용할 수 있습니다.

tag
세부정보
함수 구문
tag("system") = "code"
설명
리소스 Meta.tag 요소를 기준으로 FHIR 리소스를 필터링합니다.
인수
system
string
코드 시스템을 참조하는 URL입니다. 자세한 내용은 리소스에서 코드 사용을 참조하세요.
code
string
코드 시스템에서 정의된 개념을 식별하는 값입니다. 자세한 내용은 리소스에서 코드 사용을 참조하세요.
extension_value_ts
세부정보
함수 구문
extension_value_ts("url")
설명
extension 요소의 url 값을 기준으로 FHIR 리소스를 필터링합니다. 여기서 url은 Unix 타임스탬프입니다. 다음 비교 연산자를 지원합니다.
  • =
  • !=
  • <
  • >
  • <=
  • >=
인수
url
string
확장 프로그램을 정의하는 StructureDefinition 리소스의 표준 URL입니다. 예를 들어 다음 extension 요소에서 url은 http://hl7.org/fhir/StructureDefinition/timezone입니다. 
"extension" : [{
  "url" : "http://hl7.org/fhir/StructureDefinition/timezone",
  "valueCode" : "America/New_York"
}]
자세한 내용은 확장 프로그램 정의를 참조하세요.

FHIR 리소스 유형별로 필터링

리소스 유형만을 기준으로 FHIR 리소스를 더 광범위하게 필터링하려면 types[] 배열에 리소스 유형을 지정합니다.

작업 유형별로 필터링

CREATE, UPDATE 또는 DELETE 트랜잭션으로 수정된 FHIR 리소스를 필터링하려면 ChangeType 열거형의 값을 지정합니다.

예를 들어 삭제된 FHIR 리소스만 복구하려면 DELETE 값을 지정합니다.

CHANGE_TYPE_UNSPECIFIED 또는 ALL을 지정하거나 값을 지정하지 않으면 모든 FHIR 리소스가 복구됩니다.

이전 복구 제외

FHIR 리소스를 복구할 때 이전 복구를 제외하려면 excludeRollbacks 필드를 true로 설정합니다. 복구가 제대로 작동했고 그에 따른 변경사항을 덮어쓰지 않으려는 경우 이전 복구를 제외할 수 있습니다. 타임스탬프가 겹치는 여러 복구를 실행할 수도 있습니다.

다음 상황을 살펴보세요.

  1. 1:00에 복구 타임스탬프가 0:01로 설정된 복구를 시작합니다. 2:00에 복구 작업이 FHIR 저장소에서 Patient/1 및 Patient/2 환자 리소스를 삭제합니다. 3:00에 복구 작업이 종료됩니다.

  2. 며칠 후 복구 타임스탬프를 1:00으로 설정하여 복구 작업을 실행합니다. 기본적으로 작업 실행의 결과는 다음과 같습니다.

    • Patient/1 및 Patient/2 환자 리소스를 잘못 다시 생성합니다.
    • 3:00 이후에 생성 또는 업데이트된 FHIR 리소스를 올바르게 복구합니다.

Patient/1 및 Patient/2 환자 리소스를 삭제한 초기 복구 작업을 제외하여 해당 리소스를 다시 만들지 않으려면 excludeRollbacks를 true로 설정합니다.

장기 실행 작업(LRO) ID를 사용하여 필터링

FHIR 리소스가 하나 이상의 장기 실행 작업(LRO)으로 수정된 경우 operationIds 필드에 LRO ID를 지정하여 수정된 리소스를 복구할 수 있습니다.

Cloud Healthcare API 데이터 세트의 LRO ID를 나열하고 확인하는 방법에 대한 자세한 내용은 LRO 나열을 참조하세요.

프로덕션에서 복구에 실패한 FHIR 리소스 재시도

일부 FHIR 리소스가 프로덕션 복구에 실패한 경우 복구를 다시 시도할 수 있습니다. 생성된 프로덕션 출력 파일을 사용하여 실패한 FHIR 리소스를 찾습니다. 필터 파일에 이러한 FHIR 리소스의 유형과 ID를 지정하고 복구를 다시 실행합니다.

각 요청에서 동일한 구성을 사용하고 타임스탬프가 지난 21일 이내이면 복구를 실행할 때마다 복구가 멱등성을 갖습니다.

제한사항

  • PITR은 FHIR 저장소의 disableReferentialIntegrity 설정에 관계없이 참조 무결성을 적용하지 않습니다. 일부 FHIR 리소스만 복원하면 FHIR 저장소가 참조 무결성을 위반하는 상태로 유지될 수 있습니다.

  • 복원된 FHIR 리소스는 생성 또는 업데이트될 때 검증되었으므로 PITR은 FHIR 프로필 검증을 건너뜁니다. FHIR 저장소 프로필 구성이 변경되면 PITR로 인해 FHIR 저장소가 프로필 검증을 위반하는 상태로 유지될 수 있습니다.

  • rollbackTime 값이 FHIR 저장소에서 FHIR 리소스가 삭제된 시간보다 앞선 경우 FHIR 저장소에 enableUpdateCreate가 사용 설정되어야 리소스가 복구됩니다.

  • 복구 중에 FHIR 저장소를 업데이트하거나 데이터를 읽고 쓸 수 있지만 복구 단계에 따라서는 예상치 못한 결과가 나타날 수 있습니다. 예를 들어 읽기 요청은 복구된 리소스와 복구되지 않은 FHIR 리소스의 조합을 반환할 수 있습니다. 리소스를 업데이트하면 복구 시 업데이트를 덮어쓸 수 있습니다.

  • PITR은 FHIR 리소스 기록을 유지합니다. 복원된 각 리소스는 새로운 현재 버전을 가져오고 해당 기록은 보존됩니다.