Modelo de texto do Cloud Storage para o Spanner

O modelo de texto do Cloud Storage para o Spanner é um pipeline em lote que lê ficheiros de texto CSV do Cloud Storage e importa-os para uma base de dados do Spanner.

Requisitos do pipeline

• A base de dados e a tabela do Spanner de destino têm de existir.
• Tem de ter autorizações de leitura para o contentor do Cloud Storage e autorizações de escrita para a base de dados do Spanner de destino.
• O caminho do Cloud Storage de entrada que contém os ficheiros CSV tem de existir.
• Tem de criar um ficheiro de manifesto de importação que contenha uma descrição JSON dos ficheiros CSV e armazenar esse ficheiro de manifesto no Cloud Storage.
• Se a base de dados do Spanner de destino já tiver um esquema, todas as colunas especificadas no ficheiro de manifesto têm de ter os mesmos tipos de dados que as colunas correspondentes no esquema da base de dados de destino.

• O ficheiro do manifesto, codificado em ASCII ou UTF-8, tem de corresponder ao seguinte formato:

  Formato e exemplo do manifesto

  O formato do ficheiro do manifesto corresponde ao seguinte tipo de mensagem, apresentado aqui no formato de protocol buffer:

  message ImportManifest {
    // The per-table import manifest.
    message TableManifest {
      // Required. The name of the destination table.
      string table_name = 1;
      // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
      repeated string file_patterns = 2;
      // The schema for a table column.
      message Column {
        // Required for each Column that you specify. The name of the column in the
        // destination table.
        string column_name = 1;
        // Required for each Column that you specify. The type of the column.
        string type_name = 2;
      }
      // Optional. The schema for the table columns.
      repeated Column columns = 3;
    }
    // Required. The TableManifest of the tables to be imported.
    repeated TableManifest tables = 1;
  
    enum ProtoDialect {
      GOOGLE_STANDARD_SQL = 0;
      POSTGRESQL = 1;
    }
    // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
    ProtoDialect dialect = 2;
  }

  O exemplo seguinte mostra um ficheiro de manifesto para importar tabelas denominadas Albums e Singers para uma base de dados de dialeto GoogleSQL. A tabela Albums usa o esquema de colunas que a tarefa obtém da base de dados, e a tabela Singers usa o esquema que o ficheiro de manifesto especifica:

  {
    "tables": [
      {
        "table_name": "Albums",
        "file_patterns": [
          "gs://bucket1/Albums_1.csv",
          "gs://bucket1/Albums_2.csv"
        ]
      },
      {
        "table_name": "Singers",
        "file_patterns": [
          "gs://bucket1/Singers*.csv"
        ],
        "columns": [
          {"column_name": "SingerId", "type_name": "INT64"},
          {"column_name": "FirstName", "type_name": "STRING"},
          {"column_name": "LastName", "type_name": "STRING"}
        ]
      }
    ]
  }

• Os ficheiros de texto a importar têm de estar no formato CSV, com codificação ASCII ou UTF-8. Recomendamos que não use a marca de ordem de bytes (BOM) em ficheiros codificados em UTF-8.
• Os dados têm de corresponder a um dos seguintes tipos:

  GoogleSQL

      BOOL
      INT64
      FLOAT64
      NUMERIC
      STRING
      DATE
      TIMESTAMP
      BYTES
      JSON

  PostgreSQL

      boolean
      bigint
      double precision
      numeric
      character varying, text
      date
      timestamp with time zone
      bytea

Nota: se não especificar os nomes das colunas e os tipos de dados da tabela de destino no ficheiro de manifesto de importação, as colunas nos ficheiros CSV têm de estar na mesma ordem que as colunas na base de dados de destino. Pode ver a ordem das colunas na tabela executando a seguinte consulta:

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME =
      TABLE_NAME ORDER BY ORDINAL_POSITION

Aviso: se a base de dados do Spanner de destino não estiver vazia, os novos dados podem substituir os dados pré-existentes.

Parâmetros de modelos

Parâmetros obrigatórios

• instanceId: o ID da instância da base de dados do Spanner.
• databaseId: o ID da base de dados do Spanner.
• importManifest: o caminho no Cloud Storage a usar ao importar ficheiros de manifesto. Por exemplo, gs://your-bucket/your-folder/your-manifest.json.

Parâmetros opcionais

• spannerHost: o ponto final do Cloud Spanner a chamar no modelo. Usado apenas para testes. Por exemplo, https://batch-spanner.googleapis.com. O valor predefinido é: https://batch-spanner.googleapis.com.
• columnDelimiter: o delimitador de colunas que o ficheiro de origem usa. O valor predefinido é ,. Por exemplo, ,.
• fieldQualifier: o caráter que tem de envolver qualquer valor no ficheiro de origem que contenha o columnDelimiter. O valor predefinido são as aspas duplas.
• trailingDelimiter: especifica se as linhas nos ficheiros de origem têm delimitadores finais, ou seja, se o caráter columnDelimiter aparece no final de cada linha, após o valor da última coluna. O valor predefinido é true.
• escape: o caráter de escape usado pelo ficheiro de origem. Por predefinição, este parâmetro não está definido e o modelo não usa o caráter de escape.
• nullString: a string que representa um valor NULL. Por predefinição, este parâmetro não está definido e o modelo não usa a string nula.
• dateFormat: o formato usado para analisar colunas de datas. Por predefinição, o pipeline tenta analisar as colunas de data como yyyy-M-d[' 00:00:00'], por exemplo, como 2019-01-31 ou 2019-1-1 00:00:00. Se o formato de data for diferente, especifique o formato através dos padrões java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
• timestampFormat: o formato usado para analisar colunas de data/hora. Se a data/hora for um número inteiro longo, é analisada como a hora da época Unix. Caso contrário, é analisado como uma string com o formato java.time.format.DateTimeFormatter.ISO_INSTANT (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT). Para outros casos, especifique a sua própria string de padrão, por exemplo, usando MMM dd yyyy HH:mm:ss.SSSVV para indicações de tempo no formato Jan 21 1998 01:02:03.456+08:00.
• spannerProjectId: o ID do projeto do Google Cloud que contém a base de dados do Spanner. Se não for definido, é usado o ID do projeto do projeto do Google Cloud predefinido.
• spannerPriority: a prioridade do pedido para chamadas do Spanner. Os valores possíveis são HIGH, MEDIUM e LOW. O valor predefinido é MEDIUM.
• handleNewLine: se for true, os dados de entrada podem conter carateres de nova linha. Caso contrário, os carateres de nova linha causam um erro. O valor predefinido é false. A ativação do processamento de novas linhas pode reduzir o desempenho.
• invalidOutputPath: o caminho do Google Cloud Storage a usar ao escrever linhas que não podem ser importadas. Por exemplo, gs://your-bucket/your-path. A predefinição é vazio.

Se precisar de usar formatos de data ou hora personalizados, certifique-se de que são padrões válidos.java.time.format.DateTimeFormatter A tabela seguinte mostra exemplos adicionais de formatos personalizados para colunas de data e hora:

Tipo	Valor da entrada	Formato	Observação
DATE	2011-3-31		Por predefinição, o modelo pode analisar este formato. Não precisa de especificar o parâmetro dateFormat.
DATE	2011-3-31 00:00:00		Por predefinição, o modelo pode analisar este formato. Não precisa de especificar o formato. Se quiser, pode usar yyyy-M-d' 00:00:00'.
DATE	01 abr, 18	dd MMM, aa
DATE	Quarta-feira, 3 de abril de 2019 d.C.	EEEE, LLLL d, yyyy G
TIMESTAMP	2019-01-02T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z		O formato predefinido ISO_INSTANT pode analisar este tipo de data/hora. Não tem de indicar o parâmetro timestampFormat.
TIMESTAMP	1568402363		Por predefinição, o modelo pode analisar este tipo de indicação de tempo e tratá-lo como tempo de época Unix.
TIMESTAMP	Ter., 3 de jun. de 2008, 11:05:30 GMT	EEE, d MMM aaaa HH:mm:ss VV
TIMESTAMP	2018/12/31 110530.123PST	aaaa/MM/dd HHmmss.SSSz
TIMESTAMP	2019-01-02T11:22:33Z ou 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	Se a coluna de entrada for uma combinação de 2019-01-02T11:22:33Z e 2019-01-02T11:22:33.123Z, o formato predefinido pode analisar este tipo de data/hora. Não tem de fornecer o seu próprio parâmetro de formato. Pode usar yyyy-MM-dd'T'HH:mm:ss[.SSS]VV para processar ambos os casos. Não pode usar yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z' porque o sufixo "Z" tem de ser analisado como um ID de fuso horário e não como um caráter literal. Internamente, a coluna de data/hora é convertida num java.time.Instant. Por conseguinte, tem de ser especificado em UTC ou ter informações de fuso horário associadas. Não é possível analisar a data/hora local, como 2019-01-02 11:22:33, como um java.time.Instant válido.

Execute o modelo

Consola

1. Aceda à página do fluxo de dados Criar tarefa a partir de um modelo.
Aceda a Criar tarefa a partir de modelo
2. No campo Nome da tarefa, introduza um nome exclusivo para a tarefa.
3. Opcional: para Ponto final regional, selecione um valor no menu pendente. A região predefinida é us-central1.

   Para ver uma lista das regiões onde pode executar uma tarefa do Dataflow, consulte as localizações do Dataflow.

4. No menu pendente Modelo do fluxo de dados, selecione the Text Files on Cloud Storage to Cloud Spanner template.
5. Nos campos de parâmetros fornecidos, introduza os valores dos parâmetros.
6. Clique em Executar tarefa.

gcloud

Nota: para usar a CLI do Google Cloud para executar modelos classic, tem de ter a versão CLI do Google Cloud 138.0.0 ou posterior.

Na shell ou no terminal, execute o modelo:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Cloud_Spanner \
    --region REGION_NAME \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
importManifest=GCS_PATH_TO_IMPORT_MANIFEST

Substitua o seguinte:

• JOB_NAME: um nome de tarefa exclusivo à sua escolha
• VERSION: a versão do modelo que quer usar

  Pode usar os seguintes valores:

  • latest para usar a versão mais recente do modelo, que está disponível na pasta principal sem data no contentor: gs://dataflow-templates-REGION_NAME/latest/
  • o nome da versão, como 2023-09-12-00_RC00, para usar uma versão específica do modelo, que pode ser encontrada aninhada na pasta principal com a data correspondente no contentor: gs://dataflow-templates-REGION_NAME/
  Atenção: a versão mais recente dos modelos pode ser atualizada com alterações destrutivas. Os seus ambientes de produção devem usar modelos mantidos na pasta principal datada mais recente para evitar que estas alterações significativas afetem os seus fluxos de trabalho de produção.
• REGION_NAME: a região onde quer implementar a tarefa do Dataflow, por exemplo, us-central1
• INSTANCE_ID: o ID da instância do Spanner
• DATABASE_ID: o ID da sua base de dados do Spanner
• GCS_PATH_TO_IMPORT_MANIFEST: o caminho do Cloud Storage para o ficheiro de manifesto de importação

API

Para executar o modelo através da API REST, envie um pedido HTTP POST. Para mais informações sobre a API e os respetivos âmbitos de autorização, consulte projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}

Substitua o seguinte:

• PROJECT_ID: o ID do projeto onde quer executar a tarefa do Dataflow Google Cloud
• JOB_NAME: um nome de tarefa exclusivo à sua escolha
• VERSION: a versão do modelo que quer usar

  Pode usar os seguintes valores:

  • latest para usar a versão mais recente do modelo, que está disponível na pasta principal sem data no contentor: gs://dataflow-templates-REGION_NAME/latest/
  • o nome da versão, como 2023-09-12-00_RC00, para usar uma versão específica do modelo, que pode ser encontrada aninhada na pasta principal com a data correspondente no contentor: gs://dataflow-templates-REGION_NAME/
  Atenção: a versão mais recente dos modelos pode ser atualizada com alterações destrutivas. Os seus ambientes de produção devem usar modelos mantidos na pasta principal datada mais recente para evitar que estas alterações significativas afetem os seus fluxos de trabalho de produção.
• LOCATION: a região onde quer implementar a tarefa do Dataflow, por exemplo, us-central1
• INSTANCE_ID: o ID da instância do Spanner
• DATABASE_ID: o ID da sua base de dados do Spanner
• GCS_PATH_TO_IMPORT_MANIFEST: o caminho do Cloud Storage para o ficheiro de manifesto de importação

Código-fonte do modelo

Java

O código fonte deste modelo encontra-se no repositório GoogleCloudPlatform/DataflowTemplates no GitHub.

O que se segue?

• Saiba mais sobre os modelos do Dataflow.
• Consulte a lista de modelos fornecidos pela Google.