Carga datos de Klaviyo en BigQuery

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Nota: Para obtener asistencia o enviar comentarios sobre esta función, comunícate con [e-mail].

Para programar transferencias de datos recurrentes de Klaviyo a BigQuery, crea una configuración de transferencia que especifique qué objetos de datos se transferirán y con qué frecuencia se programará la transferencia de datos. Puedes crear una configuración de transferencia con la consola de Google Cloud o la herramienta de línea de comandos de bq. Una vez que hayas establecido la configuración de transferencia, el Servicio de transferencia de datos de BigQuery transferirá los datos más recientes a una tabla de BigQuery según el programa especificado.

Para obtener información sobre cómo funciona una transferencia de Klaviyo, consulta Introducción a las transferencias de datos de Klaviyo.

Limitaciones

Las transferencias incrementales de Klaviyo están sujetas a las siguientes limitaciones:

• Solo puedes elegir TIMESTAMP columnas como columnas de marca de agua.
• La transferencia incremental solo se admite para los recursos con columnas de marca de agua válidas.
• Los valores de una columna de marca de agua deben aumentar de forma monótona.
• Las transferencias incrementales no pueden sincronizar las operaciones de eliminación en la tabla de origen.
• Una sola configuración de transferencia solo puede admitir la transferencia incremental o completa.
• No puedes actualizar los objetos de la lista asset después de la primera ejecución de transferencia incremental.
• No puedes cambiar el modo de escritura en una configuración de transferencia después de la primera ejecución de transferencia incremental.
• No puedes cambiar la columna de marca de agua ni la clave primaria después de la primera ejecución de transferencia incremental.
• La tabla de BigQuery de destino se agrupa con la clave primaria proporcionada y está sujeta a las limitaciones de las tablas agrupadas.
• Cuando actualizas una configuración de transferencia existente al modo de transferencia incremental por primera vez, la primera transferencia de datos después de esa actualización transfiere todos los datos disponibles de tu fuente de datos. En cualquier transferencia de datos incremental posterior, solo se transferirán las filas nuevas y actualizadas de tu fuente de datos.

Antes de comenzar

En las siguientes secciones, se describen los requisitos que debes cumplir antes de crear una transferencia de datos de Klaviyo.

Requisitos previos de Klaviyo

Debes tener una clave de API privada de solo lectura para permitir que el conector de Klaviyo transfiera datos a BigQuery. Para obtener más información, consulta Crea una clave privada.

Requisitos previos de BigQuery

• Verifica si completaste todas las acciones necesarias para habilitar el Servicio de transferencia de datos de BigQuery.
• Crea un conjunto de datos de BigQuery para almacenar tus datos.

Roles de BigQuery requeridos

Para obtener los permisos que necesitas para crear una transferencia de datos del Servicio de transferencia de datos de BigQuery, pídele a tu administrador que te otorgue el rol de IAM de administrador de BigQuery (roles/bigquery.admin) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para crear una transferencia de datos del Servicio de transferencia de datos de BigQuery. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear una transferencia de datos del Servicio de transferencia de datos de BigQuery:

• Permisos del Servicio de transferencia de datos de BigQuery:
  • bigquery.transfers.update
  • bigquery.transfers.get
• Permisos de BigQuery:
  • bigquery.datasets.get
  • bigquery.datasets.getIamPolicy
  • bigquery.datasets.update
  • bigquery.datasets.setIamPolicy
  • bigquery.jobs.create

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información, consulta Otorga acceso a bigquery.admin.

Si quieres configurar las notificaciones de ejecución de transferencias para Pub/Sub, asegúrate de tener el permiso de IAM pubsub.topics.setIamPolicy. Los permisos de Pub/Sub no son necesarios si solo configuras las notificaciones por correo electrónico. Para obtener más información, consulta la sección sobre notificaciones de ejecución del Servicio de transferencia de datos de BigQuery.

Configura una transferencia de datos de Klaviyo

Agrega datos de Klaviyo a BigQuery estableciendo una configuración de transferencia con una de las siguientes opciones:

Console

1. Ve a la página Transferencia de datos en la consola de Google Cloud .

   Ir a Transferencias de datos

2. Haz clic en Crear transferencia.

3. En la sección Tipo de fuente, en Fuente, elige Klaviyo - Versión preliminar.

4. En la sección Detalles de fuente de datos, haz lo siguiente:

   • En Clave de API privada, ingresa tu clave de API privada. Para obtener más información, consulta Requisitos previos de Klaviyo.
   • Opcional: En Fecha de inicio, especifica una fecha de inicio para que se incluyan los registros nuevos en la transferencia de datos. Solo se incluyen en la transferencia de datos los registros creados en esta fecha o después de ella. El valor predeterminado es 3 meses antes de la fecha de ejecución de la transferencia.
   • En Objetos de Klaviyo para transferir, haz clic en Explorar para seleccionar los objetos que se transferirán al conjunto de datos de destino de BigQuery. También puedes ingresar de forma manual cualquier objeto que quieras incluir en la transferencia de datos en este campo.

5. En la sección Configuración de destino, en Conjunto de datos, elige el conjunto de datos que creaste para almacenar tus datos.

6. En la sección Nombre de configuración de la transferencia (Transfer config name), en Nombre visible (Display name), ingresa el nombre de la transferencia de datos.

7. En la sección Opciones de programación, haz lo siguiente:

   • En la lista Frecuencia de repetición, selecciona una opción para especificar la frecuencia con la que se ejecuta esta transferencia de datos. Para especificar una frecuencia de repetición personalizada, selecciona Personalizado. Si seleccionas Según demanda, esta transferencia se ejecuta cuando activas la transferencia de forma manual.
   • Si corresponde, selecciona Comenzar ahora o Comenzar a la hora definida y detalla una fecha de inicio y una hora de ejecución.

8. Opcional: En la sección Opciones de notificación, haz lo siguiente:

   • Para habilitar las notificaciones por correo electrónico, haz clic en el botón de activar o desactivar Notificación por correo electrónico. Si habilitas esta opción, el administrador de transferencias recibirá una notificación por correo electrónico cuando falle la ejecución de una transferencia.
   • Si quieres habilitar las notificaciones de ejecución de transferencias de Pub/Sub para esta transferencia, haz clic en el botón de activar Notificaciones de Pub/Sub. Puedes seleccionar el nombre del tema o hacer clic en Crear un tema para crear uno.

9. Haz clic en Guardar.

bq

Ingresa el comando bq mk y suministra la marca de creación de transferencias --transfer_config.

bq mk
    --transfer_config
    --project_id=PROJECT_ID
    --data_source=DATA_SOURCE
    --display_name=NAME
    --target_dataset=DATASET
    --params='PARAMETERS'

Reemplaza lo siguiente:

• PROJECT_ID (opcional): Es el ID del proyecto de Google Cloud . Si no se proporciona --project_id para especificar un proyecto en particular, se usa el proyecto predeterminado.
• DATA_SOURCE: La fuente de datos: klaviyo.
• NAME: el nombre visible de la configuración de transferencia de datos. El nombre de la transferencia puede ser cualquier valor que te permita identificarla con facilidad si es necesario hacerle modificaciones más tarde.
• DATASET es el conjunto de datos de destino para la configuración de transferencia.

• PARAMETERS son los parámetros de la configuración de transferencia creada en formato JSON. Por ejemplo: --params='{"param":"param_value"}' Los siguientes son los parámetros para una transferencia de datos de Klaviyo:

  • assets: Es la ruta de acceso a los objetos de Klaviyo que se transferirán a BigQuery.
  • connector.authentication.privateApiKey: Es la clave de API privada de la cuenta de Klaviyo.
  • connector.startDate: (Opcional) Es una fecha de inicio para que se incluyan registros nuevos en la transferencia de datos, en el formato YYYY-MM-DD. Solo se incluyen en la transferencia de datos los registros creados en esta fecha o después de ella. El valor predeterminado es 3 meses antes de la fecha de ejecución de la transferencia.
  • ingestionType: Especifica el método de carga de datos (opcional). Los valores permitidos son full (reemplaza todos los datos de la tabla de destino) o incremental (carga solo los datos nuevos o modificados desde la última transferencia).
  • writeMode: (Opcional) Cuando ingestionType se establece en incremental, especifica cómo se escriben los datos en la tabla de destino. Los valores permitidos son WRITE_MODE_APPEND (agrega registros nuevos) o WRITE_MODE_UPSERT (actualiza los registros existentes y, además, inserta registros nuevos).

Con el siguiente comando, se crea una transferencia de datos de Klaviyo en el proyecto predeterminado.

    bq mk
        --transfer_config
        --target_dataset=mydataset
        --data_source=klaviyo
        --display_name='My Transfer'
        --params= ' {
            "assets": [ "Events" , "Flows"] ,
            "connector.authentication.privateApiKey" : "pk_123456789123",
            "connector.startDate": "2025-10-20"
            }'

Cuando guardas la configuración de transferencia, el conector de Klaviyo activa automáticamente una ejecución de transferencia según la opción de programación que hayas elegido. Con cada ejecución de transferencia, el conector de Klaviyo transfiere todos los datos disponibles de Klaviyo a BigQuery.

Para ejecutar de forma manual una transferencia de datos fuera de tu programa habitual, puedes iniciar una ejecución de reabastecimiento.

Para obtener una lista de los datos que se incluyen en una transferencia de datos de Klaviyo, consulta la referencia del modelo de datos de Klaviyo.

Soluciona problemas con la configuración de una transferencia

Si tienes problemas para configurar tu transferencia de datos, consulta Problemas de transferencia de Klaviyo.

¿Qué sigue?

• Para obtener una descripción general del Servicio de transferencia de datos de BigQuery, consulta ¿Qué es el Servicio de transferencia de datos de BigQuery?.
• Para obtener información sobre el uso de las transferencias (por ejemplo, cómo obtener información sobre una configuración de transferencia, mostrar distintas configuraciones o visualizar su historial de ejecuciones), consulta Manejar transferencias.