문제 해결

Cloud Healthcare API를 사용하는 데 문제가 발생하면 도움이 될 수 있는 문제 해결 단계를 알아봅니다.

Cloud Healthcare API를 사용 설정할 수 없음

Google Cloud 프로젝트에서 Cloud Healthcare API를 처음 사용 설정하면 프로젝트에 Google Cloud APIs를 사용 설정할 수 있는 권한이 없다는 권한 오류가 발생할 수 있습니다.

Cloud Healthcare API를 포함한 Google Cloud APIs 사용 설정 방법에 대한 자세한 내용은 API 사용 설정 및 중지를 참조하세요.

Cloud Healthcare API에 인증할 수 없음

Cloud Healthcare API를 호출할 때 '애플리케이션 기본 사용자 인증 정보'를 사용할 수 없다는 오류 메시지가 표시될 수 있습니다.

애플리케이션 기본 사용자 인증 정보를 구성하는 방법 또는 인증 사용자 인증 정보를 애플리케이션 또는 명령어로 수동으로 전달하는 방법에 대한 자세한 내용은 API에 인증을 참조하세요.

Cloud Healthcare API 서비스 계정 또는 Healthcare 서비스 에이전트 역할 누락

Cloud Healthcare API를 사용 설정하고 첫 번째 데이터 세트를 만들면 Cloud Healthcare 서비스 에이전트 서비스 계정이 자동으로 생성됩니다. 이 계정은 Google 관리형 서비스 계정입니다. 서비스 계정을 완전히 삭제할 수 없지만 특정 환경에서는 ID 및 액세스 관리 페이지에 표시되지 않을 수 있으며, Cloud Healthcare API에 문제가 발생할 수 있습니다.

Cloud Healthcare API가 올바르게 작동하고 Pub/Sub에서 메시지를 게시 및 수신하거나 Cloud Logging에 측정항목을 작성하는 것과 같은 작업을 완료하기 위해서는 Cloud Healthcare 서비스 에이전트 서비스 계정이 존재해야 하며, Healthcare 서비스 에이전트 IAM 역할을 포함해야 합니다.

다음 문제 중 하나가 발생하면 Cloud Healthcare 서비스 에이전트 서비스 계정을 다시 만들거나 Healthcare 서비스 에이전트 IAM 역할을 부여할 수 있습니다.

  • ID 및 액세스 관리 페이지에서 Cloud Healthcare 서비스 에이전트 서비스 계정을 찾을 수 없습니다.
  • Cloud Healthcare 서비스 에이전트 서비스 계정은 찾을 수 있지만 Healthcare 서비스 에이전트 역할은 포함되어 있지 않습니다.

Google Cloud CLI를 사용하여 healthcare.serviceAgent 역할을 서비스 계정 식별자(service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com 형식 사용)를 사용하는 Cloud Healthcare Service Agent 서비스 계정에 추가합니다.

서비스 계정을 다시 만들거나 Healthcare 서비스 에이전트 IAM 역할을 부여하려면 gcloud projects add-iam-policy-binding 명령어를 실행합니다. PROJECT_ID 및 PROJECT_NUMBER를 찾으려면 프로젝트 식별을 참조하세요.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com \
    --role=roles/healthcare.serviceAgent

요청이 성공하면 명령어 프롬프트에 다음 샘플과 유사한 메시지가 표시됩니다.

Updated IAM policy for project [PROJECT_ID].
bindings:
...
- members:
  - serviceAccount:service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount.com
  role: roles/healthcare.serviceAgent
...
etag: VALUE
version: VALUE

Identity and Access Management 페이지로 돌아가서 다음을 확인합니다.

  • 구성원 열에는 service-PROJECT_NUMBER@gcp-sa-healthcare.iam.gserviceaccount 형식의 서비스 계정 식별자가 포함되어 있습니다.
  • 구성원 열과 같은 행의 이름 열에는 Cloud Healthcare 서비스 에이전트가 포함되어 있습니다.
  • 구성원 열과 같은 행의 역할 열에는 Healthcare 서비스 에이전트가 포함되어 있습니다.

누적 과부하로 인해 FHIR 트랜잭션 번들 취소됨

FHIR 트랜잭션 번들을 실행할 때 요청이 '트랜잭션 번들 실행에 대한 누적 과부하로 인해 취소됨'을 나타내는 오류 메시지가 수신될 수 있습니다.

트랜잭션 번들을 실행할 때 만들 수 있는 잠금 경합 양에는 제한이 없습니다. 예를 들어 각 번들에서 공통 환자 리소스 하나를 업데이트하고 공통적이지 않은 일부 다른 리소스도 만드는 번들 집합을 구축하고 동시에 실행하는 경우 모든 번들에서 전체 트랜잭션의 공통 환자를 잠가야 하므로 소요 시간이 빠르게 증가합니다. 이로 인해 시간이 제한되기 시작합니다. Cloud Healthcare API에서 트랜잭션 번들 제한 시간을 감지하면 이 오류 메시지가 있는 모든 트랜잭션 번들을 일시적으로 거부하여 경합을 해결합니다.

이 문제를 방지하려면 다음 중 하나를 시도해 보세요.

  • 트랜잭션 시맨틱스가 필요하지 않은 경우 일괄 번들을 사용합니다. 일괄 번들은 원자적이지 않으므로 이 문제를 완전히 피할 수 있습니다. 하지만 이렇게 하면 참조 무결성 적용이 줄어듭니다.
  • 동시에 업데이트되는 리소스를 식별할 수 있다면 업데이트를 제외하거나 피할 수 있는지 확인합니다. FHIR에서 Observation과 같은 새 리소스를 만들고 이미 존재하며 변경되지 않는 연결된 Patient(또는 Organization, Location, Device 등)를 업데이트하는 경우에도 이 문제가 발생합니다.
  • 클라이언트 측에 대한 비율 제한은 트랜잭션 번들이 실행되는 데 시간이 오래 걸리는 경우 요청 시간이 초과되기 전에 수집 속도를 줄이세요.