Importe ficheiros Avro do Spanner

Esta página descreve como importar bases de dados do Spanner para o Spanner através da consola Google Cloud . Para importar ficheiros Avro de outra origem, consulte o artigo Importe dados de bases de dados não pertencentes ao Spanner.

O processo usa o Dataflow; importa dados de uma pasta de contentor do Cloud Storage que contém um conjunto de ficheiros Avro e ficheiros de manifesto JSON. O processo de importação só suporta ficheiros Avro exportados do Spanner.

Para importar uma base de dados do Spanner através da API REST ou da gcloud CLI, conclua os passos na secção Antes de começar desta página e, de seguida, consulte as instruções detalhadas em Cloud Storage Avro para Spanner.

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:

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 Otimizar 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)

Opcional: encontre a pasta da base de dados no Cloud Storage

Para encontrar a pasta que contém a base de dados exportada na Google Cloud consola, navegue até ao navegador do Cloud Storage e clique no contentor que contém a pasta exportada.

Aceda ao navegador do Cloud Storage

O nome da pasta que contém os dados exportados começa com o ID da instância, o nome da base de dados e a data/hora da tarefa de exportação. A pasta contém:

• Um ficheiro spanner-export.json.
• Um ficheiro TableName-manifest.json para cada tabela na base de dados que exportou.

• Um ou mais TableName.avro-#####-of-##### ficheiros. O primeiro número na extensão .avro-#####-of-##### representa o índice do ficheiro Avro, começando em zero, e o segundo representa o número de ficheiros Avro gerados para cada tabela.

  Por exemplo, Songs.avro-00001-of-00002 é o segundo de dois ficheiros que contêm os dados da tabela Songs.

• Um ficheiro ChangeStreamName-manifest.json para cada stream de alterações na base de dados que exportou.

• Um ChangeStreamName.avro-00000-of-00001 ficheiro para cada stream de alterações. Este ficheiro contém dados vazios com apenas o esquema Avro da stream de alterações.

Importe uma base de dados

Para importar a sua base de dados do Spanner do Cloud Storage para a sua instância, siga estes passos.

1. Aceda à página Instâncias do Spanner.

   Aceda à página de instâncias

2. Clique no nome da instância que vai conter a base de dados importada.

3. Clique no item de menu Importar/exportar no painel do lado esquerdo e, de seguida, clique no botão Importar.

4. Em Escolha uma pasta de origem, clique em Procurar.

5. Encontre o contentor que contém a sua exportação na lista inicial ou clique em Pesquisar para filtrar a lista e encontrar o contentor. Clique duas vezes no contentor para ver as pastas que contém.

6. Encontre a pasta com os ficheiros exportados e clique para a selecionar.

7. Clique em Selecionar.

8. Introduza um nome para a nova base de dados, que o Spanner cria durante o processo de importação. O nome da base de dados não pode já existir na sua instância.

9. Escolha o dialeto para a nova base de dados (GoogleSQL ou PostgreSQL).

10. (Opcional) Para proteger a nova base de dados com uma chave de encriptação gerida pelo cliente, clique em Mostrar opções de encriptação e selecione Usar uma chave de encriptação gerida pelo cliente (CMEK). Em seguida, selecione uma chave na lista pendente.

11. Selecione uma região no menu pendente Escolha uma região para a tarefa de importação.

12. (Opcional) Para encriptar o estado do pipeline do Dataflow com uma chave de encriptação gerida pelo cliente, clique em Mostrar opções de encriptação e selecione Usar uma chave de encriptação gerida pelo cliente (CMEK). Em seguida, selecione uma chave na lista pendente.

13. Selecione a caixa de verificação em Confirmar cobranças para confirmar que existem cobranças além das incorridas pela sua instância do Spanner existente.

14. Clique em Importar.

    A Google Cloud consola apresenta a página Detalhes da base de dados, que agora mostra uma caixa que descreve a sua tarefa de importação, incluindo o tempo decorrido da tarefa:

    

Quando a tarefa termina ou é terminada, a Google Cloud consola apresenta uma mensagem na página Detalhes da base de dados. Se a tarefa for bem-sucedida, é apresentada uma mensagem de êxito:

Se a tarefa não for bem-sucedida, é apresentada uma mensagem de falha:

Se a tarefa falhar, verifique os registos do Dataflow da tarefa para ver detalhes dos erros e consulte o artigo Resolva problemas de tarefas de importação com falhas.

Uma nota sobre a importação de colunas geradas e streams de alterações

O Spanner usa a definição de cada coluna gerada no esquema Avro para recriar essa coluna. O Spanner calcula automaticamente os valores das colunas geradas durante a importação.

Da mesma forma, o Spanner usa a definição de cada stream de alterações no esquema Avro para a recriar durante a importação. Os dados de alteração da stream não são exportados nem importados através do Avro, pelo que todas as streams de alteração associadas a uma base de dados recém-importada não têm registos de dados de alteração.

Uma nota sobre a importação de sequências

Cada sequência (GoogleSQL, PostgreSQL) que o Spanner exporta usa a função GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) para capturar o respetivo estado atual. O Spanner adiciona um buffer de 1000 ao contador e escreve o novo valor do contador nas propriedades do campo de registo. Tenha em atenção que esta é apenas uma abordagem de melhor esforço para evitar erros de valores duplicados que possam ocorrer após a importação. Ajuste o contador de sequência real se existirem mais gravações na base de dados de origem durante a exportação de dados.

Na importação, a sequência começa a partir deste novo contador, em vez do contador encontrado no esquema. Se precisar, pode usar a declaração ALTER SEQUENCE (GoogleSQL, PostgreSQL) para atualizar para um novo contador.

Uma nota sobre a importação de tabelas intercaladas e chaves externas

A tarefa do Dataflow pode importar tabelas intercaladas, o que lhe permite manter as relações principal-secundário do ficheiro de origem. No entanto, as restrições de chaves externas não são aplicadas durante o carregamento de dados. A tarefa do Dataflow cria todas as chaves externas necessárias após a conclusão do carregamento de dados.

Se tiver restrições de chaves externas na base de dados do Spanner antes do início da importação, pode encontrar erros de escrita devido a violações da integridade referencial. Para evitar erros de escrita, considere eliminar todas as chaves estrangeiras existentes antes de iniciar o processo de importação.

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.

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.

  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 a tarefa estiver a ser executada lentamente, pode experimentar outras otimizações:

• 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 custos 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

Tenha em atenção que a criação de índices e chaves externas continua após a conclusão da tarefa de importação do Dataflow. Os fluxos de alterações são criados antes da conclusão da tarefa de importação, mas depois de todos os dados serem importados.

• 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 o trabalho mais lento.

• 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.