Integración con Meta

En esta página, se describen las configuraciones necesarias para importar datos de Meta (anuncios de Facebook y de Instagram) como fuente de datos de la carga de trabajo de marketing de Cortex Framework Data Foundation.

Meta es una empresa de tecnología que posee varias plataformas en línea populares. Cortex Framework integra los anuncios de datos de Instagram y Facebook para analizarlos, combinarlos con otras fuentes de datos y usar la IA para obtener estadísticas más detalladas y optimizar tu estrategia de marketing.

En el siguiente diagrama, se describe cómo los datos de marketing de Meta están disponibles a través de la carga de trabajo de marketing de la base de datos de Cortex Framework:

Fuente de metadatos

Figura 1. Es la fuente de datos de marketing de Meta.

Archivo de configuración

El archivo config.json configura los parámetros necesarios para conectarse a las fuentes de datos y transferir datos de diversas cargas de trabajo. Este archivo contiene los siguientes parámetros para Meta:

   "marketing": {
        "deployMeta": true,
        "Meta": {
            "deployCDC": true,
            "datasets": {
                "cdc": "",
                "raw": "",
                "reporting": "REPORTING_Meta"
            }
        }
    }

En la siguiente tabla, se describe el valor de cada parámetro de marketing:

Parámetro Significado Valor predeterminado Descripción
marketing.deployMeta Implementar Meta true Ejecuta la implementación de la fuente de datos de Meta.
marketing.Meta.deployCDC Implementa secuencias de comandos de CDC para Meta true Genera secuencias de comandos de procesamiento de CDC de Meta para ejecutarlas como DAG en Cloud Composer.
marketing.Meta.datasets.cdc Conjunto de datos de CDC para Meta Es el conjunto de datos de CDC para Meta.
marketing.Meta.datasets.raw Conjunto de datos sin procesar para Meta Es el conjunto de datos sin procesar de Meta.
marketing.Meta.datasets.reporting Conjunto de datos de informes para Meta "REPORTING_Meta" Es el conjunto de datos de informes de Meta.

Modelo de datos

En esta sección, se describe el modelo de datos de Meta con el diagrama de relación entre entidades (ERD).

Diagrama de relación entre entidades de Meta

Figura 2. Meta: Diagrama de relación entre entidades.

Vistas base

Estos son los objetos azules en el DER y son vistas de las tablas de CDC con transformaciones mínimas para desempaquetar estructuras de datos complejas. Consulta las secuencias de comandos en src/marketing/src/Meta/src/reporting/ddls.

Vistas de informes

Estos son los objetos verdes en el DER y son vistas de informes que contienen métricas agregadas. Consulta las secuencias de comandos en src/marketing/src/Meta/src/reporting/ddls.

Conexión a la API

Las plantillas de transferencia en Cortex Framework para Meta usan la API de Meta Marketing para recuperar atributos y métricas de informes. Las plantillas actuales usan la versión v25.0.

Meta impone un límite de frecuencia dinámico cuando se consulta la API de Marketing. Cuando se alcanza el límite de frecuencia, es posible que los DAG de transferencia de datos de Source to Raw no se completen correctamente. En esos casos, puedes ver mensajes de error relevantes en el registro, y la próxima ejecución de los DAG cargará de forma retroactiva los datos faltantes.

La API de Meta Marketing tiene dos niveles de acceso: Básico y Estándar. El nivel Estándar ofrece un límite mucho más alto y se recomienda si planeas usar la transferencia de datos de Source to Raw de forma extensiva. Para obtener más detalles sobre estos límites y cómo alcanzar un nivel de acceso más alto, consulta la documentación de Meta.

Si tienes acceso al nivel Estándar, puedes reducir el valor del parámetro de configuración next_request_delay_sec en src/Meta/src/raw/pipelines/config.ini para que los tiempos de carga sean más rápidos.

Acceso a la API y token de acceso

Para transferir correctamente los datos de Meta a Cortex Framework, debes seguir los pasos que se indican a continuación en el Administrador de Negocio de Meta y la consola para desarrolladores.

  1. Identifica una app para usar. Puedes crear una app nueva que esté conectada a la cuenta comercial. Asegúrate de que tu app sea del tipo Business.
  2. Configura los permisos de la app. Debes tener asignado el rol de administrador en la app para poder crear tokens con ella. Consulta la documentación sobre los roles de la app. Asegúrate de asignar recursos (cuentas) relevantes a tu aplicación.

  3. Crea un token de acceso. Se requieren tokens de acceso para acceder a la API de Meta Marketing, y siempre están asociados a una app y a un usuario. Puedes crear el token con un usuario del sistema o con tu propio acceso.

    1. Crea un usuario del sistema administrador.
    2. Genera un token. Asegúrate de anotar tus tokens en cuanto se generen, ya que no podrás recuperarlos una vez que salgas de la página.
    3. Otorga los permisos ads_read y business_management a tu token para acceder a los objetos compatibles.

  4. Sigue la documentación de Cloud Composer para habilitar Secret Manager en Cloud Composer. Luego, crea un secreto llamado cortex_meta_access_token y almacena el token que generaste en el paso anterior como contenido.

Actualidad y demora de los datos

Como regla general, la actualización de los datos de las fuentes de datos de Cortex Framework está limitada por lo que permite la conexión upstream, así como por la frecuencia de ejecución de tu DAG. Ajusta la frecuencia de ejecución de tu DAG para que coincida con la frecuencia de los DAGs upstream, las restricciones de recursos y las necesidades de tu empresa.

Con la API de Meta Marketing, la mayoría de los datos (excepto las conversiones) están disponibles casi en tiempo real, aunque se pueden ajustar hasta 28 días después del evento.

Permisos de conexiones de Cloud Composer

Crea las siguientes conexiones en Cloud Composer. Consulta más detalles en la documentación sobre cómo administrar conexiones de Airflow.

Nombre de la conexión Purpose
meta_raw_dataflow Para la API de Meta Marketing > Conjunto de datos sin procesar de BigQuery
meta_cdc_bq Para la transferencia de datos sin procesar > conjunto de datos de CDC
meta_reporting_bq Para la transferencia del conjunto de datos de informes > conjunto de datos de los CDC

Permisos de la cuenta de servicio de Cloud Composer

Otorga permisos de Dataflow a la cuenta de servicio que se usa en Cloud Composer (según se configuró en la conexión meta_raw_dataflow). Consulta las instrucciones en la documentación de Dataflow. La cuenta de servicio también requiere el permiso Secret Manager Secret Accessor. Consulta los detalles en la documentación sobre el control de acceso.

Parámetros de solicitud

El directorio src/Meta/config/request_parameters contiene un archivo de especificación de solicitud de API para cada entidad que se extrae de la API de Meta Marketing. Cada archivo de solicitud contiene una lista de campos para recuperar de la API de Meta Marketing, un campo por fila. Consulta más información en la Referencia de la API de Meta Marketing.

Configuración de transferencia

Controla las canalizaciones de datos Source to Raw y Raw to CDC a través de la configuración del archivo src/Meta/config/ingestion_settings.yaml. En esta sección, se describen los parámetros de cada canalización de datos.

De tablas de origen a tablas sin procesar

En esta sección, se incluyen entradas que controlan qué entidades recuperan las APIs y cómo lo hacen. Cada entrada corresponde a una entidad de la API de Meta Marketing. Según esta configuración, Cortex Framework crea DAG de Airflow que ejecutan canalizaciones de Dataflow para recuperar datos con las APIs de Meta Marketing.

El archivo src/Meta/src/raw/pipelines/config.ini controla parte del comportamiento del DAG de Cloud Composer y la forma en que se consumen las APIs de Meta Marketing. Encuentra las descripciones de cada parámetro en el archivo.

Los siguientes parámetros controlan la configuración de Source to Raw para cada entrada:

Parámetro Descripción
base_table Tabla del conjunto de datos sin procesar en la que se almacenan los datos recuperados (por ejemplo, customer).
load_frequency Frecuencia con la que se ejecuta un DAG para recuperar datos de Meta. Para obtener más información sobre los valores posibles, consulta la documentación de Airflow.
object_endpoint Ruta de extremo de API (por ejemplo, campaigns para el extremo /{account_id}/campaigns)
entity_type Tipo de tabla (debe ser uno de los siguientes: fact, dimension o addaccount))
object_id_column Columnas (separadas por comas) que forman un registro único para esta tabla. Solo se requiere cuando entity_type es fact.
breakdowns Opcional: Columnas de desglose (separadas por comas) para los extremos de Insights. Solo se aplica cuando entity_type es fact.
action_breakdowns Opcional: Columnas de desglose de acciones (separadas por comas) para los extremos de Insights. Solo se aplica cuando entity_type es fact.
partition_details Opcional: Si deseas que esta tabla se particione por motivos de rendimiento. Para obtener más información, consulta Partición de tablas.
cluster_details Opcional: Si deseas que esta tabla se agrupe para tener en cuenta el rendimiento. Para obtener más información, consulta Configuración del clúster.

Tablas sin procesar a CDC

En esta sección, se describen las entradas que controlan cómo se transfieren los datos de las tablas sin procesar a las tablas de CDC. Cada entrada corresponde a una tabla sin procesar (que, a su vez, corresponde a una entidad de la API de Meta, como se mencionó).

Los siguientes parámetros controlan la configuración de Raw to CDC para cada entrada:

Parámetro Descripción
base_table Tabla en la que se replicaron los datos sin procesar. Una tabla con el mismo nombre en el conjunto de datos de CDC almacena los datos sin procesar después de la transformación de CDC (por ejemplo, campaign_insights).
row_identifiers Columnas (separadas por comas) que forman un registro único para esta tabla.
load_frequency Frecuencia con la que se ejecuta un DAG para esta entidad con el objetivo de completar la tabla del CDC. Para obtener más información sobre los valores posibles, consulta la documentación de Airflow.
partition_details Opcional: Si deseas que esta tabla se particione por motivos de rendimiento. Para obtener más información, consulta Partición de tablas.
cluster_details Opcional: Si deseas que esta tabla se agrupe en clústeres por motivos de rendimiento. Para obtener más información, consulta Configuración del clúster.

Esquema de la tabla de CDC

En el caso de Meta, todos los campos se almacenan en formato de cadena en la capa sin procesar. En la capa de CDC, los tipos primitivos se convierten en tipos de datos comerciales pertinentes, y todos los tipos complejos se almacenan en formato JSON de BigQuery.

Para habilitar esta conversión, el directorio src/Meta/config/table_schema contiene un archivo de esquema para cada entidad especificada en la sección raw_to_cdc_tables, que explica cómo traducir correctamente cada tabla BigQueryraw en una tabla de CDC.

Cada archivo de esquema contiene tres columnas:

  • SourceField: Es el nombre del campo de la tabla sin procesar para esta entidad.
  • TargetField: Es el nombre de la columna en la tabla de CDC para esta entidad.
  • DataType: Es el tipo de datos de cada campo de la tabla de CDC.

Configuración de informes

Puedes configurar y controlar cómo Cortex genera datos para la capa de informes final de Meta con el archivo de configuración de informes (src/Meta/config/reporting_settings.yaml). Este archivo controla cómo se generan los objetos de BigQuery de la capa de informes (tablas, vistas, funciones o procedimientos almacenados).

Para obtener más información, consulta Cómo personalizar el archivo de configuración de informes.

Próximos pasos