La canalización de Cloud Storage Text a BigQuery es una canalización por lotes que lee archivos de texto almacenados en Cloud Storage, los transforma con una función de JavaScript definida por el usuario (UDF) y agrega el resultado a una tabla de BigQuery.
Requisitos de la canalización
- Crea un archivo JSON que describa tu esquema de BigQuery.
Asegúrate de que haya un array JSON de nivel superior titulado
BigQuery Schema
y que su contenido siga el patrón{"name": "COLUMN_NAME", "type": "DATA_TYPE"}
.La plantilla de texto de Cloud Storage a BigQuery no admite la importación de datos a los campos
STRUCT
(Record) en la tabla BigQuery de destino.En el siguiente JSON, se describe un esquema de BigQuery de ejemplo:
{ "BigQuery Schema": [ { "name": "name", "type": "STRING" }, { "name": "age", "type": "INTEGER" }, ] }
- Crea un archivo JavaScript (
.js
) con tu función UDF que proporciona la lógica para transformar las líneas de texto. La función debe mostrar una string JSON.Por ejemplo, esta función divide cada línea de un archivo CSV y muestra una string JSON después de transformar los valores.
function process(inJson) { val = inJson.split(","); const obj = { "name": val[0], "age": parseInt(val[1]) }; return JSON.stringify(obj); }
Parámetros de la plantilla
Parámetros obligatorios
- inputFilePattern: La ruta de acceso gs:// al texto en Cloud Storage que deseas procesar. (Ejemplo: gs://your-bucket/your-file.txt).
- JSONPath: Ruta de acceso gs:// al archivo JSON que define el esquema de BigQuery almacenado en Cloud Storage. (Ejemplo: gs://your-bucket/your-schema.json).
- outputTable: La ubicación de la tabla de BigQuery que se usará para almacenar los datos procesados. Si vuelves a usar una tabla existente, se reemplaza. (Ejemplo: <PROJECT_ID>:<DATASET_NAME>.<TABLE_NAME>).
- javascriptTextTransformGcsPath: El URI de Cloud Storage del archivo
.js
que define la función definida por el usuario (UDF) de JavaScript que deseas usar. (Por ejemplo: gs://your-bucket/your-transforms/*.js). - javascriptTextTransformFunctionName: Es el nombre de la función definida por el usuario (UDF) de JavaScript que deseas usar. Por ejemplo, si el código de tu función de JavaScript es
myTransform(inJson) { /*...do stuff...*/ }
, el nombre de la función esmyTransform
. Para ver ejemplos de UDF de JavaScript, consulta ejemplos de UDF (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples, ejemplo: transform_udf1). - bigQueryLoadingTemporaryDirectory: El directorio temporal para el proceso de carga de BigQuery. (Ejemplo: gs://your-bucket/your-files/temp-dir).
Parámetros opcionales
- useStorageWriteApi: si es
true
, la canalización usa la API de BigQuery Storage Write (https://cloud.google.com/bigquery/docs/write-api). El valor predeterminado esfalse
. Para obtener más información, consulta Usa la API de Storage Write (https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api). - useStorageWriteApiAtLeastOnce: cuando usas la API de Storage Write, se especifica la semántica de escritura. Para usar una semántica de al menos una vez (https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics), configura el parámetro en
true
. Para usar una semántica de una y solo una vez, configura el parámetro enfalse
. Este parámetro se aplica solo cuandouseStorageWriteApi
estrue
. El valor predeterminado esfalse
.
Función definida por el usuario
Para extender esta plantilla, puedes escribir una función definida por el usuario (UDF). La plantilla llama a la UDF para cada elemento de entrada. Las cargas útiles de elementos se serializan como cadenas JSON. Para obtener más información, consulta Crea funciones definidas por el usuario para plantillas de Dataflow.
Especificación de la función
La UDF tiene la siguiente especificación:
- Entrada: una línea de texto de un archivo de entrada de Cloud Storage.
- Resultado: Una cadena JSON que coincide con el esquema de la tabla de destino de BigQuery.
Ejecuta la plantilla
Console
- 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
- En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
- 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.
- En el menú desplegable Plantilla de Dataflow, selecciona the Text Files on Cloud Storage to BigQuery (Batch) template.
- En los campos de parámetros proporcionados, ingresa los valores de tus parámetros.
- Haga clic en Ejecutar trabajo.
gcloud
En tu shell o terminal, ejecuta la plantilla:
gcloud dataflow flex-template run JOB_NAME \ --template-file-gcs-location gs://dataflow-templates-REGION_NAME/VERSION/flex/GCS_Text_to_BigQuery_Flex \ --region REGION_NAME \ --parameters \ javascriptTextTransformFunctionName=JAVASCRIPT_FUNCTION,\ JSONPath=PATH_TO_BIGQUERY_SCHEMA_JSON,\ javascriptTextTransformGcsPath=PATH_TO_JAVASCRIPT_UDF_FILE,\ inputFilePattern=PATH_TO_TEXT_DATA,\ outputTable=BIGQUERY_TABLE,\ bigQueryLoadingTemporaryDirectory=PATH_TO_TEMP_DIR_ON_GCS
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 elijasVERSION
: 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
JAVASCRIPT_FUNCTION
es el nombre de la función definida por el usuario (UDF) de JavaScript que deseas usar.Por ejemplo, si el código de tu función de JavaScript es
myTransform(inJson) { /*...do stuff...*/ }
, el nombre de la función esmyTransform
. Para ver ejemplos de UDF de JavaScript, consulta Ejemplos de UDF.PATH_TO_BIGQUERY_SCHEMA_JSON
: Es la ruta de acceso de Cloud Storage al archivo JSON que contiene la definición de esquema.PATH_TO_JAVASCRIPT_UDF_FILE
: El URI de Cloud Storage de.js
archivo que define la función definida por el usuario (UDF) de JavaScript que deseas usar, por ejemplo:gs://my-bucket/my-udfs/my_file.js
PATH_TO_TEXT_DATA
: Es la ruta de acceso de Cloud Storage al conjunto de datos de textoBIGQUERY_TABLE
: Es el nombre de la tabla de BigQuery.PATH_TO_TEMP_DIR_ON_GCS
: Es la ruta de acceso de Cloud Storage al directorio temporal.
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/flexTemplates:launch { "launch_parameter": { "jobName": "JOB_NAME", "parameters": { "javascriptTextTransformFunctionName": "JAVASCRIPT_FUNCTION", "JSONPath": "PATH_TO_BIGQUERY_SCHEMA_JSON", "javascriptTextTransformGcsPath": "PATH_TO_JAVASCRIPT_UDF_FILE", "inputFilePattern":"PATH_TO_TEXT_DATA", "outputTable":"BIGQUERY_TABLE", "bigQueryLoadingTemporaryDirectory": "PATH_TO_TEMP_DIR_ON_GCS" }, "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/GCS_Text_to_BigQuery_Flex", } }
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 elijasVERSION
: 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
JAVASCRIPT_FUNCTION
es el nombre de la función definida por el usuario (UDF) de JavaScript que deseas usar.Por ejemplo, si el código de tu función de JavaScript es
myTransform(inJson) { /*...do stuff...*/ }
, el nombre de la función esmyTransform
. Para ver ejemplos de UDF de JavaScript, consulta Ejemplos de UDF.PATH_TO_BIGQUERY_SCHEMA_JSON
: Es la ruta de acceso de Cloud Storage al archivo JSON que contiene la definición de esquema.PATH_TO_JAVASCRIPT_UDF_FILE
: El URI de Cloud Storage de.js
archivo que define la función definida por el usuario (UDF) de JavaScript que deseas usar, por ejemplo:gs://my-bucket/my-udfs/my_file.js
PATH_TO_TEXT_DATA
: Es la ruta de acceso de Cloud Storage al conjunto de datos de textoBIGQUERY_TABLE
: Es el nombre de la tabla de BigQuery.PATH_TO_TEMP_DIR_ON_GCS
: Es la ruta de acceso de Cloud Storage al directorio temporal.
¿Qué sigue?
- Obtén información sobre las plantillas de Dataflow.
- Consulta la lista de plantillas que proporciona Google.