Plantilla de texto de Cloud Storage a Spanner

La plantilla de texto de Cloud Storage a Spanner es una canalización por lotes que lee archivos de texto CSV de Cloud Storage y los importa a una base de datos de Spanner.

Requisitos del flujo de procesamiento

• La base de datos y la tabla de destino de Spanner deben existir.
• Debes tener permisos de lectura para el segmento de Cloud Storage y permisos de escritura para la base de datos de Spanner de destino.
• La ruta de Cloud Storage de entrada que contiene los archivos CSV debe existir.
• Debe crear un archivo de manifiesto de importación que contenga una descripción JSON de los archivos CSV y almacenarlo en Cloud Storage.
• Si la base de datos de Spanner de destino ya tiene un esquema, las columnas especificadas en el archivo de manifiesto deben tener los mismos tipos de datos que las columnas correspondientes del esquema de la base de datos de destino.

• El archivo de manifiesto, codificado en ASCII o UTF-8, debe tener el siguiente formato:

  Formato y ejemplo de manifiesto

  El formato del archivo de manifiesto corresponde al siguiente tipo de mensaje, que se muestra aquí en formato de búfer de protocolo:

  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;
  }

  En el siguiente ejemplo se muestra un archivo de manifiesto para importar tablas llamadas Albums y Singers en una base de datos con dialecto GoogleSQL. La tabla Albums usa el esquema de columna que obtiene el trabajo de la base de datos, y la tabla Singers usa el esquema que especifica el archivo de manifiesto:

  {
    "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"}
        ]
      }
    ]
  }

• Los archivos de texto que se importen deben estar en formato CSV y tener codificación ASCII o UTF-8. Te recomendamos que no utilices la marca de orden de bytes (BOM) en archivos codificados en UTF-8.
• Los datos deben coincidir con uno de los siguientes 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

Parámetros de plantilla

Parámetros obligatorios

• instanceId ID de instancia de la base de datos de Spanner.
• databaseId el ID de la base de datos de Spanner.
• importManifest: ruta de Cloud Storage que se usará al importar archivos de manifiesto. Por ejemplo, gs://your-bucket/your-folder/your-manifest.json.

Parámetros opcionales

• spannerHost el endpoint de Cloud Spanner al que se llama en la plantilla. Solo se usa para hacer pruebas. Por ejemplo, https://batch-spanner.googleapis.com. El valor predeterminado es https://batch-spanner.googleapis.com.
• columnDelimiter el delimitador de columnas que usa el archivo de origen. El valor predeterminado es ,. Por ejemplo, ,.
• fieldQualifier: el carácter que debe rodear cualquier valor del archivo de origen que contenga el valor de columnDelimiter. El valor predeterminado son las comillas dobles.
• trailingDelimiter especifica si las líneas de los archivos de origen tienen delimitadores finales, es decir, si el carácter columnDelimiter aparece al final de cada línea, después del último valor de columna. El valor predeterminado es true.
• Escape: el carácter de escape que usa el archivo de origen. De forma predeterminada, este parámetro no se define y la plantilla no usa el carácter de escape.
• nullString cadena que representa un valor NULL. De forma predeterminada, este parámetro no se define y la plantilla no usa la cadena nula.
• dateFormat formato usado para analizar las columnas de fecha. De forma predeterminada, la canalización intenta analizar las columnas de fecha como yyyy-M-d[' 00:00:00'], por ejemplo, como 2019-01-31 o 2019-1-1 00:00:00. Si el formato de fecha es diferente, especifícalo con los patrones java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
• timestampFormat el formato que se usa para analizar las columnas de marca de tiempo. Si la marca de tiempo es un número entero largo, se analiza como tiempo de época de Unix. De lo contrario, se analiza como una cadena con el 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). En otros casos, especifica tu propia cadena de patrón. Por ejemplo, puedes usar MMM dd yyyy HH:mm:ss.SSSVV para las marcas de tiempo con el formato Jan 21 1998 01:02:03.456+08:00.
• spannerProjectId el ID del proyecto de Google Cloud que contiene la base de datos de Spanner. Si no se define, se usa el ID de proyecto del proyecto de Google Cloud predeterminado.
• spannerPriority la prioridad de la solicitud para las llamadas de Spanner. Los valores posibles son HIGH, MEDIUM y LOW. El valor predeterminado es MEDIUM.
• handleNewLine si true, los datos de entrada pueden contener caracteres de salto de línea. De lo contrario, los caracteres de salto de línea provocan un error. El valor predeterminado es false. Habilitar la gestión de saltos de línea puede reducir el rendimiento.
• invalidOutputPath ruta de Cloud Storage que se usará al escribir filas que no se puedan importar. Por ejemplo, gs://your-bucket/your-path. El valor predeterminado es una cadena vacía.

Si necesitas usar formatos de fecha o de marca de tiempo personalizados, asegúrate de que sean patrones válidos. java.time.format.DateTimeFormatter En la siguiente tabla se muestran más ejemplos de formatos personalizados para columnas de fecha y marca de tiempo:

Ejecutar la plantilla

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

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"
   }
}