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:

  • 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

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.
  2. Ir a Crear un trabajo a partir de una plantilla
  3. En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
  4. 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.

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

gcloud

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/
  • 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/
  • 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.

¿Qué sigue?