Esta página foi traduzida pela API Cloud Translation.

Streaming de alterações de recursos FHIR para o BigQuery

Esta página explica como configurar um FHIR store para exportar automaticamente recursos FHIR para tabelas do BigQuery sempre que um recurso FHIR é criado, atualizado, corrigido ou eliminado. Este processo é denominado streaming do BigQuery.

Pode usar o streaming do BigQuery para fazer o seguinte:

Sincronize os dados num armazenamento FHIR com um conjunto de dados do BigQuery em tempo quase real.
Executar consultas complexas em dados FHIR sem ter de os exportar para o BigQuery sempre que quiser analisar os dados.

Para melhorar o desempenho das consultas e reduzir os custos, pode configurar o streaming do BigQuery para tabelas particionadas. Para ver instruções, consulte o artigo Transmita recursos FHIR para tabelas particionadas.

Antes de começar

Leia o artigo Exportar recursos FHIR para o BigQuery para compreender como funciona o processo de exportação.

Limitações

Se importar recursos FHIR do Cloud Storage, as alterações não são transmitidas para o BigQuery.

Definir autorizações do BigQuery

Para ativar o streaming do BigQuery, tem de conceder autorizações adicionais à conta de serviço do agente do serviço de saúde do Google Cloud . Para mais informações, consulte as autorizações do BigQuery da loja FHIR.

Configure o streaming do BigQuery numa loja FHIR

Para ativar o streaming do BigQuery, configure o objeto StreamConfigs na sua loja FHIR. Em StreamConfigs, pode configurar a matriz resourceTypes[] para controlar a que tipos de recursos FHIR o streaming do BigQuery se aplica. Se não especificar resourceTypes[], o streaming do BigQuery aplica-se a todos os tipos de recursos FHIR.

Para explicações de outras configurações disponíveis no StreamConfigs, como BigQueryDestination, consulte o artigo Exportar recursos FHIR.

Os exemplos seguintes mostram como ativar o streaming do BigQuery num FHIR store existente.

Consola

Para configurar o streaming do BigQuery numa loja FHIR existente através da Google Cloud consola, conclua os seguintes passos:

Na Google Cloud consola, aceda à página Conjuntos de dados.

Aceda aos conjuntos de dados
Selecione o conjunto de dados que contém o armazenamento FHIR que quer editar.
Na lista Armazenamentos de dados, clique no armazenamento FHIR que quer editar.
Na secção Streaming do BigQuery, conclua os seguintes passos:
1. Clique em Adicionar nova configuração de streaming.
2. Na secção Nova configuração de streaming, clique em Procurar para selecionar o conjunto de dados do BigQuery para o qual quer transmitir os recursos FHIR alterados.
3. No menu pendente Tipo de esquema, selecione o esquema de saída para a tabela do BigQuery. Estão disponíveis os seguintes esquemas:
  - Analytics. Um esquema baseado no documento SQL on FHIR. Uma vez que o BigQuery só permite 10 000 colunas por tabela, os esquemas não são gerados para os campos Parameters.parameter.resource, Bundle.entry.resource e Bundle.entry.response.outcome.
  - Analytics V2. Um esquema semelhante ao esquema do Analytics, com apoio técnico adicional para o seguinte:
    - Extensões com vários valores para o mesmo url
    - Recursos FHIR contidos
    O esquema do Analytics V2 usa mais espaço na tabela de destino do que o esquema do Analytics.
4. Selecione um nível de profundidade no controlo de deslize Profundidade da estrutura recursiva para definir a profundidade de todas as estruturas recursivas no esquema de saída. Por predefinição, o valor recursivo é 2.
5. Na lista Selecionar tipos de recursos FHIR, selecione os tipos de recursos para streaming.
Clique em Concluído para guardar a configuração de streaming.

gcloud

A CLI gcloud não suporta esta ação. Em alternativa, use a Google Cloud consolacurl, o PowerShell ou o seu idioma preferido.

REST

Para configurar o streaming do BigQuery num FHIR store existente, use o método projects.locations.datasets.fhirStores.patch.

Os seguintes exemplos não especificam a matriz resourceTypes[], pelo que o streaming do BigQuery está ativado para todos os tipos de recursos FHIR.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
LOCATION: a localização do conjunto de dados
DATASET_ID: o conjunto de dados principal do FHIR store
FHIR_STORE_ID: o ID da loja FHIR
BIGQUERY_DATASET_ID: o nome de um conjunto de dados do BigQuery existente para o qual está a fazer streaming de alterações de recursos FHIR
SCHEMA_TYPE: um valor para a enumeração SchemaType. Use um dos seguintes valores:
- ANALYTICS. Um esquema baseado no documento SQL on FHIR. Uma vez que o BigQuery só permite 10 000 colunas por tabela, os esquemas não são gerados para os campos Parameters.parameter.resource, Bundle.entry.resource e Bundle.entry.response.outcome.
- ANALYTICS_V2. Um esquema semelhante ao ANALYTICS com suporte adicional para o seguinte:
  - Extensões com vários valores para o mesmo url
  - Recursos FHIR contidos
  ANALYTICS_V2 usa mais espaço na tabela de destino do que ANALYTICS
  .
WRITE_DISPOSITION: um valor para a enumeração WriteDisposition. Use um dos seguintes valores:
- WRITE_EMPTY. Exporte dados apenas se as tabelas do BigQuery de destino estiverem vazias.
- WRITE_TRUNCATE. Apague todos os dados existentes nas tabelas do BigQuery antes de escrever os recursos FHIR.
- WRITE_APPEND. Anexar dados às tabelas do BigQuery de destino.

Corpo JSON do pedido:

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Nota: O comando seguinte pressupõe que tem sessão iniciada na CLI gcloud com a sua conta de utilizador executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que inicia automaticamente sessão na CLI gcloud. Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual:

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido REST:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs"

PowerShell

Nota: O comando seguinte pressupõe que iniciou sessão na CLI do Google Cloud com a sua conta de utilizador executando gcloud init ou gcloud auth login .gcloud Pode verificar a conta atualmente ativa executando o comando gcloud auth list.

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual:

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Em seguida, execute o seguinte comando para enviar o seu pedido REST:

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs" | Select-Object -Expand Content

Explorador de APIs

Copie o corpo do pedido e abra a página de referência do método. O painel APIs Explorer é aberto no lado direito da página. Pode interagir com esta ferramenta para enviar pedidos. Cole o corpo do pedido nesta ferramenta, preencha todos os outros campos obrigatórios e clique em Executar.

Deve receber uma resposta JSON semelhante à seguinte.

Se configurou campos no recurso FhirStore, estes também aparecem na resposta.

Resposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "FHIR_STORE_VERSION",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Por predefinição, quando transmite alterações de recursos FHIR para o BigQuery, é criada uma visualização de propriedade para cada recurso transmitido. A visualização de propriedade tem as seguintes propriedades:

Tem o mesmo nome que o recurso e a tabela do recurso no conjunto de dados do BigQuery. Por exemplo, quando transmite um recurso Patient, é criada uma tabela denominada Patient com uma vista denominada Patientview.
Contém apenas a versão atual do recurso, em vez de todas as versões do histórico.

Transmita recursos FHIR para tabelas particionadas

Para exportar recursos FHIR para tabelas particionadas do BigQuery, defina a enumeração TimePartitioning no campo lastUpdatedPartitionConfig na sua loja FHIR.

As tabelas particionadas funcionam como tabelas particionadas por unidade de tempo do BigQuery. As tabelas particionadas têm uma coluna adicionada denominada lastUpdated, que é uma duplicada da coluna meta.lastUpdated gerada a partir do campo meta.lastUpdated num recurso FHIR. O BigQuery usa a coluna lastUpdated para particionar tabelas por hora, dia, mês ou ano.

Consulte Selecione a partição diária, por hora, mensal ou anual para ver recomendações sobre como selecionar um nível de detalhe da partição.

Não é possível converter tabelas do BigQuery existentes não particionadas em tabelas particionadas. Se exportar alterações do recurso Patient para uma tabela Patients não particionada e, posteriormente, criar um novo FHIR store com a partição de tabelas que exporta para o mesmo conjunto de dados do BigQuery, a Cloud Healthcare API continua a exportar dados para a tabela Patients não particionada. Para começar a usar uma tabela particionada, elimine a tabela Patients existente ou use um conjunto de dados do BigQuery diferente.

Se adicionar a partição a uma configuração da loja FHIR existente, ainda pode exportar para tabelas não particionadas existentes. No entanto, a partição só entra em vigor em novas tabelas.

Os exemplos seguintes mostram como ativar o streaming do BigQuery para tabelas particionadas numa loja FHIR existente.

Consola

A consola Google Cloud e a CLI gcloud não suportam esta ação. Em alternativa, use curl, o PowerShell ou o seu idioma preferido.

gcloud

A consola Google Cloud e a CLI gcloud não suportam esta ação. Em alternativa, use curl, o PowerShell ou o seu idioma preferido.

REST

Para configurar o streaming do BigQuery para tabelas particionadas num repositório FHIR existente, use o método projects.locations.datasets.fhirStores.patch.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

PROJECT_ID: o ID do seu Google Cloud projeto
LOCATION: a localização do conjunto de dados
DATASET_ID: o conjunto de dados principal do FHIR store
FHIR_STORE_ID: o ID da loja FHIR
BIGQUERY_DATASET_ID: o nome de um conjunto de dados do BigQuery existente para o qual está a fazer streaming de alterações de recursos FHIR
SCHEMA_TYPE: um valor para a enumeração SchemaType. Use um dos seguintes valores:
- ANALYTICS. Um esquema baseado no documento SQL on FHIR. Uma vez que o BigQuery só permite 10 000 colunas por tabela, os esquemas não são gerados para os campos Parameters.parameter.resource, Bundle.entry.resource e Bundle.entry.response.outcome.
- ANALYTICS_V2. Um esquema semelhante ao ANALYTICS com suporte adicional para o seguinte:
  - Extensões com vários valores para o mesmo url
  - Recursos FHIR contidos
  ANALYTICS_V2 usa mais espaço na tabela de destino do que ANALYTICS
  .
TIME_PARTITION_TYPE: o nível de detalhe ao qual particionar os recursos FHIR exportados. Use um dos seguintes valores:
- HOUR: particione os dados por hora
- DAY: particione os dados por dia
- MONTH: particione os dados por mês
- YEAR: crie partições de dados por ano
WRITE_DISPOSITION: um valor para a enumeração WriteDisposition. Use um dos seguintes valores:
- WRITE_EMPTY. Exporte dados apenas se as tabelas do BigQuery de destino estiverem vazias.
- WRITE_TRUNCATE. Apague todos os dados existentes nas tabelas do BigQuery antes de escrever os recursos FHIR.
- WRITE_APPEND. Anexar dados às tabelas do BigQuery de destino.

Corpo JSON do pedido:

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual:

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
EOF

Em seguida, execute o seguinte comando para enviar o seu pedido REST:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs"

PowerShell

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual:

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Em seguida, execute o seguinte comando para enviar o seu pedido REST:

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

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs" | Select-Object -Expand Content

Explorador de APIs

Deve receber uma resposta JSON semelhante à seguinte:

Resposta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "FHIR_STORE_VERSION",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Consulte uma tabela particionada

Para reduzir os custos de consulta ao consultar tabelas particionadas, use a cláusula WHERE para filtrar por unidades de tempo.

Por exemplo, suponha que define a enumeração PartitionType como DAY. Para consultar uma tabela Patients para recursos de pacientes que foram alterados numa data específica, execute a seguinte consulta:

SELECT * FROM `PROJECT_ID.BIGQUERY_DATASET.Patients`
  WHERE DATE(lastUpdated) = 'YYYY-MM-DD'

Migre do Analytics para o Analytics V2

Não pode migrar um conjunto de dados do BigQuery existente do esquema Analytics para o esquema Analytics V2 através de qualquer método, incluindo o seguinte:

Alterar o tipo de esquema da tabela no BigQuery.
Alterar o tipo de esquema numa configuração de streaming FHIR existente.

Isto deve-se ao facto de as colunas da tabela do BigQuery para as extensões FHIR no esquema Analytics terem o respetivo modo definido como NULLABLE, enquanto as do esquema Analytics V2 terem o respetivo modo definido como REPEATED. O BigQuery não permite alterar o modo de uma coluna de NULLABLE para REPEATED. Por conseguinte, os dois tipos de esquemas são incompatíveis.

Para migrar o tipo de esquema dos recursos FHIR exportados de Analytics para Analytics V2, tem de exportar os recursos FHIR para um novo conjunto de dados do BigQuery usando uma nova configuração de streaming com o tipo de esquema atualizado. Para tal, siga os seguintes passos:

Crie um novo conjunto de dados do BigQuery.
Defina autorizações para o conjunto de dados do BigQuery.
Adicione uma nova configuração de streaming à FHIR store com o tipo de esquema definido como Analytics V2.
Preencha os dados existentes exportando os dados FHIR existentes com as seguintes definições. Consulte o artigo sobre a exportação de recursos FHIR para ver instruções sobre como configurar estas definições através da Google Cloud consola, da Google Cloud CLI ou da API REST. As seguintes definições aplicam-se à API REST:
- Defina WriteDisposition como WRITE_APPEND para anexar os dados à tabela de destino.
- Definir SchemaType para ANALYTICS_V2.

As vistas no BigQuery que correspondem a alguns ou a todos os recursos FHIR no conjunto de dados do BigQuery original podem estar em falta no seu novo conjunto de dados. Para resolver este problema, consulte o artigo Criação de vistas de recursos FHIR em falta.

Resolução de problemas de streaming FHIR

Se ocorrerem erros quando as alterações de recursos são enviadas para o BigQuery, os erros são registados no Cloud Logging. Para mais informações, consulte o artigo Ver registos de erros nos Registos na nuvem.

Não é possível converter a coluna de NULLABLE para REPEATED

Este erro é causado por uma extensão repetida. Para resolver este erro, use o tipo de esquema ANALYTICS_V2. Se já estiver a usar ANALYTICS_V2, pode ter um conflito entre duas extensões ou um conflito entre uma extensão e outro campo.

Os nomes das colunas são gerados a partir do texto após o último caráter / nos URLs das extensões. Se um URL de extensão terminar com um valor como /resource_field name, pode ocorrer um conflito.

Para evitar que este erro ocorra novamente, não use extensões se os respetivos nomes dos campos forem iguais aos campos de recursos que está a preencher.

Criação de vista de recursos FHIR em falta

Se exportar em massa um recurso FHIR para o BigQuery antes de fazer o streaming desse recurso FHIR, o BigQuery não cria visualizações de propriedade para o recurso FHIR.

Por exemplo, pode não ver visualizações de recursos Encounter na seguinte situação:

Configura o streaming do BigQuery numa loja FHIR e, em seguida, usa a API REST para criar um recurso Patient.

O BigQuery cria uma tabela e uma vista para o recurso Patient.
Exporte em massa recursos Encounter para o mesmo conjunto de dados do BigQuery que no passo anterior.

O BigQuery cria uma tabela para os recursos Encounter.
Usa a API REST para criar um recurso Encounter.

Após este passo, não são criadas visualizações de propriedade do BigQuery para o recurso Encounter.

Para resolver este problema, use a seguinte consulta para criar uma vista:

SELECT
    * EXCEPT (_resource_row_id)
FROM (
  SELECT
    ROW_NUMBER() OVER(PARTITION BY id ORDER BY meta.lastUpdated DESC, commitTimestamp DESC) as _resource_row_id,
    *
    FROM `PROJECT_ID.BIGQUERY_DATASET_ID.RESOURCE_TABLE` AS p
) AS p
WHERE
  p._resource_row_id=1
  AND
  NOT EXISTS (
  SELECT
    *
  FROM
    UNNEST(p.meta.tag)
  WHERE
    code = 'DELETE');

Substitua o seguinte:

PROJECT_ID: o ID do seu Google Cloud projeto
BIGQUERY_DATASET_ID: o ID do conjunto de dados do BigQuery para o qual exportou em massa o recurso FHIR
RESOURCE_TABLE: o nome da tabela correspondente ao recurso FHIR para o qual quer criar vistas

Depois de criar a visualização de propriedade, pode continuar a transmitir alterações ao recurso FHIR e a visualização de propriedade é atualizada em conformidade.

O que se segue?

Para um tutorial sobre um exemplo de utilização para o streaming de alterações de recursos FHIR, consulte o artigo Faça o streaming e sincronize recursos FHIR com o BigQuery.

Streaming de alterações de recursos FHIR para o BigQuery Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Limitações

Definir autorizações do BigQuery

Configure o streaming do BigQuery numa loja FHIR

Consola

gcloud

REST

curl

PowerShell

Explorador de APIs

Resposta

Transmita recursos FHIR para tabelas particionadas

Consola

gcloud

REST

curl

PowerShell

Explorador de APIs

Resposta

Consulte uma tabela particionada

Migre do Analytics para o Analytics V2

Resolução de problemas de streaming FHIR

Não é possível converter a coluna de NULLABLE para REPEATED

Criação de vista de recursos FHIR em falta

O que se segue?

Streaming de alterações de recursos FHIR para o BigQuery