Importe dados de bases de dados que não sejam do Spanner

Esta página descreve como preparar ficheiros Avro que exportou de bases de dados não pertencentes ao Spanner e, em seguida, importar esses ficheiros para o Spanner. Estes procedimentos incluem informações para bases de dados com dialeto GoogleSQL e bases de dados com dialeto PostgreSQL. Se quiser importar uma base de dados do Spanner que exportou anteriormente, consulte o artigo Importar ficheiros Avro do Spanner.

O processo usa o Dataflow; importa dados de um contentor do Cloud Storage que contém um conjunto de ficheiros Avro e um ficheiro de manifesto JSON que especifica as tabelas de destino e os ficheiros Avro que preenchem cada tabela.

Antes de começar

Para importar uma base de dados do Spanner, primeiro, tem de ativar as APIs Spanner, Cloud Storage, Compute Engine e Dataflow:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Também precisa de quota suficiente e das autorizações de IAM necessárias.

Requisitos de quota

Os requisitos de quota para tarefas de importação são os seguintes:

• Spanner: tem de ter capacidade de computação suficiente para suportar a quantidade de dados que está a importar. Não é necessária capacidade de computação adicional para importar uma base de dados, embora possa ter de adicionar mais capacidade de computação para que a tarefa termine num período razoável. Consulte o artigo Otimize tarefas para ver mais detalhes.
• Cloud Storage: para importar, tem de ter um contentor com os ficheiros exportados anteriormente. Não precisa de definir um tamanho para o seu contentor.
• Dataflow: as tarefas de importação estão sujeitas às mesmas quotas de CPU, utilização de disco e endereço IP do Compute Engine que outras tarefas do Dataflow.

• Compute Engine: antes de executar a tarefa de importação, tem de configurar as quotas iniciais para o Compute Engine, que o Dataflow usa. Estas quotas representam o número máximo de recursos que permite que o Dataflow use para a sua tarefa. Os valores iniciais recomendados são:

  • CPUs: 200
  • Endereços IP em utilização: 200
  • Disco persistente padrão: 50 TB

  Geralmente, não tem de fazer outros ajustes. O Dataflow oferece o dimensionamento automático para que só pague pelos recursos reais usados durante a importação. Se o seu trabalho puder usar mais recursos, a IU do Dataflow apresenta um ícone de aviso. A tarefa deve terminar mesmo que exista um ícone de aviso.

Funções necessárias

Para receber as autorizações de que precisa para exportar uma base de dados, peça ao seu administrador para lhe conceder as seguintes funções do IAM na conta de serviço do trabalhador do Dataflow:

• Visitante do Cloud Spanner (roles/spanner.viewer)
• Dataflow Worker (roles/dataflow.worker)
• Administrador de armazenamento (roles/storage.admin)
• Leitor da base de dados do Spanner (roles/spanner.databaseReader)
• Administrador da base de dados (roles/spanner.databaseAdmin)

Nota: a função de administrador da base de dados do Spanner só é necessária para tarefas de importação.

Exporte dados de uma base de dados não pertencente ao Spanner para ficheiros Avro

O processo de importação transfere dados de ficheiros Avro localizados num contentor do Cloud Storage. Pode exportar dados no formato Avro de qualquer origem e usar qualquer método disponível para o fazer.

Para exportar dados de uma base de dados não pertencente ao Spanner para ficheiros Avro, siga estes passos:

Tenha em atenção o seguinte quando exportar os seus dados:

• Pode exportar usando qualquer um dos tipos primitivos do Avro, bem como o tipo complexo array.

• Cada coluna nos seus ficheiros Avro tem de usar um dos seguintes tipos de colunas:

  • ARRAY
  • BOOL
  • BYTES^*
  • DOUBLE
  • FLOAT
  • INT
  • LONG^†
  • STRING^‡

  ^* Uma coluna do tipo BYTES é usada para importar um Spanner NUMERIC; consulte a secção mapeamentos recomendados seguinte para ver detalhes.

  ^†,‡ Pode importar um LONG que armazene uma data/hora ou um STRING que armazene uma data/hora como um Spanner TIMESTAMP. Consulte a secção de mapeamentos recomendados abaixo para ver detalhes.

• Não tem de incluir nem gerar metadados quando exporta os ficheiros Avro.

• Não tem de seguir nenhuma convenção de nomenclatura específica para os seus ficheiros.

Se não exportar os ficheiros diretamente para o Cloud Storage, tem de carregar os ficheiros Avro para um contentor do Cloud Storage. Para ver instruções detalhadas, consulte o artigo Carregue objetos para o Cloud Storage.

Importe ficheiros Avro de bases de dados não pertencentes ao Spanner para o Spanner

Para importar ficheiros Avro de uma base de dados que não seja do Spanner para o Spanner, siga estes passos:

1. Crie tabelas de destino e defina o esquema da sua base de dados do Spanner.
2. Crie um ficheiro spanner-export.json no seu contentor do Cloud Storage.
3. Execute uma tarefa de importação do Dataflow através da CLI gcloud.

Passo 1: crie o esquema da base de dados do Spanner

Antes de executar a importação, tem de criar a tabela de destino no Spanner e definir o respetivo esquema.

Tem de criar um esquema que use o tipo de coluna adequado para cada coluna nos ficheiros Avro.

Mapeamentos recomendados

GoogleSQL

Tipo de coluna Avro	Tipo de coluna do Spanner
ARRAY	ARRAY
BOOL	BOOL
BYTES	BYTES NUMERIC (quando o tipo de coluna é BYTES e logicalType=decimal, precision=38 e scale=9. Se estas especificações exatas forem omitidas, o campo é tratado como um valor do Spanner BYTES. Para mais informações, consulte a documentação sobre o tipo lógico decimal Avro.)
DOUBLE	FLOAT64
FLOAT	FLOAT64
INT	INT64
LONG	INT64 TIMESTAMP quando LONG representa uma data/hora do número de microssegundos desde 01/01/1970 às 00:00:00 UTC
STRING	STRING TIMESTAMP quando STRING representa uma data/hora no formato canónico para consultas SQL

PostgreSQL

Tipo de coluna Avro	Tipo de coluna do Spanner
ARRAY	ARRAY
BOOL	BOOLEAN
BYTES	BYTEA NUMERIC (quando o tipo de coluna é BYTEA e logicalType=decimal, precision=147455 e scale=16383. Se estas especificações exatas forem omitidas, o campo é tratado como um valor BYTEA. Para mais informações, consulte a documentação sobre o tipo lógico decimal Avro.)
DOUBLE	DOUBLE PRECISION
FLOAT	DOUBLE PRECISION
INT	BIGINT
LONG	BIGINT TIMESTAMP quando LONG representa uma data/hora do número de microssegundos desde 01/01/1970 às 00:00:00 UTC
STRING	CHARACTER VARYING TIMESTAMP quando STRING representa uma data/hora no formato canónico para consultas SQL, por exemplo, "2022-05-28T07:08:21.123456789Z" ou "2021-12-19T16:39:57-08:00".

Nota: se uma coluna nos seus dados Avro contiver valores NULL, tem de garantir que torna a coluna correspondente na sua tabela do Spanner anulável.

Passo 2: crie um ficheiro spanner-export.json

Também tem de criar um ficheiro com o nome spanner-export.json no contentor do Cloud Storage. Este ficheiro especifica o dialeto da base de dados e contém uma matriz tables que indica os nomes e as localizações dos ficheiros de dados de cada tabela.

O conteúdo do ficheiro tem o seguinte formato:

{
  "tables": [
   {
    "name": "TABLE1",
    "dataFiles": [
      "RELATIVE/PATH/TO/TABLE1_FILE1",
      "RELATIVE/PATH/TO/TABLE1_FILE2"
    ]
   },
   {
    "name": "TABLE2",
    "dataFiles": ["RELATIVE/PATH/TO/TABLE2_FILE1"]
   }
  ],
  "dialect":"DATABASE_DIALECT"
}

Em que DATABASE_DIALECT = {GOOGLE_STANDARD_SQL | POSTGRESQL}

Se o elemento dialect for omitido, o dialect tem a predefinição GOOGLE_STANDARD_SQL.

Nota: os carateres universais não são suportados. Tem de escrever todos os nomes de ficheiros na íntegra.

Passo 3: execute uma tarefa de importação do Dataflow através da CLI gcloud

Para iniciar a tarefa de importação, siga as instruções para usar a CLI do Google Cloud para executar uma tarefa com o modelo Avro para Spanner.

Depois de iniciar uma tarefa de importação, pode ver detalhes sobre a tarefa na consola. Google Cloud

Após a conclusão da tarefa de importação, adicione os índices secundários e as chaves externas necessários.

Nota: para evitar custos de transferência de dados de saída, escolha uma região que se sobreponha à localização do seu contentor do Cloud Storage. Para mais informações, consulte Escolha uma região.

Nota: a tarefa do Dataflow não resolve tabelas intercaladas nem restrições de chaves externas, pelo que pode ter erros de escrita devido a violações da integridade referencial. Remova todas as relações de intercalação ou chaves externas antes de iniciar a tarefa do Dataflow.

Escolha uma região para a tarefa de importação

Recomendamos que escolha uma região diferente com base na localização do seu contentor do Cloud Storage. Para evitar custos de transferência de dados de saída, escolha uma região que corresponda à localização do seu contentor do Cloud Storage.

• Se a localização do seu contentor do Cloud Storage for uma região, pode tirar partido da utilização da rede sem custo financeiro escolhendo a mesma região para a sua tarefa de importação, desde que essa região esteja disponível.

• Se a localização do seu contentor do Cloud Storage for uma região dupla, pode tirar partido da utilização da rede gratuita escolhendo uma das duas regiões que compõem a região dupla para a sua tarefa de importação, partindo do princípio de que uma das regiões está disponível.

• Se não estiver disponível uma região de colocação conjunta para a sua tarefa de importação ou se a localização do contentor do Cloud Storage for uma multirregião, aplicam-se custos de transferência de dados de saída. Consulte os preços de transferência de dados do Cloud Storage para escolher uma região que incorra nos custos de transferência de dados mais baixos.

Veja ou resolva problemas de tarefas na IU do Dataflow

Depois de iniciar uma tarefa de importação, pode ver os detalhes da tarefa, incluindo registos, na secção Dataflow da Google Cloud consola.

Veja os detalhes das tarefas do Dataflow

Para ver os detalhes de todas as tarefas de importação ou exportação que executou na última semana, incluindo as tarefas que estão a ser executadas agora:

1. Navegue para a página Vista geral da base de dados da base de dados.
2. Clique no item de menu do painel esquerdo Importar/Exportar. A página Importar/Exportar da base de dados apresenta uma lista de tarefas recentes.

3. Na página Importar/Exportar da base de dados, clique no nome da tarefa na coluna Nome da tarefa do Dataflow:

   

   A Google Cloud consola apresenta detalhes da tarefa do Dataflow.

Para ver uma tarefa que executou há mais de uma semana:

1. Aceda à página de tarefas do Dataflow na Google Cloud consola.

   Aceda a Empregos

2. Encontre o seu trabalho na lista e, de seguida, clique no respetivo nome.

   A Google Cloud consola apresenta detalhes da tarefa do Dataflow.

Nota: os trabalhos do mesmo tipo para a mesma base de dados têm o mesmo nome. Pode distinguir as tarefas pelos valores nas colunas Hora de início ou Hora de fim.

Veja os registos do Dataflow para a sua tarefa

Para ver os registos de uma tarefa do Dataflow, navegue para a página de detalhes da tarefa e, de seguida, clique em Registos à direita do nome da tarefa.

Se uma tarefa falhar, procure erros nos registos. Se existirem erros, a quantidade de erros é apresentada junto a Registos:

Para ver erros de tarefas:

1. Clique na contagem de erros junto a Registos.

   A Google Cloud consola apresenta os registos da tarefa. Pode ter de deslocar a página para ver os erros.

2. Localize as entradas com o ícone de erro .

3. Clique numa entrada de registo individual para expandir o respetivo conteúdo.

Para mais informações sobre a resolução de problemas de tarefas do Dataflow, consulte o artigo Resolva problemas do seu pipeline.

Resolva problemas de tarefas de importação com falhas

Se vir os seguintes erros nos registos de tarefas:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Verifique a latência de escrita de 99% no separador Monitorização da sua base de dados do Spanner na Google Cloud consola. Se estiver a apresentar valores elevados (vários segundos), significa que a instância está sobrecarregada, o que faz com que as gravações excedam o limite de tempo e falhem.

Uma das causas da latência elevada é o facto de a tarefa do Dataflow estar a ser executada com demasiados trabalhadores, o que coloca uma carga excessiva na instância do Spanner.

Para especificar um limite no número de trabalhadores do Dataflow, em vez de usar o separador Importar/Exportar na página de detalhes da instância da base de dados do Spanner na consola do Google Cloud , tem de iniciar a importação através domodelo do Cloud Storage Avro para o Spanner e especificar o número máximo de trabalhadores da seguinte forma:

Consola

Se estiver a usar a consola do Dataflow, o parâmetro Max workers está localizado na secção Parâmetros opcionais da página Criar tarefa a partir de um modelo.

Aceda ao Dataflow

gcloud

Execute o comando gcloud dataflow jobs run e especifique o argumento max-workers. Por exemplo:

  gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Resolva problemas de erro de rede

Pode ocorrer o seguinte erro quando exporta as suas bases de dados do Spanner:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Este erro ocorre porque o Spanner assume que pretende usar uma rede VPC no modo automático denominada default no mesmo projeto que a tarefa do Dataflow. Se não tiver uma rede VPC predefinida no projeto ou se a sua rede VPC estiver numa rede VPC de modo personalizado, tem de criar uma tarefa do Dataflow e especificar uma rede ou uma sub-rede alternativa.

Otimize tarefas de importação de execução lenta

Se seguiu as sugestões nas definições iniciais, geralmente, não tem de fazer outros ajustes. Se o seu trabalho estiver a ser executado lentamente, existem algumas outras otimizações que pode experimentar:

• Otimize a tarefa e a localização dos dados: execute a tarefa do Dataflow na mesma região onde se encontram a instância do Spanner e o contentor do Cloud Storage.

• Garanta recursos suficientes do Dataflow: se as quotas relevantes do Compute Engine limitarem os recursos da tarefa do Dataflow, a página do Dataflow na Google Cloud consola apresenta um ícone de aviso e mensagens de registo:

  

  Nesta situação, aumentar as quotas para CPUs, endereços IP em utilização e disco persistente padrão pode reduzir o tempo de execução da tarefa, mas pode incorrer em mais encargos do Compute Engine.

• Verifique a utilização da CPU do Spanner: se verificar que a utilização da CPU da instância é superior a 65%, pode aumentar a capacidade de computação nessa instância. A capacidade adiciona mais recursos do Spanner e o trabalho deve acelerar, mas incorre em mais encargos do Spanner.

Fatores que afetam o desempenho da tarefa de importação

Vários fatores influenciam o tempo necessário para concluir uma tarefa de importação.

• Tamanho da base de dados do Spanner: o processamento de mais dados demora mais tempo e requer mais recursos.

• Esquema da base de dados do Spanner, incluindo:

  • O número de tabelas
  • O tamanho das linhas
  • O número de índices secundários
  • O número de chaves externas
  • O número de streams de alterações

• Localização dos dados: os dados são transferidos entre o Spanner e o Cloud Storage através do Dataflow. Idealmente, todos os três componentes estão localizados na mesma região. Se os componentes não estiverem na mesma região, a movimentação dos dados entre regiões torna a tarefa mais lenta.

• Número de trabalhadores do Dataflow: os trabalhadores do Dataflow ideais são necessários para um bom desempenho. Ao usar o dimensionamento automático, o Dataflow escolhe o número de trabalhadores para a tarefa, consoante a quantidade de trabalho que tem de ser feito. No entanto, o número de trabalhadores é limitado pelas quotas de CPUs, endereços IP em utilização e disco persistente padrão. A IU do Dataflow apresenta um ícone de aviso se encontrar limites máximos de quota. Nesta situação, o progresso é mais lento, mas a tarefa deve ser concluída na mesma. O dimensionamento automático pode sobrecarregar o Spanner, o que leva a erros quando existe uma grande quantidade de dados a importar.

• Carga existente no Spanner: uma tarefa de importação adiciona uma carga significativa da CPU a uma instância do Spanner. Se a instância já tiver uma carga existente substancial, a tarefa é executada mais lentamente.

• Quantidade de capacidade de computação do Spanner: se a utilização da CPU da instância for superior a 65%, a tarefa é executada mais lentamente.

Ajuste os trabalhadores para um bom desempenho da importação

Ao iniciar uma tarefa de importação do Spanner, os trabalhadores do Dataflow têm de ser definidos para um valor ideal para um bom desempenho. Demasiados trabalhadores sobrecarregam o Spanner e muito poucos trabalhadores resultam num desempenho de importação insatisfatório.

O número máximo de trabalhadores depende muito do tamanho dos dados, mas, idealmente, a utilização total da CPU do Spanner deve estar entre 70% e 90%. Isto oferece um bom equilíbrio entre a eficiência do Spanner e a conclusão de tarefas sem erros.

Para alcançar esse objetivo de utilização na maioria dos esquemas e cenários, recomendamos um número máximo de vCPUs de trabalho entre 4 e 6 vezes o número de nós do Spanner.

Por exemplo, para uma instância do Spanner de 10 nós, usando trabalhadores n1-standard-2, definiria o número máximo de trabalhadores como 25, o que daria 50 vCPUs.