Modelo do Cloud Storage Text para Spanner

O modelo do Cloud Storage Text para Spanner é um pipeline em lote que lê arquivos de texto CSV do Cloud Storage e os importa para um banco de dados do Cloud Spanner.

Requisitos de pipeline

  • O banco de dados e a tabela de destino do Spanner precisam existir.
  • É necessário ter permissões de leitura para o bucket do Cloud Storage e permissões de gravação para o banco de dados de destino do Spanner.
  • O caminho do Cloud Storage que contém os arquivos CSV precisa existir.
  • Você precisa criar um arquivo de manifesto de importação com uma descrição em JSON dos arquivos CSV e armazenar esse arquivo de manifesto no Cloud Storage.
  • Se o banco de dados de destino do Spanner já tiver um esquema, todas as colunas especificadas no arquivo de manifesto precisam ter os mesmos tipos de dados das colunas correspondentes no esquema do banco de dados de destino.
  • O arquivo de manifesto, codificado em ASCII ou UTF-8, precisa ter o formato a seguir:

  • Os arquivos de texto a serem importados precisam estar no formato CSV, com codificação ASCII ou UTF-8. Recomendamos não usar a marca de ordem de byte (BOM) em arquivos codificados em UTF-8.
  • Os dados precisam corresponder a um dos tipos a seguir:

    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

Parâmetros do modelo

Parâmetros obrigatórios

  • instanceId: o ID da instância referente ao banco de dados do Spanner.
  • databaseId: o ID do banco de dados referente ao banco de dados do Spanner.
  • importManifest: o caminho no Cloud Storage a ser usado na importação de arquivos de manifesto. Por exemplo: gs://your-bucket/your-folder/your-manifest.json.

Parâmetros opcionais

  • spannerHost: opcional: o endpoint do Cloud Spanner para chamar no modelo. Usado apenas para testes. Por exemplo: https://batch-spanner.googleapis.com. O padrão é: https://batch-spanner.googleapis.com.
  • columnDelimiter: o delimitador de coluna usado pelo arquivo de origem. O valor padrão é ','. (Exemplo: ,).
  • fieldQualifier: o caractere que precisa cercar qualquer valor no arquivo de origem que contém o columnDelimiter. O valor padrão é ".
  • trailingDelimiter: especifica se as linhas dos arquivos de origem têm delimitadores à direita, ou seja, se o caractere columnDelimiter aparece no final de cada linha, depois do último valor da coluna. O valor padrão é true.
  • escape: o caractere de escape usado pelo arquivo de origem. Por padrão, esse parâmetro não está definido e o modelo não usa o caractere de escape.
  • nullString: a string que representa um valor NULL. Por padrão, esse parâmetro não está definido e o modelo não usa a string nula.
  • dateFormat: o formato usado para analisar as colunas de data. Por padrã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 usando 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 carimbo de data/hora. Se o carimbo de data/hora for um número inteiro longo, ele será analisado como um horário na época Unix. Caso contrário, ele será analisado como uma string usando 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 sua própria string padrão usando, por exemplo, MMM dd yyyy HH:mm:ss.SSSVV para carimbos de data/hora na forma de "Jan 21 1998 01:02:03.456+08:00".
  • spannerProjectId: o ID do projeto do Google Cloud que contém o banco de dados do Spanner. Se não for definido, o ID do projeto padrão do Google Cloud será usado.
  • spannerPriority: a prioridade de solicitação das chamadas do Spanner. Os valores permitidos são HIGH (alto), MEDIUM (médio) e LOW (baixo). Por padrão, a frequência selecionada é MEDIUM (média).
  • handleNewLine: se definido como true, os dados de entrada poderão conter caracteres de feed de linha. Caso contrário, os caracteres de nova linha causarão um erro. O valor padrão é false. A ativação do processamento de feed de linha pode reduzir o desempenho.
  • invalidOutputPath: o caminho do Cloud Storage a ser usado na gravação de linhas que não podem ser importadas. (Exemplo: gs://your-bucket/your-path). O padrão é vazio.

Se você precisar usar formatos personalizados de data ou carimbos de data/hora, confirme se eles são padrões java.time.format.DateTimeFormatter válidos. A tabela a seguir mostra mais exemplos de formatos personalizados de colunas de data e carimbo de data/hora:

Tipo Valor de entrada Formato Observação
DATE 2011-3-31 O modelo pode analisar esse formato por padrão. Não é necessário especificar o parâmetro dateFormat.
DATE 2011-3-31 00:00:00 O modelo pode analisar esse formato por padrão. Não é necessário especificar o formato. Se preferir, use yyyy-M-d' 00:00:00'.
DATE 1º de abril de 2018 dd MMM, aa
DATE Quarta-feira, 3 de abril de 2019 AD EEEE, LLLL d, aaaa G
TIMESTAMP 2019-01-02T11:22:33Z
2019-01-02T11:22:33.123Z
2019-01-02T11:22:33.12356789Z
O formato padrão ISO_INSTANT pode analisar esse tipo de carimbo de data/hora. Não é necessário informar o parâmetro timestampFormat.
TIMESTAMP 1568402363 Por padrão, o modelo pode analisar esse tipo de carimbo de data/hora como o horário Unix da era Unix.
TIMESTAMP Ter, 3 jun 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 padrão poderá analisar esse tipo de carimbo de data/hora. Não é necessário fornecer seu próprio parâmetro de formato. Use yyyy-MM-dd'T'HH:mm:ss[.SSS]VV para lidar com os dois casos. Observe que não é possível usar yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z', porque o postfix "Z" precisa ser analisado como um ID de fuso horário, não um caractere literal. Internamente, a coluna de carimbo de data/hora é convertida em java.time.Instant. Portanto, ele precisa ser especificado em UTC ou ter informações de fuso horário associadas a ele. A data/hora local, como 2019-01-02 11:22:33, não pode ser analisada como um java.time.Instant válido.

Executar o modelo

Console

  1. Acesse a página Criar job usando um modelo do Dataflow.
  2. Acesse Criar job usando um modelo
  3. No campo Nome do job, insira um nome exclusivo.
  4. Opcional: em Endpoint regional, selecione um valor no menu suspenso. A região padrão é us-central1.

    Para ver uma lista de regiões em que é possível executar um job do Dataflow, consulte Locais do Dataflow.

  5. No menu suspenso Modelo do Dataflow, selecione the Text Files on Cloud Storage to Cloud Spanner template.
  6. Nos campos de parâmetro fornecidos, insira os valores de parâmetro.
  7. Cliquem em Executar job.

gcloud

No 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:

  • JOB_NAME: um nome de job de sua escolha
  • VERSION: a versão do modelo que você quer usar

    Use estes valores:

  • REGION_NAME: a região em que você quer implantar o job do Dataflow, por exemplo, us-central1
  • INSTANCE_ID: o ID da instância do Spanner
  • DATABASE_ID: o ID do banco de dados do Spanner
  • GCS_PATH_TO_IMPORT_MANIFEST: o caminho do Cloud Storage para o arquivo de manifesto de importação.

API

Para executar o modelo usando a API REST, envie uma solicitação HTTP POST. Para mais informações sobre a API e os respectivos escopos 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:

  • PROJECT_ID: o ID do projeto do Google Cloud em que você quer executar o job do Dataflow
  • JOB_NAME: um nome de job de sua escolha
  • VERSION: a versão do modelo que você quer usar

    Use estes valores:

  • LOCATION: a região em que você quer implantar o job do Dataflow, por exemplo, us-central1
  • INSTANCE_ID: o ID da instância do Spanner
  • DATABASE_ID: o ID do banco de dados do Spanner
  • GCS_PATH_TO_IMPORT_MANIFEST: o caminho do Cloud Storage para o arquivo de manifesto de importação.

A seguir