使用資源標籤

本頁說明如何在 Cloud Healthcare API 資源上新增、查看、編輯及移除標籤。標籤是鍵/值組合，可用來整理資源。您可以為個別資源加上標籤，然後根據標籤篩選資源。標籤的相關資訊會轉送至帳單系統，因此您可以依據標籤查看帳單費用明細。

您可以將標籤與下列 Cloud Healthcare API 資源搭配使用：

  • FHIR 儲存庫
  • DICOM 儲存庫
  • 同意聲明儲存庫
  • HL7v2 儲存庫
  • HL7v2 訊息

您可以使用 REST 或 RPC API 使用標籤。Google Cloud CLI 或 Google Cloud 控制台不支援標籤。

標籤規定

套用於資源的標籤必須符合下列規定：

  • 每項資源可以有多個標籤，上限為 64 個。
  • 每個標籤都必須是鍵/值組合。
  • 鍵的長度必須至少為 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。第二個標籤的鍵為 team，值為 research。

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_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 儲存庫的名稱
  • 要更新的標籤資料，以以逗號分隔的鍵/值組合清單形式呈現
  • 更新遮罩設為 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"
      }
    },
    {
      ...
    }
  ]
}

移除標籤

您可以透過下列任一方式移除標籤：

  • 如要完全移除標籤，也就是移除鍵和值，請使用讀取-修改-寫入模式，完成下列步驟：

    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 的標籤的其他用途。