Fuente por lotes de Cloud Storage

En esta página, se proporciona orientación para configurar el complemento de fuente por lotes de Cloud Storage en Cloud Data Fusion.

El complemento de fuente por lotes de Cloud Storage te permite leer datos de buckets de Cloud Storage y trasladarlos a Cloud Data Fusion para su posterior procesamiento y transformación. Te permite cargar datos desde varios formatos de archivo, incluidos los siguientes:

  • Estructurados: CSV, Avro, Parquet, ORC
  • Semiestructurados: JSON, XML
  • Otros: Texto, Binario

Antes de comenzar

Cloud Data Fusion generalmente tiene dos cuentas de servicio:

Antes de usar el complemento de fuente por lotes de Cloud Storage, otorga el siguiente rol o permisos a cada cuenta de servicio.

Agente de servicios de la API de Cloud Data Fusion

Esta cuenta de servicio ya tiene todos los permisos necesarios y no es necesario que agregues permisos adicionales.

Cuenta de servicio de Compute Engine

En tu proyecto de Google Cloud, otorga las siguientes funciones o permisos de IAM a la cuenta de servicio de Compute Engine:

Cómo configurar el complemento

  1. Ve a la interfaz web de Cloud Data Fusion y haz clic en Studio.
  2. Comprueba que la opción Data Pipeline - Batch esté seleccionada (no Realtime).
  3. En el menú Fuente, haz clic en GCS. El nodo de Cloud Storage aparece en tu canalización.
  4. Para configurar la fuente, ve al nodo de Cloud Storage y haz clic en Propiedades.

  5. Ingresa las siguientes propiedades. Para obtener una lista completa, consulta Propiedades.

    1. Ingresa una Etiqueta para el nodo de Cloud Storage, por ejemplo, Cloud Storage tables.

    2. Ingresa los detalles de la conexión. Puedes configurar una conexión nueva de un solo uso, o una existente y reutilizable.

      Nueva conexión

      Para agregar una conexión de un solo uso a Cloud Storage, sigue estos pasos:

      1. Mantén desactivada la opción Usar conexión.
      2. En el campo ID del proyecto, deja el valor en la opción de detección automática.

      3. En el campo Tipo de cuenta de servicio, deja el valor como Ruta del archivo y la Ruta del archivo de la cuenta de servicio con la configuración de detección automática.

      Conexión reutilizable

      Para volver a usar una conexión existente, sigue estos pasos:

      1. Activa Usar conexión.
      2. Haz clic en Browse connections.

      3. Haz clic en el nombre de la conexión, por ejemplo, Cloud Storage Default.

      4. Opcional: Si no existe una conexión y deseas crear una nueva y reutilizable, haz clic en Agregar conexión y consulta los pasos de la pestaña Conexión nueva de esta página.

    3. En el campo Nombre de referencia, ingresa un nombre para usar para el linaje, por ejemplo, data-fusion-gcs-campaign.

    4. En el campo Ruta de acceso, ingresa la ruta de acceso desde la que se leerá, por ejemplo, gs://BUCKET_PATH.

    5. En el campo Formato, selecciona uno de los siguientes formatos de archivo para los datos que se leen:

      • avro
      • blob (el formato BLOB requiere un esquema que contenga un campo llamado cuerpo de tipo bytes)
      • csv
      • delimitado
      • json
      • parquet
      • text (el formato de texto requiere un esquema que contiene un campo llamado cuerpo de tipo string)
      • TSV
      • El nombre de cualquier complemento de formato que hayas implementado en tu entorno

    6. Opcional: Para probar la conectividad, haz clic en Obtener esquema.

    7. Opcional: En el campo Tamaño de la muestra, ingresa la cantidad máxima de filas para verificar el tipo de datos seleccionado, por ejemplo, 1000.

    8. Opcional: En el campo Anular, ingresa los nombres de las columnas y sus respectivos tipos de datos que se omitirán.

    9. Opcional: Ingresa Propiedades avanzadas, como un tamaño de división mínimo o un filtro de ruta de acceso de expresión regular (consulta Propiedades).

    10. Opcional: En el campo Nombre del bucket temporal, ingresa un nombre para el bucket de Cloud Storage.

  6. Opcional: Haz clic en Validar y corrige cualquier error encontrado.

  7. Haz clic en Cerrar. Las propiedades se guardan y puedes continuar con la compilación de tu canalización de datos en Cloud Data Fusion Studio.

Propiedades

Propiedad Macro habilitado Propiedad obligatoria Descripción
Etiqueta No Sí El nombre del nodo en tu canalización de datos.
Usar conexión No No Busca una conexión reutilizable al origen. Para obtener más información sobre cómo agregar, importar y editar las conexiones que aparecen cuando exploras las conexiones, consulta Cómo administrar conexiones.
Conexión Sí Sí Si la opción Usar conexión está activada, el nombre de la conexión reutilizable que selecciones aparecerá en este campo.
ID del proyecto Sí No Solo se usa cuando la opción Usar conexión está desactivada. Es un identificador único a nivel global para el proyecto.
El valor predeterminado es auto-detect.
Tipo de cuenta de servicio Sí No Selecciona una de las siguientes opciones:
  • Ruta de acceso al archivo: La ruta en la que se encuentra la cuenta de servicio.
  • JSON: contenido JSON de la cuenta de servicio.
Ruta de acceso del archivo de la cuenta de servicio Sí No Solo se usa cuando el valor del tipo de cuenta de servicio es File path. Es la ruta de acceso en el sistema de archivos local de la clave de cuenta de servicio que se usó para la autorización. Si los trabajos se ejecutan en clústeres de Dataproc, configura el valor como detección automática. Si los trabajos se ejecutan en otros tipos de clústeres, el archivo debe estar presente en todos los nodos del clúster.
El valor predeterminado es auto-detect.
JSON de la cuenta de servicio Sí No Solo se usa cuando el valor del tipo de cuenta de servicio es JSON. El contenido del archivo JSON de la cuenta de servicio.
Nombre de referencia No Sí Nombre que identifica esta fuente de forma única para otros servicios, como linaje y metadatos de anotación.
Ruta de acceso Sí Sí Es la ruta de acceso a los archivos que se leerán. Si se especifica un directorio, finaliza la ruta de acceso con una barra inversa (/). Por ejemplo, gs://bucket/path/to/directory/. Para hacer coincidir un patrón de nombre de archivo, puedes usar un asterisco (*) como comodín. Si no se encuentran archivos ni coinciden, la canalización falla.
Formato No Sí Formato de los datos que se leerán. El formato debe ser uno de los siguientes:
  • avro
  • blob (el formato BLOB requiere un esquema que contenga un campo llamado cuerpo de tipo bytes)
  • csv
  • delimitado
  • json
  • parquet
  • text (el formato de texto requiere un esquema que contenga un campo llamado cuerpo de tipo de string)
  • TSV
  • El nombre de cualquier complemento de formato que hayas implementado en tu entorno
  • Si el formato es una macro, solo se pueden usar los formatos empaquetados previamente.
Tamaño de la muestra Sí No La cantidad máxima de filas que se investigan para la detección automática de tipos de datos. El valor predeterminado es 1000.
Anular Sí No Una lista de columnas con los datos correspondientes desde los que se omite la detección automática de tipos de datos.
Delimitador Sí No Delimitador que se debe usar cuando el formato está delimitado. Esta propiedad se ignora para otros formatos.
Cómo habilitar valores entre comillas Sí No Indica si se debe tratar el contenido entre comillas como un valor. Esta propiedad solo se usa para los formatos csv, tsv o delimitados. Por ejemplo, si se establece esta propiedad como verdadera, los siguientes resultados generan dos campos: 1, "a, b, c". El primer campo tiene 1 como valor. El segundo tiene a, b, c. Los caracteres de las comillas están cortados. El delimitador de salto de línea no puede estar entre comillas.
El complemento da por sentado que las comillas se encierran correctamente, por ejemplo, "a, b, c". No cerrar una comilla ("a,b,c,) genera un error.
El valor predeterminado es False.
Usa la primera fila como encabezado Sí No Indica si se debe usar la primera línea de cada archivo como encabezado de columna. Los formatos compatibles son text, csv, tsv y delimitado.
El valor predeterminado es False.
Tamaño mínimo de la división Sí No Tamaño mínimo, en bytes, para cada partición de entrada. Las particiones más pequeñas aumentan el nivel de paralelismo, pero requieren más recursos y sobrecarga.
Si el valor de Formato es blob, no puedes dividir los datos.
Tamaño máximo de la división Sí No Tamaño máximo (en bytes) para cada partición de entrada. Las particiones más pequeñas aumentan el nivel de paralelismo, pero requieren más recursos y sobrecarga.
Si el valor de Formato es blob, no puedes dividir los datos.
El valor predeterminado es 128 MB.
Filtro de ruta de acceso de regex Sí No Expresión regular con la que deben coincidir las rutas de acceso de los archivos para que se incluya en la entrada. Se compara la ruta de acceso completa, no solo el nombre del archivo. Si no se proporciona ningún archivo, no se filtra ningún archivo. Para obtener más información sobre la sintaxis de expresiones regulares, consulta Patrón.
Campo de ruta Sí No Campo de resultado para colocar la ruta de acceso del archivo desde el que se leyó el registro. Si no se especifica, la ruta no se incluye en los registros de salida. Si se especifica, el campo debe existir en el esquema de salida como una string.
Solo el nombre de archivo de la ruta de acceso Sí No Si se configura una propiedad de campo de ruta de acceso, usa solo el nombre de archivo y no el URI de la ruta de acceso.
El valor predeterminado es False.
Cómo leer archivos de manera recurrente Sí No Indica si los archivos se deben leer de manera recursiva en la ruta de acceso.
El valor predeterminado es False.
Permitir entradas vacías Sí No Indica si se debe permitir una ruta de acceso de entrada que no contenga datos. Si se establece en False, el complemento generará un error cuando no haya datos para leer. Cuando se configura en True, no se arroja ningún error y no se lee ningún registro.
El valor predeterminado es False.
Archivo de datos encriptado Sí No Si los archivos están encriptados. Para obtener más información, consulta Encriptación de archivos de datos.
El valor predeterminado es False.
Sufijo del archivo de metadatos de encriptación Sí No El sufijo del nombre de archivo para el archivo de metadatos de encriptación.
El valor predeterminado son los metadatos.
Propiedades del sistema de archivos Sí No Propiedades adicionales para usar con InputFormat cuando se leen los datos.
Codificación de archivos Sí No La codificación de caracteres para los archivos que se leerán.
El valor predeterminado es UTF-8.
Esquema de salida Sí No Si se configura una propiedad de Campo de ruta de acceso, debe estar presente en el esquema como una string.

Encriptación de archivos de datos

En esta sección, se describe la propiedad Encriptación de archivos de datos. Si lo configuras como true, los archivos se desencriptan con el AEAD de transmisión que proporciona la biblioteca Tink. Cada archivo de datos debe ir acompañado de un archivo de metadatos que contenga la información del algoritmo de cifrado. Por ejemplo, un archivo de datos encriptados en gs://BUCKET/PATH_TO_DIRECTORY/file1.csv.enc debe tener un archivo de metadatos en gs://BUCKET/ PATH_TO_DIRECTORY/file1.csv.enc.metadata. El archivo de metadatos contiene un objeto JSON con las siguientes propiedades:

Propiedad Descripción
kms El URI de Cloud Key Management Service que se usó para encriptar la clave de encriptación de datos.
aad Los datos autenticados adicionales codificados en Base64 que se usan en la encriptación.
key set Un objeto JSON que representa la información del conjunto de claves serializado de la biblioteca Tink

Ejemplo

    /* Counting example */
    {

      "kms": "gcp-kms://projects/my-key-project/locations/us-west1/keyRings/my-key-ring/cryptoKeys/mykey",

      "aad": "73iT4SUJBM24umXecCCf3A==",

      "keyset": {

          "keysetInfo": {

              "primaryKeyId": 602257784,

              "keyInfo": [{

                  "typeUrl": "type.googleapis.com/google.crypto.tink.AesGcmHkdfStreamingKey",

                  "outputPrefixType": "RAW",

                  "keyId": 602257784,

                  "status": "ENABLED"

              }]

          },

          "encryptedKeyset": "CiQAz5HH+nUA0Zuqnz4LCnBEVTHS72s/zwjpcnAMIPGpW6kxLggSrAEAcJKHmXeg8kfJ3GD4GuFeWDZzgGn3tfolk6Yf5d7rxKxDEChIMWJWGhWlDHbBW5B9HqWfKx2nQWSC+zjM8FLefVtPYrdJ8n6Eg8ksAnSyXmhN5LoIj6az3XBugtXvCCotQHrBuyoDY+j5ZH9J4tm/bzrLEjCdWAc+oAlhsUAV77jZhowJr6EBiyVuRVfcwLwiscWkQ9J7jjHc7ih9HKfnqAZmQ6iWP36OMrEn"

      }

    }

Notas de la versión

¿Qué sigue?