使用資源標籤

本頁說明如何新增、查看、編輯及移除 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 使用標籤。