長時間実行オペレーションの管理

このページでは、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 はデータセットレベルで管理されます。LRO を返すメソッド（projects.locations.datasets.fhirStores.import など）を呼び出す場合は、LRO ID を含むリクエストをインポートが行われている FHIR ストアの親データセットに送信して、LRO のステータスを表示できます。

REST API に加えて、次のソースでは、LRO を返すメソッドに一覧表示されているメソッドを呼び出すと、長時間実行オペレーションが生成されます。

Google Cloud CLI
Google Cloud Console の [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 の進行状況
- LRO の詳細（オペレーション ID や 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 Explorer

メソッドリファレンスページを開きます。ページの右側に [API Explorer] パネルが開きます。このツールを操作してリクエストを送信できます。必須フィールドを入力して、[Execute] をクリックします。

次のとおり出力されます。レスポンスに "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 Explorer

次のような 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 Explorer

次のような 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 Explorer

次のような 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 で指数バックオフを実装する方法については、失敗したリクエストの再試行をご覧ください。

コード	列挙型	説明	ご対応のお願い
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`	リクエストにはオペレーションに有効な認証情報がありません。	問題を解決してから再試行します。