Exporte bases de dados do Spanner para o formato Avro

Esta página descreve como exportar bases de dados do Spanner com a consolaGoogle Cloud .

Para exportar uma base de dados do Spanner através da API REST ou da CLI Google Cloud, conclua os passos na secção Antes de começar desta página e, em seguida, consulte as instruções detalhadas em Spanner para Avro do Cloud Storage na documentação do Dataflow. O processo de exportação usa o Dataflow e escreve dados numa pasta num contentor do Cloud Storage. A pasta resultante contém um conjunto de ficheiros Avro e ficheiros do manifesto JSON.

Antes de começar

Para exportar 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 exportação são os seguintes:

• Spanner: não é necessária capacidade de computação adicional para exportar 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 exportar, tem de criar um contentor para os ficheiros exportados se ainda não tiver um. Pode fazê-lo na Google Cloud consola, através da página do Cloud Storage ou durante a criação da exportação através da página do Spanner. Não precisa de definir um tamanho para o seu contentor.
• Dataflow: as tarefas de exportaçã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 exportação, tem de configurar 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 exportaçã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.

Para usar os recursos de computação independentes do Spanner Data Boost durante uma exportação, também precisa da autorização spanner.databases.useDataBoost IAM. Para mais informações, consulte a Vista geral do aumento de dados.

Exporte uma base de dados

Depois de cumprir os requisitos de quota e IAM descritos anteriormente, pode exportar uma base de dados do Spanner existente.

Nota: é seguro exportar uma base de dados que esteja em utilização. No entanto, as alterações que fizer depois de o Dataflow criar uma transação do Spanner não são captadas pela exportação, porque todos os dados exportados são do mesmo instantâneo da base de dados.

Para exportar a sua base de dados do Spanner para um contentor do Cloud Storage, siga estes passos:

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

   Aceda a Instâncias

2. Clique no nome da instância que contém a sua base de dados.

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

4. Em Escolha onde armazenar a exportação, clique em Procurar.

5. Se ainda não tiver um contentor do Cloud Storage para a sua exportação:

   1. Clique em Novo contentor .
   2. Introduza um nome para o contentor. Os nomes dos contentores têm de ser exclusivos no Cloud Storage.
   3. Selecione uma classe de armazenamento e uma localização predefinidas e, de seguida, clique em Criar.
   4. Clique no seu depósito para o selecionar.

   Se já tiver um contentor, selecione-o na lista inicial ou clique em Pesquisar para filtrar a lista e, de seguida, clique no contentor para o selecionar.

6. Clique em Selecionar.

7. Selecione a base de dados que quer exportar no menu pendente Escolha uma base de dados para exportar.

8. Opcional: para exportar a base de dados de um momento anterior, selecione a caixa e introduza uma indicação de tempo.

9. Selecione uma região no menu pendente Escolha uma região para a tarefa de exportação.

   Nota: para evitar custos de transferência de dados, escolha uma região que se sobreponha à configuração da sua instância. Para mais informações, consulte a secção Escolha uma região.

10. Opcional: para encriptar o estado do pipeline do Dataflow com uma chave de encriptação gerida pelo cliente:

    1. Clique em Mostrar opções de encriptação.
    2. Selecione Usar uma chave de encriptação gerida pelo cliente (CMEK).
    3. Selecione a chave na lista pendente.

    Esta opção não afeta a encriptação ao nível do contentor do Cloud Storage de destino. Para ativar as CMEK para o seu contentor do Cloud Storage, consulte o artigo Use CMEK with Cloud Storage (Use CMEK com o Cloud Storage).

11. Opcional: para exportar através do Spanner Data Boost, selecione a caixa de verificação Usar Spanner Data Boost. Para mais informações, consulte a Vista geral do aumento de dados.

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

13. Clique em Exportar.

    A consola apresenta a página Importação/exportação de bases de dados, que agora mostra um elemento publicitário para a tarefa de exportação na lista de tarefas de importação/exportação, incluindo o tempo decorrido da tarefa: Google Cloud

    

Quando a tarefa termina ou é interrompida, o estado é atualizado na lista Importar/Exportar. Se a tarefa for bem-sucedida, é apresentado o estado Succeeded:

Se a tarefa falhar, é apresentado o estado Falhou:

Para ver os detalhes da operação do Dataflow para a sua tarefa, clique no nome da tarefa na coluna Nome da tarefa do Dataflow.

Se a tarefa falhar, verifique os registos do Dataflow da tarefa para ver detalhes dos erros.

Para evitar cobranças do Cloud Storage relativas a ficheiros criados pela tarefa de exportação com falhas, elimine a pasta e os respetivos ficheiros. Consulte o artigo Veja a sua exportação para obter informações sobre como encontrar a pasta.

Nota sobre a exportação de colunas geradas e streams de alterações

Os valores numa coluna gerada armazenada não são exportados. A definição da coluna é exportada para o esquema Avro como um campo de registo do tipo nulo, com a definição da coluna como propriedades personalizadas do campo. Até que a operação de preenchimento de uma coluna gerada adicionada recentemente seja concluída, a coluna gerada é ignorada como se não existisse no esquema.

As streams de alterações exportadas como ficheiros Avro contêm apenas o esquema das streams de alterações e não registos de alterações de dados.

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

As sequências (GoogleSQL, PostgreSQL) são objetos de esquema que usa para gerar valores inteiros únicos. O Spanner exporta cada um dos objetos de esquema para o esquema Avro como um campo de registo, com o respetivo tipo de sequência, intervalo ignorado e contador como propriedades do campo. Tenha em atenção que, para evitar que uma sequência seja reposta e gere valores duplicados após a importação, durante a exportação do esquema, a função GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) captura o contador de sequências. O Spanner adiciona um buffer de 1000 ao contador e escreve o novo valor do contador no campo de registo. Esta abordagem evita erros de valores duplicados que podem ocorrer após a importação. Se existirem mais escritas na base de dados de origem durante a exportação de dados, deve ajustar o contador de sequência real através da declaração ALTER SEQUENCE (GoogleSQL, PostgreSQL) .

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

Veja a sua exportação no Cloud Storage

Para ver a pasta que contém a base de dados exportada na Google Cloud consola, navegue para o navegador do Cloud Storage e escolha o contentor que selecionou anteriormente:

Aceda ao navegador de armazenamento

O contentor contém agora uma pasta com a base de dados exportada. O nome da pasta 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 ficheiros TableName.avro-#####-of-#####. 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 ficheiro ChangeStreamName.avro-00000-of-00001 para cada stream de alterações. Este ficheiro contém dados vazios com apenas o esquema Avro da stream de alterações.

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.

Exporte um subconjunto de tabelas

Se quiser exportar apenas os dados de determinadas tabelas e não de toda a base de dados, pode especificar essas tabelas durante a exportação. Neste caso, o Spanner exporta todo o esquema da base de dados, incluindo os dados das tabelas que especificar, e deixa todas as outras tabelas presentes, mas vazias, no ficheiro exportado.

Pode especificar um subconjunto de tabelas para exportar através da página Dataflow na Google Cloud consola ou da CLI gcloud. (A página do Spanner não oferece esta ação.)

Se exportar os dados de uma tabela que é filha de outra tabela, deve exportar também os dados da tabela principal. Se os pais não forem exportados, a tarefa de exportação falha.

Para exportar um subconjunto de tabelas, inicie a exportação através do modelo do Spanner para o Cloud Storage Avro do Dataflow e especifique as tabelas através da página do Dataflow na Google Cloud consola ou através da CLI gcloud, conforme descrito:

Consola

Se estiver a usar a página do Dataflow na Google Cloud consola, o parâmetro Nomes das tabelas do Cloud Spanner encontra-se na secção Parâmetros opcionais da página Criar tarefa a partir de modelo. Podem ser especificadas várias tabelas num formato separado por vírgulas.

Aceda ao Dataflow

gcloud

Execute o comando gcloud dataflow jobs run e especifique o argumento tableNames. Por exemplo:

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

A especificação de várias tabelas no gcloud requer escape de argumentos do tipo dicionário. O exemplo seguinte usa "|" como carater de escape:

 gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='^|^instanceId=test-instance|databaseId=example-db|tableNames=table1,table2|outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

O parâmetro shouldExportRelatedTables é uma opção útil para exportar automaticamente todas as tabelas principais das tabelas escolhidas. Por exemplo, nesta hierarquia de esquemas com as tabelas Singers, Albums e Songs, só precisa de especificar Songs. A opção shouldExportRelatedTables também exporta Singers e Albums, porque Songs é descendente de ambos.

gcloud dataflow jobs run my-export-job \
--gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
--region=us-central1 \
--parameters='instanceId=test-instance,databaseId=example-db,tableNames=Songs,shouldExportRelatedTables=true,outputDir=gs://my-gcs-bucket' \
--max-workers=10 \
--network=network-123

Veja ou resolva problemas de tarefas na IU do Dataflow

Depois de iniciar uma tarefa de exportaçã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 exportaçã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 leitura 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 leituras 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 Google Cloud consola, tem de iniciar a exportação através do modelo do Spanner para o Cloud Storage Avro 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-export-job \
    --gcs-location='gs://dataflow-templates/latest/Cloud_Spanner_to_GCS_Avro' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,outputDir=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 exportaçã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 exportação

Vários fatores influenciam o tempo necessário para concluir uma tarefa de exportaçã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.

• Carga existente no Spanner: normalmente, uma tarefa de exportação adiciona uma carga ligeira 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.