Usar etiquetas de recursos

Esta página mostra como adicionar, ver, editar e remover etiquetas em recursos da Cloud Healthcare API. As etiquetas são pares de chave-valor que pode usar para organizar recursos. Pode anexar uma etiqueta a recursos individuais e, em seguida, filtrar os recursos com base nas respetivas etiquetas. As informações sobre as etiquetas são encaminhadas para o sistema de faturação, para que possa discriminá-las por etiqueta.

Pode usar etiquetas com os seguintes recursos da Cloud Healthcare API:

  • Armazenamentos FHIR
  • DICOM stores
  • Lojas de consentimento
  • Armazenamentos de HL7v2
  • Mensagens HL7v2

As etiquetas estão disponíveis através das APIs REST ou RPC. As etiquetas não estão disponíveis na CLI gcloud nem na Google Cloud consola.

Requisitos de etiquetas

As etiquetas aplicadas a um recurso têm de cumprir os seguintes requisitos:

  • Cada recurso pode ter várias etiquetas, até um máximo de 64.
  • Cada etiqueta tem de ser um par chave-valor.
  • As chaves têm um comprimento mínimo de 1 caráter e um comprimento máximo de 63 carateres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 carateres.
  • As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8 e são permitidos carateres internacionais.
  • A chave de uma etiqueta tem de ser exclusiva num único recurso, mas pode usar a mesma chave com vários recursos.
  • As chaves têm de começar com uma letra minúscula ou um caráter internacional.

Adicionar uma etiqueta

O exemplo seguinte mostra como adicionar uma etiqueta a um FHIR store existente.

Por exemplo, pode usar a etiqueta para indicar que o FHIR store está a ser usado como um ambiente de teste. A chave da etiqueta seria environment e o valor seria test.

curl

Para adicionar uma etiqueta a um arquivo FHIR existente, faça um pedido PATCH e especifique as seguintes informações:

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Os dados da etiqueta a atualizar
  • Uma máscara de atualização definida como labels
  • Uma chave de acesso

O exemplo seguinte mostra um pedido PATCH através de curl.

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"

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

PowerShell

Para adicionar uma etiqueta a um arquivo FHIR existente, faça um pedido PATCH e especifique as seguintes informações:

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Os dados da etiqueta a atualizar
  • Uma máscara de atualização definida como labels
  • Uma chave de acesso

O exemplo seguinte mostra um pedido PATCH através do Windows PowerShell.

$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

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

Adicionar várias etiquetas

O exemplo seguinte mostra como adicionar várias etiquetas a um arquivo FHIR existente. Para adicionar várias etiquetas, separe cada etiqueta com uma vírgula.

Por exemplo, pode usar as etiquetas para indicar que o FHIR store está a ser usado como um ambiente de teste e que é usado para uma equipa de investigação.

A chave da primeira etiqueta seria environment e o valor seria test. A chave da segunda etiqueta seria team e o valor seria research.

curl

Para adicionar várias etiquetas a um arquivo FHIR existente, faça um pedido PATCH e especifique as seguintes informações:

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Os dados da etiqueta a atualizar como uma lista de pares de chave/valor delimitada por vírgulas
  • Uma máscara de atualização definida como labels
  • Uma chave de acesso

O exemplo seguinte mostra um pedido PATCH através de curl.

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"

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

PowerShell

Para adicionar uma etiqueta a um arquivo FHIR existente, faça um pedido PATCH e especifique as seguintes informações:

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Os dados da etiqueta a atualizar como uma lista de pares de chave/valor delimitada por vírgulas
  • Uma máscara de atualização definida como labels
  • Uma chave de acesso

O exemplo seguinte mostra um pedido PATCH através do Windows PowerShell.

$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

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

Listagem e filtragem por etiquetas

Depois de adicionar uma etiqueta a um recurso da API Cloud Healthcare, pode listar recursos e filtrá-los pelas respetivas etiquetas. Por exemplo, depois de adicionar uma etiqueta a uma loja FHIR nos exemplos anteriores, pode listar as lojas FHIR no seu conjunto de dados e filtrar pelas etiquetas que adicionou.

As mensagens HL7v2 têm opções de filtragem adicionais que pode ver em projects.locations.datasets.hl7V2Stores.messages.list.

curl

Para ver os armazenamentos de FHIR num conjunto de dados e filtrá-los por uma etiqueta, faça um pedido e faculte as seguintes informações:GET

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Uma string de consulta que contém as informações pelas quais filtrar
  • Uma chave de acesso

O exemplo seguinte mostra um pedido GET através de curl.

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"

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

PowerShell

Para ver os armazenamentos de FHIR num conjunto de dados e filtrá-los por uma etiqueta, faça um pedido e faculte as seguintes informações:GET

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Uma string de consulta que contém as informações pelas quais filtrar
  • Uma chave de acesso

O exemplo seguinte mostra um pedido GET através do Windows PowerShell.

$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

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

Remover uma etiqueta

Pode remover uma etiqueta de duas formas:

  • Para remover completamente a etiqueta, o que significa que a chave e o valor são removidos, use o padrão de leitura-modificação-escrita seguindo estes passos:

    1. Leia as etiquetas atuais chamando o método get() do recurso.
    2. Edite as etiquetas devolvidas, através de um editor de texto ou programaticamente, para adicionar ou remover quaisquer chaves aplicáveis e os respetivos valores.
    3. Escreva as etiquetas atualizadas chamando o método patch() do recurso.

  • Para manter a chave e remover o valor, defina o valor como null.

curl

O exemplo seguinte mostra como remover uma etiqueta definindo o valor da etiqueta como null.

Para remover uma etiqueta de uma loja FHIR existente, faça um pedido PATCH e especifique as seguintes informações:

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Os dados da etiqueta a atualizar
  • Uma máscara de atualização definida como labels
  • Uma chave de acesso

O exemplo seguinte mostra um pedido PATCH através de curl.

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"

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

PowerShell

O exemplo seguinte mostra como remover uma etiqueta definindo o valor da etiqueta como null.

Para remover uma etiqueta de uma loja FHIR existente, faça um pedido PATCH e especifique as seguintes informações:

  • O nome do conjunto de dados principal
  • O nome do FHIR store
  • Os dados da etiqueta a atualizar
  • Uma máscara de atualização definida como labels
  • Uma chave de acesso

O exemplo seguinte mostra um pedido PATCH através do Windows 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 "{
      '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

Se o pedido for bem-sucedido, o servidor devolve a resposta no formato JSON:

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

O que se segue?

Leia acerca de outras utilizações de etiquetas com a API Cloud Resource Manager.