장기 실행 작업 권장사항

이 페이지에서는 Cloud Healthcare API에서 장기 실행 작업(LRO) 실행 및 관리를 위한 권장사항을 설명합니다. Cloud Healthcare API에서 LRO 개요는 장기 실행 작업 관리를 참조하세요.

LRO 속성

다음 섹션은 LRO를 반환하는 메서드에 나열된 메서드에 적용됩니다.

할당량 영향

LRO는 다음 유형의 할당량을 소비하는 Cloud Healthcare API 만들기, 읽기, 업데이트, 삭제(CRUD) 메서드와 할당량을 공유하지 않습니다.

• fhir_read_ops
• fhir_write_ops
• fhir_search_ops
• fhir_store_ops
• dicom_web_ops
• dicom_ops

LRO 할당량은 fhir_store_lro_ops 및 dicom_store_lro_ops 측정항목을 사용해서 계산됩니다.

Cloud Healthcare API는 Google Cloud 프로젝트에서 동시에 실행될 수 있는 LRO 수를 제한합니다. 자세한 내용은 LRO 수 제한을 참조하세요.

데이터 처리량

LRO 메서드는 일반적으로 상응하는 CRUD 메서드보다 높은 데이터 처리량을 달성합니다. 예를 들어 dicomStores.import로 DICOM 인스턴스를 가져오는 것이 dicomStores.storeInstances로 개별적으로 인스턴스를 저장하는 것보다 성능이 뛰어납니다.

특히 대규모 데이터 볼륨을 처리할 때는 다음과 같은 제약조건으로 인해 여러 LRO를 동시에 실행해도 데이터 처리량이 증가하지 않을 수 있습니다.

• 할당량 제한사항
• 리소스 경합
• LRO 실행 중 Google Cloud 프로젝트가 Cloud Healthcare API로 전송하는 기타 트래픽

LRO를 실행할 때 데이터 처리량을 극대화하려면 다음을 고려하세요.

• 소규모 가져오기 및 내보내기 배치는 일반적으로 오버헤드로 인해 처리량이 낮습니다.
• LRO는 다른 Cloud Healthcare API 작업과 별개로 할당량을 실행하고 소비합니다.
• 각 LRO에는 최대 처리량이 있습니다.
• 동일 리소스에서 동시에 수행되는 LRO는 잠금 경합을 일으킬 수 있습니다.
• Cloud Healthcare API는 Google Cloud 프로젝트에서 동시에 실행될 수 있는 LRO 수를 제한합니다. 자세한 내용은 LRO 수 제한을 참조하세요.

사용 사례에 필요한 LRO 수를 계획합니다. 여러 LRO 간에 대규모 데이터 배치를 파티션으로 나눠야 하는 경우 파티션 수를 낮게 유지해야 합니다.

FHIR 참조 무결성

fhirStores.import 메서드는 disableReferentialIntegrity 설정을 고려하지 않습니다. 이렇게 하면 데이터 처리량이 증가하는 순서 지정 또는 그룹화가 필요하지 않은 임의의 상호 의존성으로 데이터를 가져올 수 있습니다. 입력 데이터에 잘못된 참조가 있거나 일부 FHIR 리소스를 가져오지 못한 경우 FHIR 저장소 상태가 참조 무결성을 위반할 수 있습니다.

fhirStores.import를 사용하려면 클라이언트 애플리케이션이 다음을 확인하여 FHIR 리소스 참조가 올바른지 확인해야 합니다.

• 올바른 FHIR 리소스 데이터 및 형식
• 가져오기 중 발생하는 모든 오류 관리

참조 무결성을 적용하려면 fhirStores.import 대신 fhir.create 또는 fhir.executeBundle을 사용합니다. 자세한 내용은 FHIR 데이터 가져오기와 번들 실행 비교를 참조하세요.

Pub/Sub 알림

일부 Cloud Healthcare API 메서드는 의료 리소스 만들기 또는 삭제와 같은 의료 이벤트에 대한 Pub/Sub 알림을 전송합니다. Pub/Sub 알림을 전송하는 메서드 목록은 Pub/Sub 알림 구성을 참조하세요.

다음 가져오기 메서드는 Pub/Sub 알림을 전송하지 않습니다.

• dicomStores.import
• fhirStores.import

가져오기가 완료되었을 때 애플리케이션 일부에 알림이 필요하면 가져오기의 데이터를 나열할 수 있는 다른 알림 메서드를 사용합니다.

오류 처리 한도

Cloud Healthcare API는 특히 LRO가 대규모 데이터 볼륨을 처리하고 많은 오류를 생성하는 경우 LRO의 모든 오류를 로깅하지 못할 수 있습니다. LRO 처리 및 오류를 개별적으로 추적할 수 방법을 구현하세요. 자세한 내용은 리소스 오류 처리를 참조하세요.

데이터 및 검색 색인

비동기 검색 색인으로 인해 검색 결과에 지연이 발생할 수 있습니다. LRO가 FHIR 리소스를 만들거나 업데이트하는 경우 검색 결과에 변경사항이 제공되기 전에 추가 시간이 걸릴 수 있습니다.

예를 들어 FHIR 저장소에서 환자 리소스를 검색하면 FHIR 가져오기 작업 직후 모든 결과가 반환되지 않을 수 있습니다.

실행 순서

LRO는 Google Cloud 리소스 가용성을 기준으로 예약됩니다. LRO가 실행되고 완료되는 순서는 요청된 순서와 일치하지 않을 수 있습니다.

소규모 가져오기 및 내보내기 요청 방지

이 섹션에서는 소규모 데이터 볼륨을 처리할 때의 LRO 제한사항을 설명합니다.

가져오기 및 내보내기 작업으로 반환된 LRO는 대규모 데이터 양을 빠르게 처리하고 로드 급증을 방지하여 데이터 처리량을 확장하는 데 도움이 됩니다. 소규모 데이터 양을 저장하려면 데이터 저장 권장사항의 다른 기법을 사용합니다.

LRO 수 제한

Cloud Healthcare API는 Google Cloud 프로젝트에서 동시에 실행될 수 있는 LRO 수를 제한합니다. 이 한도는 다음을 기반으로 합니다.

• LRO 유형
• LRO에 할당된 Google Cloud 리소스 양 이는 입력 데이터의 크기를 기반으로 합니다.

LRO를 너무 많이 실행하면 Cloud Healthcare API 비율이 제한되고 오류가 발생하고, LRO 처리량이 저하될 수 있습니다. Cloud Healthcare API는 LRO 수가 리소스 한도 내로 유지되도록 Google Cloud 리소스를 자동으로 보존합니다.

LRO는 백그라운드 프로세스이므로, LRO의 로드가 CRUD 작업과 같이 우선순위가 높은 프로세스와 충돌할 경우 Cloud Healthcare API가 LRO 처리량을 줄일 수 있습니다. 그 결과 더 높은 우선순위의 프로세스를 사용할 수 있습니다.

리소스 할당 및 삭제 오버헤드

LRO가 시작되면 Cloud Healthcare API가 리소스를 할당합니다. Cloud Healthcare API가 다음을 수행해야 하기 때문에 이 작업은 몇 분 정도 걸릴 수 있습니다.

1. 컨트롤러 프로세스를 시작합니다.
2. 작업자 풀에서 작업자를 할당합니다.
3. 입력 데이터 크기를 결정합니다.
4. 규모에 맞게 작업 할당을 시작합니다.

LRO를 중지하고 삭제하는 것도 몇 분 정도 걸릴 수 있습니다.

오버헤드로 인해 소규모 데이터 양을 처리하는 LRO는 작업자 풀을 할당하고 리소스를 삭제하는 데 대부분의 시간을 소비할 수 있습니다.

이러한 LRO가 많으면 Google Cloud 프로젝트 할당량 한도를 충족시킬 가능성이 높기 때문에 데이터 처리량이 낮아질 수 있습니다.

LRO 할당량 요청 제한

추가 LRO 할당량을 요청하려면 먼저 할당량 관리 권장사항을 구현합니다. 할당량이 더 필요하면 Google Cloud 고객 지원에 문의하세요. 요청하려면 추가 할당량 요청 권장사항을 참조하세요.

입력 데이터가 크면 추가 할당량이 필요할 수 있습니다. 예를 들면 다음과 같습니다.

• 크기가 수 페타바이트(PB)에 달하는 DICOM 인스턴스를 가져옵니다.
• 수백억 개의 FHIR 리소스를 가져옵니다.

LRO 상태 및 오류 상태

LRO를 시작하면 응답에 고유 ID가 포함됩니다. 해당 ID를 폴링하여 LRO 상태를 확인할 수 있습니다. LRO가 완료되면 다음 상태 중 하나가 됩니다.

• 오류 없이 성공적으로 완료됨
• 일부 오류와 함께 성공적으로 완료됨
• 완료되지 않았지만 실패 전 일부 출력이 생성되었을 수 있음

다음 JSON 예시는 LRO가 완료될 때 반환되는 응답을 설명합니다.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "METADATA_TYPE",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "logsUrl": "https://console.cloud.google.com/CLOUD_LOGGING_URL"
    "counter": {
      "success": "SUCCESS_COUNT",
      // If there were any failures, they display in the `failure` field.
      "failure": "FAILURE_COUNT"
    }
  },
  "done": true,
  // The `response` field only displays if there were no errors.
  "response": {
    "@type":
  },
  // If there were any errors, an `error` field displays instead of a `response` field.
  // See Troubleshooting long-running operations for a list of response codes.
  "error": {
    "code": ERROR_CODE,
    "message": "DESCRIPTION",
    "details": [
      {
        "@type": "...",
        FIELD1: ...,
        ...
      }
    ]
  }
}

LRO 상태를 가져오고, LRO를 나열하고, LRO를 취소하려면 장기 실행 작업 관리를 참조하세요.

LRO 상태 및 오류 상태 관리

LRO 상태 및 오류 상태를 관리하려면 다음 권장사항을 수행합니다.

• LRO를 폴링하여 상태를 가져오고 완료되었는지 확인합니다. LRO를 폴링하려면 작업이 완료될 때까지 projects.locations.datasets.operations.get 메서드를 반복해서 호출합니다. 각 폴링 요청 사이에 백오프를 사용합니다(예: 10초). 응답에 "done": true가 포함되었으면 LRO가 완료된 것입니다.

• LRO가 완료되었으면 응답에 error 필드가 포함되었는지 확인합니다. 포함되었으면 다음을 기준으로 작업을 재시도할지 여부를 결정합니다.

  • 오류 코드. 오류 코드 및 권장 조치는 LRO 문제 해결을 참조하세요.
  • 이미 발생한 재시도 횟수
  • LRO가 시작된 시점과 오류가 발생한 시점 사이의 시간. 예를 들어 일반적으로 몇 시간 정도 걸리는 LRO에 며칠이 걸리고 오류 상태가 반환되지 않았으면 작업자 개입이 필요할 수 있습니다. 작업자 개입이 필요한 경우에 대한 자세한 내용은 최종 오류 상태 계획을 참조하세요.

  LRO를 재시도하는 방법에 대한 자세한 내용은 LRO 큐에 추가를 참조하세요.

• LROㄹ를 재시도하지 않는 경우 metadata.counter.failure 필드를 보고 특정 리소스에 오류가 발생했는지 확인합니다. 리소스를 개별적으로 처리할 수도 있습니다. 자세한 내용은 리소스 오류 처리를 참조하세요.

리소스 오류 처리

LRO는 오류와 함께 완료될 수 있습니다. LRO 응답의 오류는 Google Cloud 오류 모델을 따릅니다. LRO 응답에는 자세한 정보 확인을 위한 Cloud Logging 링크가 포함됩니다.

LRO 오류 세부정보

Cloud Logging의 LRO 오류에는 다음 속성이 포함됩니다.

• Cloud Logging 오류 로그에는 LRO ID가 포함되지 않습니다. operation.id 및 operation.producer 필드를 사용해서 LRO 상태 및 오류를 찾습니다. 예를 들어 projects.locations.datasets.fhirStores.import 메서드에서 호출된 LRO에는 operation.producer 필드의 import_fhir이 포함됩니다.

  여러 LRO에 동일한 operation.id 및 operation.producer가 있으면 createTime 및 endTime 타임스탬프를 사용해서 올바른 LRO를 식별합니다.

• 모든 LRO 오류가 Cloud Logging에 제공되지는 않습니다. metadata.counter.failure 필드는 다음으로 인해 로깅되는 실제 오류 수를 초과할 수 있습니다.

  • Cloud Logging 할당량 제한
  • Cloud Logging 서비스 가용성
  • LRO 로그 제한

  예를 들어 LRO가 천만 개의 FHIR 리소스를 가져올 때 이 중에서 50%에 형식 지정 오류가 있으면 비율 제한 및 Cloud Logging 할당량으로 인해 몇 백 또는 몇 천 개의 오류만 로깅될 수 있습니다.

  또한 로깅되는 오류 수는 오류 비율이 높을 때 LRO 실행 시간의 길이에 따라 달라집니다. LRO가 느리게 실행되면 긴 시간 동안 오류가 분산되었고 비율 제한이 적용되지 않기 때문에 Cloud Logging에 오류가 더 많이 표시될 수 있습니다.

LRO 재시도 효과

LRO에 오류가 발생하고 클라이언트 애플리케이션이 동일한 데이터를 사용해서 작업을 재시도하면 재시도로 인해 더 많은 오류가 발생할 수 있습니다.

가져오려고 시도한 일부 FHIR 리소스가 잘못되었기 때문에 fhirStores.import LRO가 오류와 함께 완료되는 경우를 고려해보세요. 동일한 데이터로 가져오기를 자동으로 재시도하면 원래 작업에서 일부 FHIR 리소스를 가져왔기 때문에 많은 409 ALREADY_EXISTS 오류가 발생할 수 있습니다. LRO를 쿼리하고 실패한 생성 작업이 발견되면 자동으로 재시도하지 마세요. 사람이 409 ALREADY_EXISTS 오류를 검토해야 합니다.

재시도에 성공하면 metadata.counter.failure 필드에 이전 작업 오류가 포함되지 않습니다. 성공한 재시도의 응답에 이전 시도의 오류가 포함되지 않기 때문에 오류 수가 잘못될 수 있습니다.

LRO 재시도

LRO 오류를 감지하는 클라이언트 측 처리 파이프라인이 있으면 Cloud Logging을 사용하지 마세요. LRO 오류 세부정보에 표시된 것처럼 LRO에 대한 Cloud Logging 오류 로깅은 신뢰할 수 없고 완전하지 않습니다. 대신 다음 섹션의 기법을 사용하세요.

가져오기 작업 재시도

가져오기에 실패한 데이터를 감지하기 위해 Cloud Healthcare API의 가져온 데이터를 Cloud Storage의 소스 데이터와 비교합니다. 다음 방법을 사용해서 데이터를 가져올 수 있습니다.

• projects.locations.datasets.fhirStores.import
• projects.locations.datasets.dicomStores.import
• projects.locations.datasets.hl7V2Stores.import

FHIR 환자 리소스에 대한 의료 기록 번호(MRN)과 같은 고유 식별자를 사용해서 데이터를 비교합니다.

가져오기 작업을 재시도할 때 수행할 단계는 LRO 재시도 효과를 참조하세요.

가져오기를 다시 실행하면 이전에 삭제한 리소스가 다시 생성될 수 있습니다. 다음 상황을 살펴보세요.

1. 1,000,000개의 FHIR 리소스를 가져오려고 시도합니다. 50,000개의 리소스가 형식 지정 오류로 인해 실패합니다.
2. 형식 지정 오류를 수정하느라 며칠이 소요됩니다. 이 기간 동안 환자가 자신의 레코드 삭제를 요청합니다.
3. 가져오기를 다시 실행하면 이전에 삭제한 환자 데이터가 다시 생성될 위험이 있습니다.

내보내기 작업 재시도

BigQuery로 내보내지 못한 데이터를 감지하기 위해 소스 데이터의 고유 ID를 내보낸 데이터와 비교하는 스크립트를 작성합니다.

다음 방법을 사용하여 BigQuery로 데이터를 내보낼 수 있습니다.

• projects.locations.datasets.fhirStores.export
• projects.locations.datasets.dicomStores.export
• projects.locations.datasets.hl7V2Stores.export

LRO 큐에 넣기 및 관리

온보딩을 위해 또는 정기적인 일정에 따라 대규모 데이터 볼륨을 처리하는 LRO를 실행하는 경우 다음과 같은 LRO 큐에 넣기 기법을 구현합니다.

• 동시 LRO를 5와 같은 작은 숫자로 제한합니다. 실행하는 LRO 크기 및 유형에 따라 이 제한을 조정할 수 있습니다.
• LRO 완료를 모니터링합니다. 오류가 발생하면 LRO를 다시 예약하거나 처리 파이프라인에서 오류를 개별적으로 해결합니다.

• 가능하면 리소스 오류 처리의 오류를 자동으로 해결합니다.

  • FHIR 가져오기의 사용 사례를 파악해서 409 ALREADY_EXISTS 오류를 무시할지 또는 오류 해결을 위해 개별 CRUD 작업을 수행할지를 결정합니다. LRO 오류 세부정보에 표시된 것처럼 일부 409 ALREADY_EXISTS 오류는 Cloud Logging에 로깅되지 않을 수 있습니다. 애플리케이션이 오류 로그에 의존하는 경우 LRO 재시도의 기법 중 하나를 사용합니다.

  • 적은 수의 오류를 해결하려면 오류가 발생한 데이터에 대해 소규모 LRO를 큐에 넣거나 개별 CRUD 작업을 수행합니다.

  • 많은 수의 오류를 해결하려면 일관성 보장을 위해 LRO를 다시 실행하는 것이 가장 간단한 방법일 수 있습니다. 삭제된 데이터에 대해 가져오기를 다시 실행할 때의 위험은 가져오기 작업 재시도를 참조하세요.

• 오류 해결을 위해 사용자 개입이 필요한지 여부를 자동으로 감지합니다. 시스템 관리자를 위한 도구 및 운영 플레이북이 있어야 합니다. 오류를 해결하기 위한 태스크에는 다음이 포함될 수 있습니다.

  • LRO를 다시 예약합니다.
  • 이전 LRO에서 데이터 하위 집합을 다시 예약합니다.
  • 오류를 검사하고 오류가 발생한 개별 데이터 요소를 해결합니다. 이 태스크는 LRO의 모든 오류가 로깅된 것을 확인할 수 있는 경우에만 가능합니다.

• LRO 일정을 확인합니다. 실행 중인 CRUD 작업이 많을 때는 사용량이 많은 시간에 실행되지 않도록 LRO를 예약할 수 있습니다. 자세한 내용은 할당량 관리로 데이터 처리량 극대화를 참조하세요.

모니터링 및 알림 수신

LRO 모니터링하 및 알림 확인을 위한 절차를 만들고 유지합니다. 알림은 주로 LRO 상태 및 큐에 넣기 문제로 인해 발생합니다. 이러한 절차는 다음 상황을 해결해야 합니다.

• 구성된 것보다 많이 재시도가 실패하는 LRO
• 오류 하위 집합을 해결하기 위해 작업자 개입이 필요한 문제. 예를 들어 LRO가 실패하고 클라이언트가 오류를 해결할 수 없으면 사용자 개입이 필요할 수 있습니다. 사용자 개입이 필요한 문제 해결 방법에 대한 자세한 내용은 큐 및 LRO 관리를 참조하세요.
• 길이를 초과하거나 너무 빠르게 증가하는 큐
• 권한 문제 또는 잘못된 구성과 같이 충족되지 않은 정책 요구사항
• 여러 LRO 간의 체계적인 문제를 보여주는 일관성 검사. 소스 데이터 세트 및 대상 데이터 세트가 동일한 개수의 FHIR 리소스를 갖도록 요구되는 여러 익명화 LRO가 있을 수 있습니다. 시간이 지남에 따라 불일치가 발생하면 처리되지 않은 데이터가 있음을 나타낼 수 있습니다.
• LRO 할당량 문제. 자세한 내용은 할당량 관리로 데이터 처리량 극대화 및 할당량 관리 권장사항을 참조하세요.