Implementa una solución de integración sin servidores basada en Cloud Functions y Pub/Sub

En este instructivo, se muestra cómo configurar y probar una solución de integración de datos basada en los conceptos descritos en Una solución de integración sin servidores para Google Marketing Platform.

Se encuentra disponible una demostración de esta solución sin servidores en una demostración de código abierto en GitHub. Con la solución, se incluyen API y una secuencia de comandos de shell que te ayudará a configurar la solución en Google Cloud.

Este instructivo está dirigido a arquitectos o ingenieros de datos que quieran automatizar la integración de datos en sistemas de destino mediante API o mediante otras opciones de integración programática, como la carga de SFTP.

Objetivos

  • Implementar una solución de integración sin servidores
  • Configurar una integración en los sistemas de destino de las API de destino
  • Probar esta solución mediante la carga de un archivo CSV en Hojas de cálculo de Google

Costos

En este instructivo, se usan los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud sean aptos para obtener una prueba gratuita.

Cuando finalices este instructivo, podrás borrar los recursos creados para evitar que se te siga facturando. Para obtener más información, consulta cómo hacer una limpieza.

Antes de comenzar

  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir a la página del selector de proyectos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

  4. Abre Cloud Shell
    5. Abrir Cloud Shell

Instala la solución

  1. En Cloud Shell, clona el repositorio que contiene el código que usarás para este instructivo:

    git clone https://github.com/GoogleCloudPlatform/cloud-for-marketing.git

  2. Ejecuta la secuencia de comandos de instalación:

    cd cloud-for-marketing/marketing-analytics/activation/gmp-googleads-connector; chmod a+x deploy.sh; ./deploy.sh

    La secuencia de comandos ejecuta una serie de procesos, como la verificación del entorno y la compilación de dependencias.

  3. Cuando se te solicite, ingresa el ID del proyecto de Cloud que deseas usar para este instructivo.

  4. Selecciona la región en la que deseas implementar tu función de Cloud Functions y almacenar tus datos de Cloud Storage, por ejemplo, us-east1.

  5. Selecciona las API integradas que deseas usar o presiona Enter para seleccionarlas todas. Con esta solución, se incluyen las siguientes API de destino:

    • Protocolo de medición de Google Analytics
    • API de administración de Google Analytics (importación de datos)
    • Carga de las conversiones de Campaign Manager
    • Carga de SFTP para las cargas de datos de la empresa en Search Ads 360
    • API de Hojas de cálculo de Google para las cargas programadas de las conversiones de Google Ads basadas en Hojas de cálculo de Google
    • Carga de las conversiones de Search Ads 360

    Incluye la API de Hojas de cálculo de Google, ya que, después de la instalación, ejecutarás una prueba que la requiere. Se realiza una verificación a fin de determinar si están presentes los permisos necesarios para realizar la instalación. Si esta verificación falla, deberás solicitar los permisos faltantes a tu administrador y, luego, volver a ejecutar la secuencia de comandos.

  6. Ingresa un nombre para el bucket de Cloud Storage que almacena tus datos. Si el bucket no existe, selecciona una región para que la secuencia de comandos lo cree. (Sugerimos que uses la región predeterminada, que coincide con la región en la que se implementarán las funciones de Cloud Functions).

  7. Ingresa una carpeta de Cloud Storage que supervise esta solución o presiona Enter para seleccionar la carpeta predeterminada.

  8. Ingresa un prefijo para las suscripciones y los temas de Pub/Sub o presiona Enter si deseas usar el prefijo predeterminado.

  9. Cuando se te solicite, escribe Y para confirmar y guardar la configuración en un archivo config.json.

    Ya se crearon las suscripciones y los temas de Pub/Sub.

  10. Si se requiere una cuenta de servicio para las API que habilitaste, ingresa el nombre de una cuenta de servicio y, luego, confirma que deseas descargar el archivo de claves.

  11. Después de que las funciones de Cloud Functions se implementen de forma automática, la secuencia de comandos indicará si está lista la instancia de Firestore o de Datastore. Si no está lista, imprime las instrucciones para iniciar Firestore.

Prepara los datos

Ahora que ya instalaste la solución, puedes preparar tus datos para el sistema de destino.

Formatos de archivo

Las API integradas en esta solución requieren formatos de archivo específicos en algunos casos:

  • La carga de SFTP no solicita ningún formato en particular. Esta integración sube el archivo al servidor por medio de SFTP, sin importar el formato de archivo.
  • La API de administración de Google Analytics (Importación de datos) y las API de Hojas de cálculo de Google requieren archivos CSV.
  • Para todas las demás API, el sistema exige el formato JSON delimitado por saltos de línea (NDJSON). Cada línea es una string JSON válida. Por ver un ejemplo, consulta los formatos de exportación de BigQuery.

Configuración de las API

Las distintas API tienen distintos parámetros de configuración. Una misma API puede tener más de un parámetro de configuración para distintos usos. Por lo tanto, los parámetros de configuración se agrupan por API y combinan un solo objeto JSON en el archivo config_api.json. En la siguiente lista del archivo de plantilla JSON del repositorio de GitHub para este instructivo, se muestra cómo se organizan los parámetros de configuración.

marketing-analytics/activation/gmp-googleads-connector/config_api.json.template
{
  "CM": {
    "foo": {
      "cmAccountId": "[YOUR-DCM-ACCOUNT-ID]",
      "cmConfig": {
        "idType": "encryptedUserId",
        "conversion": {
          "floodlightConfigurationId": "[YOUR-FL-CONFIG-ID]",
          "floodlightActivityId": "[YOUR-FL-ACTIVITY-ID]",
          "quantity": 1
        },
        "customVariables": [
          "[YOUR-U-VARIABLES-NAME-1]", "[YOUR-U-VARIABLES-NAME-2]"
        ],
        "encryptionInfo": {
          "encryptionEntityId": "[YOUR-ENCRYPTION-ID]",
          "encryptionEntityType": "DCM_ADVERTISER",
          "encryptionSource": "AD_SERVING"
        }
      }
    }
  },
  "GA": {
    "bar": {
      "dataImportHeader": "[YOUR-DATA-IMPORT-HEADER]",
      "gaConfig": {
        "accountId": "[YOUR-GA-ACCOUNT-ID]",
        "webPropertyId": "[YOUR-WEB-PROPERTY-ID]",
        "customDataSourceId": "[YOUR-CUSTOM-DATASOURCE-ID]"
      }
    }
  },
  "MP": {
    "baz": {
      "mpConfig":{
        "v": "1",
        "t": "transaction",
        "ni": "1",
        "dl": "[YOUR-SOMETHING-URL]",
        "tid": "[YOUR-WEB-PROPERTY-ID]"
      }
    }
  },
  "SFTP": {
    "qux": {
      "sftp":{
        "host": "[YOUR-SFTP-HOST]",
        "port": "[YOUR-SFTP-PORT]",
        "username": "[YOUR-SFTP-USERNAME]",
        "password": "[YOUR-SFTP-PASSWORD]"
      }
    }
  },
  "GS": {
    "foo": {
      "spreadsheetId": "[YOUR-SPREADSHEET-ID]",
      "sheetName": "[YOUR-SHEET-NAME]",
      "sheetHeader": "[ANYTHING-PUT-AHEAD-OF-CSV]",
      "pasteData": {
        "coordinate": {
          "rowIndex": 0,
          "columnIndex": 0
        },
        "delimiter": ","
      }
    }
  },
  "SA": {
    "bar": {
      "saConfig": {
        "currencyCode": "[YOUR-CURRENCY-CODE]",
        "type": "TRANSACTION",
        "segmentationType": "FLOODLIGHT",
        "segmentationId": "[YOUR-SEGMENTATION-ID]",
        "state": "ACTIVE"
      },
      "availabilities": [
        {
          "agencyId": "[YOUR-AGENCY-ID]",
          "advertiserId": "[YOUR-ADVERTISER-ID]",
          "segmentationType": "FLOODLIGHT",
          "segmentationId": "[YOUR-SEGMENTATION-ID]"
        }
      ]
    }
  },
  "ACLC": {
    "foo" : {
      "customerId": "[YOUR-GOOGLE-ADS-ACCOUNT-ID]",
      "loginCustomerId": "[YOUR-LOGIN-GOOGLE-ADS-ACCOUNT-ID]",
      "developerToken": "[YOUR-GOOGLE-ADS-DEV-TOKEN]",
      "adsConfig": {
        "conversion_action": "[YOUR-CONVERSION-ACTION-NAME]",
        "conversion_value": "[YOUR-CONVERSION-VALUE]",
        "currency_code": "[YOUR-CURRENCY-CODE]"
      }
    }
  }
}

Puedes cambiar el nombre del archivo de plantilla a config_api.json, dejar solo las secciones de API de destino y editar los detalles de la configuración. Si tienes más de una configuración, cópialas y asígnales nombres diferentes. Después de esto, actualiza los parámetros de configuración en Firestore:

./deploy.sh update_api_config

Convención para los nombres de archivos

Con el fin de lograr cierta flexibilidad en los diferentes tipos de API y de parámetros de configuración, adoptamos una convención para asignar nombres a los archivos entrantes en esta solución. Los nombres de archivo deben contener el patrón API[X] y config[Y].

  • X representa los códigos de las API de destino. En esta solución, X podría ser cualquiera de las siguientes opciones:
    • MP: Protocolo de medición de Google Analytics
    • GA: API de administración de Google Analytics (Importación de datos)
    • CM: API de tráfico y de informes de DFA y DCM
    • SFTP: Carga de SFTP
    • GS: API de Hojas de cálculo de Google
    • SA: API de Search Ads 360
  • Y es el nombre de la configuración, por ejemplo, foo o bar en el código de la plantilla.

Por ejemplo, un archivo llamado API[GA]_config[bar]_20191111.csv indica lo siguiente:

  • [GA] significa que Google Analytics es el sistema de destino y que Importación de datos es la API de destino.
  • [bar] significa que el archivo se envía al sistema de destino mediante el uso de la clave bar de un objeto JSON almacenado en el archivo de configuración de la plantilla.

Entre los patrones opcionales para los nombres de archivos se incluyen los siguientes:

  • Si el nombre de archivo contiene dryrun, se siguen todos los pasos en el proceso, pero no se envían los datos al servidor de la API.
  • Si el nombre de archivo contiene _size[Z] o _size[Zmb], el archivo entrante se divide en varios archivos. Los tamaños de archivo que son inferiores a Z MB en Cloud Storage cumplen con el límite de tamaño de archivos de algunas API. Por ejemplo, la Importación de datos tiene un límite de 1 GB.

Por ejemplo, un archivo llamado API[GA]_config[bar]_dryrun_20191111.csv no se envía a Google Analytics, pero pasa por todo el sistema de integración. Un archivo llamado API[GA]_config[bar]_size[100]_20191111.csv se divide en un grupo de archivos con tamaños que no superan los 100 MB, y cada archivo se envía de forma individual a Google Analytics a través de la Importación de datos.

Prueba la solución

Después de instalar la solución, debes probar una integración mediante la creación de un archivo CSV y la carga automática de los datos de ese archivo en una hoja de cálculo de Google de destino.

Otorga permiso a la cuenta de servicio

  1. Crea una hoja de cálculo de Google nueva y, luego, cámbiale el nombre, por ejemplo, Integration Test.
  2. Haz clic en Compartir.

  3. En Cloud Shell, obtén la dirección de correo electrónico de la cuenta de servicio que usaste durante los pasos de instalación:

    ./deploy.sh print_service_account

  4. En el campo People, copia la dirección de correo electrónico de la cuenta de servicio y, luego, selecciona  Can edit para asignarle los permisos de editor.

Obtén el ID de la hoja de cálculo de destino

  • Copia el ID de la hoja de cálculo de Google de destino.

    El ID de la hoja de cálculo es el valor que se encuentra entre /d/ y /edit en la URL de la hoja de cálculo, por ejemplo, spreadsheetId en el siguiente ejemplo:

    https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0

Actualiza la configuración de la API

  1. En Cloud Shell, ve a la carpeta en la que instalaste la solución, por ejemplo, ~/cloud-for-marketing/marketing-analytics/activation/gmp-googleads-connector.

  2. Abre el archivo JSON llamado config_api.json y reemplaza el contenido por el siguiente código:

    {
  "GS": {
    "foo": {
      "spreadsheetId": "your-spreadsheet-id",
      "sheetName": "your-sheet-name",
      "sheetHeader": "This is a test integration",
      "pasteData": {
        "coordinate": {
          "rowIndex": 0,
          "columnIndex": 0
        },
        "delimiter": ","
      }
    }
  }
}

    Reemplaza lo siguiente:

    • your-spreadsheet-id: Es el ID de la hoja de cálculo.
    • your-sheet-name: Es el nombre de la hoja de cálculo de Google de destino.

  3. Sube la configuración a Firestore o a Datastore:

    ./deploy.sh update_api_config

    Este es el resultado:

    Init ApiConfig based on Datastore.
  Import Config for API[GS]_config[foo]

Prepara los archivos que deseas enviar

En esta prueba, deberás cargar los datos de tu archivo CSV en la hoja de cálculo de destino.

  • En Cloud Shell, crea un archivo CSV con el contenido de algunas API integradas:

    cat > API[GS]_config[foo]_test.csv <<EOF
#What are Tentacles built in APIs
Target System, Target API, Code
Google Analytics, Measurement Protocol, MP
Google Analytics, Google Analytics Management API, GA
Campaign Manager, DCM/DFA Reporting and Trafficking API, CM
Search Ads 360, SFTP, SFTP
EOF

Sube el archivo a Cloud Storage

  • Sube el archivo al bucket de Cloud Storage:

    ./deploy.sh copy_file_to_gcs API[GS]_config[foo]_test.csv

    El resultado es similar a este:

    Copy integration data file to target folder…
Copying file:...
  Operation completed over...

Verifica el resultado

  • Abre la hoja de cálculo de Google que creaste antes.

    Se cambió el tamaño del archivo Sheet1 y se cargaron en este los datos del archivo CSV.

    Captura de pantalla en la que se muestran los datos subidos a una hoja de cálculo de Google

Realiza una limpieza

La manera más fácil de eliminar la facturación es borrar el proyecto que creaste para el instructivo.

  1. En Cloud Console, ve a la página Administrar recursos.

    Ir a Administrar recursos

  2. En la lista de proyectos, elige el proyecto que quieres borrar y haz clic en Borrar.
  3. En el diálogo, escribe el ID del proyecto y, luego, haz clic en Cerrar para borrar el proyecto.

¿Qué sigue?