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 de la canalización

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

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

  Formato de manifiesto y ejemplo

  El formato del archivo de manifiesto corresponde al siguiente tipo de mensaje, que se muestra 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 denominadas Albums y Singers a una base de datos de dialecto de GoogleSQL. La tabla Albums usa el esquema de columna que el trabajo recupera 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 importarán deben estar en formato CSV, con codificación ASCII o UTF-8. Recomendamos no usar la marca de orden de bytes (BOM) en archivos con codificación 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

Nota: Si no se especifican los nombres de columna y los tipos de datos de la tabla de destino en el archivo de manifiesto de importación, las columnas en los archivos CSV deben estar en el mismo orden que las columnas en la base de datos de destino. Puedes ver el orden de las columnas en la tabla si ejecutas la siguiente consulta:

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

Advertencia: Si la base de datos de destino de Spanner no está vacía, los datos nuevos pueden reemplazar los datos preexistentes.

Parámetros de la plantilla

Parámetros obligatorios

• instanceId: El ID de la instancia de la base de datos de Spanner.
• databaseId: El ID de la base de datos de Spanner.
• importManifest : la ruta de acceso en Cloud Storage que se usará para importar archivos de manifiesto. (Por ejemplo: gs://your-bucket/your-folder/your-manifest.json).

Parámetros opcionales

• spannerHost: El extremo de Cloud Spanner al que se llamará en la plantilla. Solo se usa para pruebas. (Ejemplo: https://batch-spanner.googleapis.com). La configuración predeterminada es https://batch-spanner.googleapis.com.
• columnDelimiter : El delimitador de columnas que usa el archivo de origen. El valor predeterminado es ','. (Ejemplo: ,).
• fieldQualifier : el carácter que debe rodear a cualquier valor en el archivo de origen que contiene el columnDelimiter. El valor predeterminado es ".
• trailingDelimiter : Especifica si las líneas en 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 está configurado y la plantilla no usa el carácter de escape.
• nullString :La string que representa un valor NULL. De forma predeterminada, este parámetro no está configurado y la plantilla no usa la string nula.
• dateFormat : El formato que se usa 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 tu formato de fecha es diferente, especifica el formato con java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
• timestampFormat : 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 Unix. De lo contrario, se analiza como una string 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 string de patrón, por ejemplo, con MMM dd yyyy HH:mm:ss.SSSVV para marcas de tiempo en el formato de "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 está configurado, se usa el ID del proyecto predeterminado de Google Cloud.
• spannerPriority: la prioridad de solicitud para llamadas de Spanner. Los valores posibles son HIGH, MEDIUM y LOW. El valor predeterminado es MEDIUM.
• handleNewLine : Si es true, los datos de entrada pueden contener caracteres de salto de línea (opcional). De lo contrario, los caracteres de salto de línea generarán un error. El valor predeterminado es false. Habilitar el manejo de saltos de línea puede reducir el rendimiento.
• invalidOutputPath : la ruta de acceso de Cloud Storage que se usará cuando se escriban filas que no se pueden importar. (Ejemplo: gs://your-bucket/your-path). La configuración predeterminada es vacía.

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

Tipo	Valor de entrada	Formato	Observación
DATE	2011-3-31		De forma predeterminada, la plantilla puede analizar este formato. No necesitas especificar el parámetro dateFormat.
DATE	2011-3-31 00:00:00		De forma predeterminada, la plantilla puede analizar este formato. No necesitas especificar el formato. Si lo deseas, puedes usar yyyy-M-d' 00:00:00'.
DATE	01 abr, 18	dd MMM, yy
DATE	Miércoles, abril 3, 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		El formato predeterminado ISO_INSTANT puede analizar este tipo de marca de tiempo. No es necesario que proporciones el parámetro timestampFormat.
TIMESTAMP	1568402363		De forma predeterminada, la plantilla puede analizar este tipo de marca de tiempo y tratarla como tiempo de época Unix.
TIMESTAMP	Mar, 3 jun 2008 11:05:30 GMT	EEE, d MMM yyyy HH:mm:ss VV
TIMESTAMP	2018/12/31 110530.123PST	yyyy/MM/dd HHmmss.SSSz
TIMESTAMP	2019-01-02T11:22:33Z o 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	Si la columna de entrada es una combinación de 2019-01-02T11:22:33Z y 2019-01-02T11:22:33.123Z, el formato predeterminado puede analizar este tipo de marca de tiempo. No necesitas proporcionar tu propio parámetro de formato. Puedes usar yyyy-MM-dd'T'HH:mm:ss[.SSS]VV para manejar ambos casos. No puedes usar yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z', ya que el sufijo “Z” debe analizarse como un ID de zona horaria, no como un literal de caracteres. De forma interna, la columna de marca de tiempo se convierte en java.time.Instant. Por lo tanto, debe especificarse en UTC o tener información de zona horaria asociada. La fecha y hora local, como 2019-01-02 11:22:33, no se puede analizar como una java.time.Instant válida.

Ejecuta la plantilla

Console

1. Ve a la página Crear un trabajo a partir de una plantilla de Dataflow.
Ir a Crear un trabajo a partir de una plantilla
2. En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
3. Opcional: Para Extremo regional, selecciona un valor del menú desplegable. La región predeterminada es us-central1.

   Para obtener una lista de regiones en las que puedes ejecutar un trabajo de Dataflow, consulta Ubicaciones de Dataflow.

4. En el menú desplegable Plantilla de Dataflow, selecciona the Text Files on Cloud Storage to Cloud Spanner template.
5. En los campos de parámetros proporcionados, ingresa los valores de tus parámetros.
6. Haga clic en Ejecutar trabajo.

gcloud

Nota: Para usar Google Cloud CLI a fin de ejecutar plantillas classic, debes tener Google Cloud CLI en la versión 138.0.0 o una versión posterior.

En tu shell o terminal, ejecuta 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

Reemplaza lo siguiente:

• JOB_NAME: Es el nombre del trabajo que elijas
• VERSION: Es la versión de la plantilla que deseas usar.

  Puedes usar los siguientes valores:

  • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket gs://dataflow-templates-REGION_NAME/latest/
  • el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket gs://dataflow-templates-REGION_NAME/
  Precaución: La versión más reciente de las plantillas podría actualizarse con cambios rotundos. Los entornos de producción deben usar plantillas que se conserven en la carpeta superior con la fecha más reciente para evitar que estos cambios rotundos afecten los flujos de trabajo de producción.
• REGION_NAME: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
• INSTANCE_ID: el ID de instancia de Spanner
• DATABASE_ID: el ID de la base de datos de Spanner
• GCS_PATH_TO_IMPORT_MANIFEST: Es la ruta de Cloud Storage al archivo de manifiesto de importación.

API

Para ejecutar la plantilla con la API de REST, envía una solicitud POST HTTP. Para obtener más información de la API y sus permisos de autorización, consulta 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"
   }
}

Reemplaza lo siguiente:

• PROJECT_ID: El ID del proyecto de Google Cloud en el que deseas ejecutar el trabajo de Dataflow.
• JOB_NAME: Es el nombre del trabajo que elijas
• VERSION: Es la versión de la plantilla que deseas usar.

  Puedes usar los siguientes valores:

  • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket gs://dataflow-templates-REGION_NAME/latest/
  • el nombre de la versión, como 2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket gs://dataflow-templates-REGION_NAME/
  Precaución: La versión más reciente de las plantillas podría actualizarse con cambios rotundos. Los entornos de producción deben usar plantillas que se conserven en la carpeta superior con la fecha más reciente para evitar que estos cambios rotundos afecten los flujos de trabajo de producción.
• LOCATION: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
• INSTANCE_ID: el ID de instancia de Spanner
• DATABASE_ID: el ID de la base de datos de Spanner
• GCS_PATH_TO_IMPORT_MANIFEST: Es la ruta de Cloud Storage al archivo de manifiesto de importación.

Código fuente de la plantilla

Java

El código fuente de esta plantilla se encuentra en el repositorio GoogleCloudPlatform/DataflowTemplates de GitHub.

¿Qué sigue?

• Obtén información sobre las plantillas de Dataflow.
• Consulta la lista de plantillas que proporciona Google.