장기 실행 작업 관리

이 페이지에서는 Cloud Healthcare API 장기 실행 작업(LRO)의 수명 주기를 관리하는 방법을 설명합니다.

API 메서드가 완료되는 데 시간이 오래 걸리면 클라이언트에 Operation을 반환할 수 있습니다. 클라이언트는 Operation 인터페이스를 사용해서 작업을 폴링하여 API 메서드 상태를 비동기적으로 검색할 수 있습니다. Cloud Healthcare API의 LRO는 Google Cloud LRO 디자인 패턴을 준수합니다.

Cloud Healthcare API는 projects.locations.datasets.fhirStores.import와 같은 여러 메서드에 대해 LRO를 만듭니다. projects.locations.datasets.fhirStores.import가 호출되면 Cloud Healthcare API가 가져오기 상태를 추적하기 위한 LRO를 만듭니다. 이 LRO에는 LRO 상태를 확인하는 데 사용할 수 있는 고유 식별자가 포함됩니다.

LRO는 데이터 세트 수준에서 관리됩니다. projects.locations.datasets.fhirStores.import와 같이 LRO를 반환하는 메서드를 호출하는 경우 가져오기가 수행되는 FHIR 저장소의 환자 데이터 세트로 LRO ID가 포함된 요청을 전송하여 LRO 상태를 확인할 수 있습니다.

REST API 외에도 다음 소스는 LRO를 반환하는 메서드에 나열된 메서드를 호출할 때 장기 실행 작업을 생성합니다.

Google Cloud CLI
Google Cloud 콘솔의 Cloud Healthcare API 페이지

Google Cloud 콘솔, Google Cloud CLI 또는 REST API를 사용하여 Cloud Healthcare API LRO를 관리할 수 있습니다.

LRO 레코드는 LRO가 완료된 후 약 30일 동안 유지됩니다. 이후에는 LRO를 보거나 나열할 수 없습니다.

LRO를 반환하는 메서드

다음 메서드는 LRO를 반환합니다.

동의 관리 메서드:

projects.locations.datasets.consentStores.queryAccessibleData

데이터 세트 메서드:

DICOM 메서드:

FHIR 메서드:

HL7v2 메서드:

LRO 세부정보 가져오기

다음 샘플은 LRO에 대한 세부정보를 확인하는 방법을 보여줍니다.

LRO에 대한 세부정보를 가져올 때 응답에 표시되는 Cloud Healthcare API의 버전은 LRO를 시작한 메서드의 API 버전과 동일합니다.

콘솔

gcloud CLI 또는 LRO를 반환하는 API를 사용하여 메서드를 호출하면 Google Cloud 콘솔에서 LRO에 대한 세부정보를 볼 수 있습니다.

Google Cloud 콘솔에서 데이터 세트 페이지로 이동합니다.

데이터 세트로 이동
보려는 LRO가 포함된 데이터 세트의 이름을 클릭합니다.
작업을 클릭합니다.
Cloud Logging의 작업 오류 로그를 보려면 작업을 클릭한 다음 Cloud Logging에서 세부정보 보기를 클릭합니다. 자세한 내용은 Cloud Logging에서 오류 로그 보기를 참조하세요.
작업에 대한 자세한 내용을 보려면 실행 중인 작업 ID를 클릭합니다. 장기 실행 작업 세부정보 페이지가 표시됩니다. 페이지에는 다음 정보가 표시됩니다.
- LRO 진행률
- 작업 ID 및 LRO를 호출한 메서드와 같은 LRO 세부정보
- 로그 항목의 하위 집합

gcloud

gcloud healthcare dicom-stores deidentify 호출 후 다음 응답이 수신되었다고 가정해보세요.

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...

응답에는 Cloud Healthcare API로 작업 ID가 포함된 LRO가 생성된 것이 표시됩니다. 또한 장기 실행 데이터베이스 작업을 나열하여 작업 ID를 검색할 수 있습니다. 이 명령어는 완료될 때까지 계속 실행되고, 이후에 다음을 출력합니다.

Request issued for: [DATASET_ID]
Waiting for operation [OPERATION_ID] to complete...done
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID

LRO 세부정보를 가져오려면 gcloud healthcare operations describe 명령어를 실행합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

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

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

Linux, macOS 또는 Cloud Shell

gcloud healthcare operations describe OPERATION_ID \
    --project=PROJECT_ID \
    --dataset=DATASET_ID \
    --location=LOCATION

Windows(PowerShell)

gcloud healthcare operations describe OPERATION_ID `
    --project=PROJECT_ID `
    --dataset=DATASET_ID `
    --location=LOCATION

Windows(cmd.exe)

gcloud healthcare operations describe OPERATION_ID ^
    --project=PROJECT_ID ^
    --dataset=DATASET_ID ^
    --location=LOCATION

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

응답

done: true
// 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: ERROR
  code: ERROR_CODE
  message: DESCRIPTION
metadata:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata'
  apiMethodName: 'google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore'
  counter:
    success: 'SUCCESS_COUNT'
    // If there were any failures, they display in the `failure` field.
    failure: 'FAILURE_COUNT'
  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
name: projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID
// The `response` field only displays if there were no errors.
response:
  '@type': 'type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary'

REST

projects.locations.datasets.dicomStores.deidentify 호출 후 다음 응답이 수신되었다고 가정해보세요.

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
}

name 값은 Cloud Healthcare API로 projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID라는 LRO가 생성된 것을 보여줍니다. 또한 LRO를 나열하여 LRO 이름을 검색할 수 있습니다.

LRO 상태를 가져오려면 projects.locations.datasets.operations.get 메서드를 사용합니다. LRO를 폴링하려면 작업이 완료될 때까지 projects.locations.datasets.operations.get 메서드를 반복해서 호출합니다. 각 폴링 요청 사이에 백오프를 사용합니다(예: 10초).

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

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

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

curl

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

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

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

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

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

$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가 포함되었으면 장기 실행 작업이 완료된 것입니다.

응답

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
    "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": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
    
  },
  // 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를 나열하는 방법을 보여줍니다.

콘솔

Google Cloud 콘솔에서 데이터 세트의 모든 LRO 목록을 보려면 다음 단계를 완료합니다.

Google Cloud 콘솔에서 데이터 세트 페이지로 이동합니다.

데이터 세트로 이동
보려는 LRO가 포함된 데이터 세트의 이름을 클릭합니다.
작업을 클릭합니다.

데이터 세트에 있는 LRO 및 해당 상태 목록이 표시됩니다. Cloud Logging에서 오류 로그를 보려면 마지막 열의 추가 정보 아이콘을 클릭한 다음 Cloud Logging에서 세부정보 보기를 클릭합니다. 자세한 내용은 Cloud Logging에서 오류 로그 보기를 참조하세요.

gcloud

데이터 세트의 LRO를 나열하려면 gcloud healthcare operations list 명령어를 실행합니다.

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

DATASET_ID: 데이터 세트 ID
LOCATION: 데이터 세트 위치

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

Linux, macOS 또는 Cloud Shell

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows(PowerShell)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

Windows(cmd.exe)

gcloud healthcare operations list --dataset=DATASET_ID --location=LOCATION

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

응답

ID             LOCATION     DONE
OPERATION_ID   LOCATION {TRUE|FALSE}
...

REST

데이터 세트의 LRO를 나열하려면 projects.locations.datasets.operations.get 메서드를 사용합니다.

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

PROJECT_ID: Google Cloud 프로젝트의 ID
DATASET_ID: 데이터 세트 ID
LOCATION: 데이터 세트 위치

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

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"

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" | Select-Object -Expand Content

API 탐색기

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

응답

{
  "operations": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
        "apiMethodName": "google.cloud.healthcare.v1.deidentify.DeidentifyService.DeidentifyDicomStore",
        "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": "type.googleapis.com/google.cloud.healthcare.v1.deidentify.DeidentifySummary"
      },
      // 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를 취소하는 방법을 보여줍니다.

콘솔

Google Cloud 콘솔에서 LRO를 취소하려면 다음 단계를 완료합니다.

Google Cloud 콘솔에서 데이터 세트 페이지로 이동합니다.

데이터 세트로 이동
보려는 LRO가 포함된 데이터 세트의 이름을 클릭합니다.
작업을 클릭합니다.
취소하려는 LRO와 동일한 행에서 작업 목록을 열고 작업 중지를 클릭합니다.

REST

LRO를 취소하려면 projects.locations.datasets.operations.cancel 메서드를 사용합니다.

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

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

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

curl

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID:cancel"

PowerShell

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

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

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

API 탐색기

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

응답

{}

취소 요청의 상태를 보려면 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 탐색기

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

응답

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata",
    "apiMethodName": "API_METHOD_NAME",
    "createTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "endTime": "YYYY-MM-DDTHH:MM:SS+ZZ:ZZ",
    "cancelRequested": true,
    "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,
  "error": {
    "code": 1,
    "message": "Operation cancelled by user. Any progress already completed by the operation will not be reverted."
  }
}

여러 LRO 취소

여러 LRO를 취소하려면 다음 단계를 완료합니다.

operations.list 메서드를 호출하여 데이터 세트의 작업 이름을 가져옵니다.
각 작업에서 operations.cancel 메서드를 호출합니다.

Google에서는 제공된 데이터 세트에 대해 모든 작업을 취소하기 위해 사용할 수 있는 Python 스크립트를 제공합니다.

LRO 문제 해결

LRO가 실패하면 해당 응답에 표준 Google Cloud 오류 코드가 포함됩니다. 다음 표에서는 각 코드의 원인에 대한 설명과 코드 처리 방법에 대한 권장사항을 보여줍니다. 많은 오류의 경우 지수 백오프를 사용해서 요청을 다시 시도하는 것이 좋습니다. Cloud Healthcare API에서 지수 백오프를 구현하는 방법은 실패한 요청 재시도를 참조하세요.

코드	Enum	설명	권장 조치
1	`CANCELLED`	작업이 취소되었습니다. 대개 호출자에 의해 취소됩니다.	원하는 경우 작업을 다시 실행합니다.
2	`UNKNOWN`	다른 주소 공간에서 수신된 `Status` 값이 이 주소 공간에서 알려지지 않은 오류 공간에 속하는 경우 이 오류가 반환될 수 있습니다. API 오류가 충분한 정보를 반환하지 않으면 해당 오류가 이 오류로 변환될 수 있습니다.	지수 백오프로 다시 시도합니다.
3	`INVALID_ARGUMENT`	클라이언트에서 잘못된 인수를 지정했습니다. 이 오류는 `FAILED_PRECONDITION`과 다릅니다. `INVALID_ARGUMENT`는 시스템 상태에 관계없이 문제(예: 잘못된 형식의 파일 이름)가 있는 인수를 나타냅니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
4	`DEADLINE_EXCEEDED`	작업을 완료하기 전에 기한이 지났습니다. 작업에서 시스템의 상태를 변경하는 경우 작업이 정상적으로 완료되었어도 이 오류가 반환될 수 있습니다. 예를 들어 서버의 성공 응답이 오래 지연되어 기한이 지났을 수 있습니다.	지수 백오프로 다시 시도합니다.
5	`NOT_FOUND`	FHIR 리소스와 같은 일부 요청한 항목을 찾을 수 없습니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
6	`ALREADY_EXISTS`	클라이언트에서 만들려고 시도한 항목(예: DICOM 인스턴스)이 이미 존재합니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
7	`PERMISSION_DENIED`	호출자에 지정한 작업을 실행할 권한이 없습니다. 이 오류 코드는 요청이 유효하다거나, 요청된 항목이 존재한다거나, 다른 전제조건이 충족되었음을 의미하지 않습니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
8	`RESOURCE_EXHAUSTED`	프로젝트당 할당량과 같은 일부 리소스가 소진되었습니다. 권장 조치는 할당량 관리 권장사항을 참조하세요.	지수 백오프로 다시 시도합니다. 할당량은 시간 경과에 따라 사용 가능해질 수 있습니다.
9	`FAILED_PRECONDITION`	시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부되었습니다. 예를 들어 삭제할 디렉토리가 비어 있지 않거나 디렉토리가 아닌 항목에 `rmdir` 작업을 적용한 경우입니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
10	`ABORTED`	작업이 취소되었습니다. 대개 시퀀서 확인 실패, 트랜잭션 취소 등의 동시 실행 문제가 원인입니다.	지수 백오프로 다시 시도합니다.
11	`OUT_OF_RANGE`	파일 끝을 지나서 탐색하거나 읽는 등 유효한 범위를 넘어서 작업을 시도했습니다. `INVALID_ARGUMENT`와 달리, 이 오류는 시스템 상태가 변경되면 문제가 해결될 수 있음을 나타냅니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.
12	`UNIMPLEMENTED`	작업이 구현되지 않았거나 Cloud Healthcare API에서 지원되지 않거나 사용 설정되지 않았습니다.	재시도하지 마세요.
13	`INTERNAL`	내부 오류가 발생했습니다. 기본 시스템에서 처리 중에 예기치 않은 오류가 발생했음을 나타냅니다.	지수 백오프로 다시 시도합니다.
14	`UNAVAILABLE`	현재 Cloud Healthcare API를 사용할 수 없습니다. 일시적인 상태일 가능성이 높으며, 잠시 시간을 두고 다시 시도하면 해결될 수 있습니다. 멱등성이 없는 작업을 재시도하는 것이 항상 안전한 것은 아닙니다.	지수 백오프로 다시 시도합니다.
15	`DATA_LOSS`	복구할 수 없는 데이터 손실이나 손상이 발생했습니다.	시스템 관리자에게 문의하세요. 데이터 손실 또는 손상이 발생한 경우 시스템 관리자가 지원 담당자에게 연락해야 할 수 있습니다.
16	`UNAUTHENTICATED`	요청에 작업과 관련된 올바른 사용자 인증 정보가 없습니다.	문제를 해결하지 않은 상태로 다시 시도하지 마세요.