リソースラベルの使用

このページでは、Cloud Healthcare API リソースでラベルを追加、表示、編集、削除する方法について説明します。ラベルは、リソースの整理に使用できる Key-Value ペアです。個々のリソースにララベルを設定し、そのラベルに基づいてリソースをフィルタリングできます。ラベルに関する情報は課金システムに転送されるため、ラベルを基準に請求料金を分析することもできます。

次の Cloud Healthcare API リソースでラベルを使用できます。

FHIR ストア
DICOM ストア
Consent Store
HL7v2 ストア
HL7v2 メッセージ

ラベルは REST API または RPC API によって使用できます。ラベルは Google Cloud CLI や Google Cloud コンソールでは使用できません。

ラベルの要件

リソースに適用するラベルは、次の要件を満たす必要があります。

1 つのリソースには、最大 64 個のラベルを適用できます。
ラベルは、Key-Value ペアでなければなりません。
キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。
ラベルのキーは単一のリソース内で一意であることが必要ですが、同じキーを複数のリソースで使用できます。
キーは、小文字または国際文字で始める必要があります。

ラベルを追加する

次のサンプルは、既存の FHIR ストアにラベルを追加する方法を示しています。

たとえば、ラベルを使用して、FHIR ストアがテスト環境として使用されていることを示すことができます。ラベルのキーは environment で、値は test です。

curl

既存の FHIR ストアにラベルを追加するには、PATCH リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
更新するラベルデータ
labels に設定された更新マスク
アクセストークン

次のサンプルは、curl を使用した PATCH リクエストを示しています。

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

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "labels": {
    "KEY": "VALUE"
  }
}

PowerShell

既存の FHIR ストアにラベルを追加するには、PATCH リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
更新するラベルデータ
labels に設定された更新マスク
アクセストークン

次のサンプルは、Windows PowerShell を使用した PATCH リクエストを示しています。

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

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
      'labels': {
        'KEY': 'VALUE'
      }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=labels" | Select-Object -Expand Content

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "labels": {
    "KEY": "VALUE"
  }
}

複数のラベルを追加する

次のサンプルは、既存の FHIR ストアに複数のラベルを追加する方法を示しています。複数のラベルを追加する場合は、各ラベルをカンマで区切ります。

たとえば、FHIR ストアがテスト環境として使用されていること、および調査チームに使用されていることを示すために、ラベルを使用できます。

最初のラベルのキーは environment で、値は test です。 2 番目のラベルのキーは team で、値は research です。

curl

既存の FHIR ストアに複数のラベルを追加するには、PATCH リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
更新するラベルデータ（Key-Value ペアのカンマ区切りリスト）
labels に設定された更新マスク
アクセストークン

次のサンプルは、curl を使用した PATCH リクエストを示しています。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data "{
      'labels': {
        'KEY_1' : 'VALUE_1',
        'KEY_2' : 'VALUE_2'
      }
     }" "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=labels"

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "labels": {
    "KEY_1": "VALUE_1",
    "KEY_2": "VALUE_2"
  }
}

PowerShell

既存の FHIR ストアにラベルを追加するには、PATCH リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
更新するラベルデータ（Key-Value ペアのカンマ区切りリスト）
labels に設定された更新マスク
アクセストークン

次のサンプルは、Windows PowerShell を使用した PATCH リクエストを示しています。

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

Invoke-WebRequest `
  -Method Patch `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body "{
      'labels': {
        'KEY_1': 'VALUE_1',
        'KEY_2': 'VALUE_2'
      }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=labels" | Select-Object -Expand Content

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "labels": {
    "KEY_1": "VALUE_1",
    "KEY_2": "VALUE_2"
  }
}

ラベルによる一覧表示とフィルタリング

Cloud Healthcare API リソースにラベルを追加すると、リソースを一覧表示して、そのラベルでフィルタリングできます。たとえば、上記のサンプルの FHIR ストアにラベルを追加すると、データセット内の FHIR ストアを一覧表示して、追加したラベルでフィルタリングできます。

HL7v2 メッセージには、projects.locations.datasets.hl7V2Stores.messages.list で表示できる追加のフィルタリングオプションがあります。

curl

データセット内の FHIR ストアを表示してラベルでフィルタリングするには、GET リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
フィルタリングに使用する情報を含むクエリ文字列
アクセストークン

次のサンプルは、curl を使用した GET リクエストを示しています。

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores?filter=labels.KEY=VALUE"

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "fhirStores": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "labels": {
        "KEY": "VALUE"
      }
    },
    {
      ...
    }
  ]
}

PowerShell

データセット内の FHIR ストアを表示してラベルでフィルタリングするには、GET リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
フィルタリングに使用する情報を含むクエリ文字列
アクセストークン

次のサンプルは、Windows PowerShell を使用した GET リクエストを示しています。

$cred = gcloud auth application-default 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/fhirStores?filter=labels.KEY=VALUE" | Select-Object -Expand Content

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "fhirStores": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
      "labels": {
        "KEY": "VALUE"
      }
    },
    {
      ...
    }
  ]
}

ラベルの削除

ラベルは次の 2つの方法のいずれかで削除できます。

ラベルを完全に削除する、すなわちキーと値の両方を削除するには、次の手順で読み取り - 変更 - 書き込みのパターンを使用します。
1. リソースの get() メソッドを呼び出して、現在のラベルを読み取ります。
2. 返されたラベルを、テキストエディタを使用するかプログラムで編集して、該当するキーと値を追加または削除します。
3. リソースの patch() メソッドを呼び出して、更新されたラベルを書き込みます。
キーを保持して値を削除するには、値を null に設定します。

curl

次のサンプルは、ラベルの値を null に設定してラベルを削除する方法を示しています。

既存の FHIR ストアからラベルを削除するには、PATCH リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
更新するラベルデータ
labels に設定された更新マスク
アクセストークン

次のサンプルは、curl を使用した PATCH リクエストを示しています。

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

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "labels": {
    "KEY":
  }
}

PowerShell

次のサンプルは、ラベルの値を null に設定してラベルを削除する方法を示しています。

既存の FHIR ストアからラベルを削除するには、PATCH リクエストを行い、次の情報を指定します。

親データセットの名前
FHIR ストアの名前
更新するラベルデータ
labels に設定された更新マスク
アクセストークン

次のサンプルは、Windows PowerShell を使用した PATCH リクエストを示しています。

$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 "{
      'labels': {
        'KEY': nullresource_manager_api
      }
  }" `
  -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=labels" | Select-Object -Expand Content

リクエストが成功すると、サーバーは JSON 形式のレスポンスを返します。

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "labels": {
    "KEY":
  }
}

次のステップ

Cloud Resource Manager API を使用したラベルのその他の使用について確認する。