v1beta1 API への更新

2020 年 8 月 26 日以降、v1beta1 は改定バージョンへの更新を開始しました。このページでは、この日付より前の v1beta1 のバージョンを「以前の v1beta1」と呼びます。それ以降のバージョンは「新しい v1beta1」と呼びます。以前の v1beta1 の動作が終了になる完了予定日は、2020 年 9 月 22 日です。

このページでは、v1beta1 の更新について説明します。これは主に、Cloud Healthcare API 間でのリクエストとレスポンスのフィールドの非推奨と追加に関わるものです。この変更を実装すると、v1beta1 と v1 間の共通のメソッド、リソース、レスポンス、リクエストなどが連携します。また、このセクションでは、以前の v1beta1 から新しい v1beta1 に移行する方法の例についても説明します。

重要: 新しい v1beta1 への移行期間中、以前の v1beta1 の動作と、新しい v1beta1 の動作はどちらも有効です。新しい v1beta1 の動作のみが受け入れられる場合に備えて、両方の動作タイプに対応するようにクライアント コードを更新することをおすすめします。

アノテーションの変更点

アノテーションのインポートとエクスポート

以前の v1beta1 では、annotationStores.import と annotationStores.export は annotationStore パラメータを使用してアノテーション ストアを識別していました。新しい v1beta1 では、annotationStore ではなく name を使用してアノテーション ストアを識別します。

アノテーション ストアの評価

以前の v1beta1 では、annotationStores.evaluate は evalStore パラメータを使用して、ゴールデン ストアと比較するためのアノテーション ストアを識別していました。新しい v1beta1 では、evalStore の代わりに name を使用して、ゴールデン ストアと比較するためのアノテーション ストアを識別します。

ImportAnnotationsErrorDetails と ExportAnnotationsErrorDetails。

新しい v1beta1 では、ImportAnnotationsErrorDetails レスポンスと ExportAnnotationsErrorDetails レスポンスが削除されています。代わりに、Cloud Logging でエラーの詳細を表示できます。

ImportAnnotationsResponse、ExportAnnotationsResponse、EvaluateAnnotationStoreResponse

• ImportAnnotationsResponse と ExportAnnotationsResponse。これらはインポートまたはエクスポートの長時間実行オペレーションの Operation.response フィールドに含まれ、annotationStore フィールドまたは successCount フィールドには含まれなくなりました。代わりに、返された長時間実行オペレーションで返される Operation.metadata フィールドで、成功と失敗の数を表示できます。
• EvaluateAnnotationStoreResponse。これは評価の長時間実行オペレーションの Operation.response フィールドに含まれ、evalStore、goldenStore、goldenCount または matchedCount のフィールドには含まれなくなりました。代わりに、matchedCount の値を見つけるには、Operation.metadata の success フィールドを表示します。goldenCount の値を見つけるには、success フィールドの値と、failure フィールドの値を Operation.metadata に追加します。

Data de-identification の変更

DeidentifyErrorDetails 削除

DeidentifyErrorDetails レスポンスは、新しい v1beta1 で使用できなくなりました。代わりに、Cloud Logging でエラーの詳細を表示できます。

SuccessResourceCount 削除

以前の v1beta1 では、次のレスポンスに SuccessResourceCount フィールドが含まれていました。

• DeidentifySummary
• DeidentifyErrorDetails
• DeidentifyDicomStoreSummary
• DeidentifyFhirStoreSummary

新しい v1beta1 では、これらのレスポンスに SuccessResourceCount フィールドは含まれなくなりました。代わりに、Cloud Healthcare API が正常に匿名化したリソースを、長時間実行オペレーション レスポンスの progress_counter.success フィールドに表示できます。

SuccessStoreCount と FailureStoreCount の削除

以前の v1beta1 では、次のレスポンスに SuccessStoreCount フィールドが含まれていました。

• DeidentifySummary
• DeidentifyErrorDetails

DeidentifyErrorDetails にも FailureStoreCount フィールドが含まれていました。

新しい v1beta1 では、これらのレスポンスに SuccessStoreCount フィールドまたは FailureStoreCount フィールドが含まれなくなりました。

FailureResourceCount 削除

以前の v1beta1 では、次のレスポンスに FailureResourceCount フィールドが含まれていました。

• DeidentifySummary
• DeidentifyErrorDetails
• DeidentifyDicomStoreSummary

新しい v1beta1 では、これらのレスポンスに FailureResourceCount フィールドは含まれなくなりました。代わりに、Cloud Healthcare API で匿名化に失敗したリソースを、長時間実行オペレーションレ スポンスの progress_counter.failure フィールドに表示できます。

DICOM の変更点

取引を検索

以前の v1beta1 では、検索は成功したもののクエリに一致する結果がなかった場合、検索トランザクションメソッドは 200 レスポンス コードを返していました。レスポンス本文には、空の結果の配列も含まれていました。

DICOM PS3.18 - Web サービス標準に合わせて、新しい v1beta1 の検索トランザクション メソッドは 200 レスポンス コードではなく 204 レスポンス コードを返します。空の結果の配列を返すのではなく、空のレスポンス本文が返されます。

DICOMweb の削除メソッド

以前の v1beta1 では、正常に実行されると次のメソッドは空のレスポンス コードを返していました。

• projects.locations.datasets.dicomStores.studies.delete
• projects.locations.datasets.dicomStores.studies.series.delete

新しい v1beta1 では、メソッドは長時間実行オペレーションを返します。削除が完了すると、長時間実行オペレーションに done: true が含まれます。

Cloud Storage レスポンスから DICOM データをインポートする

以前の v1beta1 では、projects.locations.datasets.dicomStores.import メソッドは Operation.error.status.details オブジェクトで ImportDicomDataErrorDetails を返しました。新しい v1beta1 では、このメソッドはエラーに対してこのレスポンスを返しません。その代わりに、Cloud Logging への Operation.metadata に URL が入力され、エラーの詳細を表示できます。

FHIR の変更

FHIR ストアの作成

FHIR ストアを作成するときは、そのストアの FHIR バージョン（DSTU2、STU3、または R4）を指定する必要があります。バージョンを指定しない場合、Cloud Healthcare API はエラーを返します。

例:

gcloud

次のサンプルは、FHIR ストアを作成する方法を示しています。

gcloud beta healthcare fhir-stores create FHIR_STORE_ID \
  --dataset=DATASET_ID \
  --location=LOCATION \
  --version={DSTU2|STU3|R4}

API

curl

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'version': 'FHIR_STORE_VERSION'
    }" "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID"

PowerShell

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

Invoke-WebRequest `
  -Method Post `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
      'version': 'FHIR_STORE_VERSION'
  }" `
  
  -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?fhirStoreId=FHIR_STORE_ID" | Select-Object -Expand Content

ImportResourcesResponse、ExportResourcesResponse、ImportResourcesErrorDetails、ExportResourcesErrorDetails

以前の v1beta1 では、projects.locations.datasets.fhirStores.import と projects.locations.datasets.fhirStores.export は ImportResourcesResponse と ExportResourcesResponse を含む長時間実行オペレーションをそれぞれ Operation.response フィールドで返しました。エラーが発生した場合、ImportResourcesErrorDetails または ExportResourcesErrorDetails が Operation.error フィールドで返されました。

新しい v1beta1 では、これらのレスポンスは Operation.metadata フィールドで成功と失敗の数として返されます。

BigQuery にエクスポートする場合のスキーマ

以前の v1beta1 では、FHIR リソースを BigQuery にエクスポートするときに、projects.locations.datasets.fhirStores.export メソッドで次のスキーマタイプを指定できました。

• SCHEMA_TYPE_UNSPECIFIED: スキーマタイプが指定されていません。LOSSLESS と同じ。
• LOSSLESS: エクスポートされる FHIR データに存在するフィールドから生成されたデータドリブン スキーマ。追加の簡略化はありません。
• ANALYTICS: FHIR コミュニティで定義されているアナリティクス スキーマ。https://github.com/FHIR/sql-on-fhir/blob/master/sql-on-fhir.md をご覧ください。

新しい v1beta1 では、SCHEMA_TYPE_UNSPECIFIED スキーマタイプが使用できなくなりました。SCHEMA_TYPE_UNSPECIFIED を指定するか、schemaType フィールドを設定しない場合、Cloud Healthcare API はエラーを返します。

場所の変更

projects.locations.get メソッドと projects.locations.list メソッドには、次の権限が必要になりました。

• locations.get: リクエストされたロケーションに対する healthcare.locations.get。
• locations.list: 親 Google Cloud プロジェクトに対する healthcare.locations.list。