Usa paquetes de JavaScript

Este documento te muestra cómo hacer lo siguiente:

Antes de comenzar

  1. En la consola de Google Cloud, ve a la página Dataform.

    Ir a Dataform

  2. Realiza una de las siguientes acciones o ambas:

    1. Para instalar un paquete en un repositorio o autenticar un paquete NPM privado para habilitar su instalación, sigue estos pasos:
      1. Selecciona o crea un repositorio.
      2. Selecciona o crea un lugar de trabajo de desarrollo.
      3. Opcional: Para instalar un paquete privado, autenticarlo.
      4. Si tu repositorio no contiene un archivo package.json, crea package.json y mueve el paquete principal de Dataform.
    2. Para crear un paquete, sigue estos pasos:
      1. Crea un repositorio de Dataform dedicado a tu paquete. Haz que el nombre del repositorio coincida con el nombre de tu paquete.
      2. Conecta el repositorio a un repositorio de Git de terceros que alojará tu paquete.
      3. Crea e inicializa un espacio de trabajo en el repositorio de Dataform.

  3. Asegúrate de tener los permisos necesarios para completar las tareas de este documento.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Instala un paquete

En esta sección, se muestra cómo instalar un paquete de JavaScript y, luego, importarlo a un archivo de JavaScript y a un archivo SQLX para que puedas usarlo para desarrollar flujos de trabajo en Dataform.

Para usar un paquete en Dataform, debes instalarlo en tu repositorio.

Puedes instalar los siguientes tipos de paquetes en Dataform:

Luego, para usar el paquete en un archivo JavaScript o SQLX, debes importar el contenido seleccionado del paquete al archivo. También puedes importar un paquete completo a un archivo JavaScript o SQLX en lugar de su contenido seleccionado.

Para evitar problemas con la instalación de paquetes en tu entorno de producción, te recomendamos que hagas lo siguiente:

  • Especifica de forma explícita la versión del paquete en package.json, por ejemplo, 3.0.0. No uses otras opciones dependencies de package.json, por ejemplo, >version.

  • Probar versiones nuevas de paquetes en un entorno que no sea de producción Para obtener más información sobre la configuración de diferentes entornos de ciclo de vida del código, consulta Cómo administrar el ciclo de vida del código.

Agrega un paquete como dependencia

Para instalar un paquete dentro de un repositorio de Dataform, debes añadirlo como una dependencia en el archivo package.json:

  1. En tu lugar de trabajo, en el panel Files, selecciona package.json.

  2. Agrega el paquete al bloque dependencies:

    1. Agrega un paquete público de NPM publicado con el siguiente formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Reemplaza lo siguiente:

      • PACKAGE-NAME por el nombre del paquete.
      • PACKAGE-VERSION con la versión más reciente del paquete público de NPM publicado. Para evitar problemas con la instalación del paquete, especifica la versión de forma explícita, por ejemplo, 3.0.0.

    2. Agrega un paquete público de NPM no publicado con el siguiente formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Reemplaza lo siguiente:

      • PACKAGE-NAME por el nombre del paquete.
      • PACKAGE-URL con la URL tar.gz del repositorio de paquetes de terceros, por ejemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Agrega un paquete NPM privado autenticado en el siguiente formato:

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"

      Reemplaza lo siguiente:

      • REGISTRY-SCOPE por el nombre del paquete. REGISTRY-SCOPE debe coincidir con el alcance del registro definido en el archivo .nmprc de tu repositorio.
      • PACKAGE-NAME por el nombre del paquete.
      • PACKAGE-URL con la URL tar.gz del repositorio de paquetes, por ejemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Haz clic en Install packages.

  4. Confirma y envía los cambios.

En la siguiente muestra de código, se muestra el paquete público de código abierto de dimensiones que cambian lentamente agregado al archivo .package.json:

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

Importa una función o constante de paquete a un archivo JavaScript en Dataform

Para usar una función o una constante de un paquete dentro de un archivo JavaScript en Dataform, primero debes importarla al archivo.

Para importar una función o una constante de un paquete a un archivo JavaScript, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Files, selecciona un archivo .js en el que deseas usar el paquete.

  2. En el archivo, importa una función o una constante con el siguiente formato:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Reemplaza EXPORT-NAME por el nombre de la función o constante que deseas usar, declarado en module.exports en el archivo index.js del paquete.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En la siguiente muestra de código, se muestra la función getDomain del paquete postoffice importada y usada en un archivo JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

Importa un paquete completo a un archivo JavaScript en Dataform

Para importar todo el paquete a un archivo JavaScript en lugar de importar funciones o constantes seleccionadas a un archivo JavaScript, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Files, selecciona un archivo .js en el que quieras usar el paquete.

  2. En el archivo, importa el paquete con el siguiente formato:

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Reemplaza CONSTANT-NAME por un nombre para la constante.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En la siguiente muestra de código, se muestra la función getDomain del paquete postoffice importado que se usa en un archivo JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

Importa una función o constante de paquete a un archivo SQLX en Dataform

Para usar una función o una constante de un paquete dentro de un archivo SQLX, primero debes importarla al archivo.

Para importar una función o una constante de un paquete a un archivo SQLX, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Files, selecciona un archivo .sqlx en el que quieras usar el paquete.

  2. En el archivo, ingresa el siguiente bloque js:

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Reemplaza EXPORT-NAME por el nombre de la función o constante que deseas usar, declarado en module.exports en el archivo index.js del paquete.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En la siguiente muestra de código, se muestra la función getDomain del paquete postoffice importada en un bloque js y utilizada en una sentencia SELECT en un archivo SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

Importa un paquete completo a un archivo SQLX en Dataform

Para importar todo el paquete a un archivo SQLX en lugar de importar funciones o constantes seleccionadas a un archivo JavaScript, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Files, selecciona un archivo .sqlx en el que deseas usar el paquete.

  2. En el archivo, importa el paquete con el siguiente formato:

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Reemplaza CONSTANT-NAME por un nombre para la constante.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En la siguiente muestra de código, se muestra el paquete postoffice importado en un bloque js y su función getDomain que se usa en una sentencia SELECT en un archivo SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

Cómo autenticar un paquete privado

En esta sección, se muestra cómo autenticar un paquete de NPM privado en Dataform para habilitar su instalación en un repositorio de Dataform.

Para instalar un paquete de NPM privado en un repositorio de Dataform y usarlo para desarrollar tu flujo de trabajo, primero debes autenticarlo en Dataform. El proceso de autenticación es diferente para el primer paquete privado en un repositorio y un paquete privado posterior en un repositorio.

Cómo autenticar el primer paquete privado en un repositorio de Dataform

Para autenticar paquetes privados de NPM en Dataform, debes hacer lo siguiente antes de instalar el primer paquete privado de NPM en un repositorio de Dataform:

  1. Crea un secreto de Secret Manager dedicado a almacenar tokens de autenticación de paquetes privados de NPM en el repositorio de Dataform.

    1. Agrega el token de autenticación del paquete, obtenido de tu registro de NPM, al secreto.

    Debes almacenar todos los tokens de autenticación de los paquetes privados de NPM en un solo Secret de tu repositorio. Debes crear un secreto dedicado por repositorio de Dataform. El Secret debe estar en formato JSON.

  2. Sube el secreto al repositorio de Dataform.

  3. Crea un archivo .npmrc y agrega el token de autenticación del paquete al archivo.

    El token de autenticación en el archivo .npmrc debe coincidir con el token de autenticación en el secreto subido.

Después de autenticar el paquete privado de NPM, puedes instalarlo en el repositorio de Dataform.

Crea un secreto para la autenticación de paquetes privados

Para autenticar paquetes privados de NPM en un repositorio de Dataform, debes crear un Secret de Secret Manager y definir tokens de autenticación para todos los paquetes privados que deseas instalar en el repositorio de Dataform dentro del Secret. Define un token de autenticación para cada paquete privado de NPM y almacena todos los tokens de autenticación en un solo Secret para cada repositorio. El Secret debe estar en formato JSON.

Para crear un secreto con tokens de autenticación para paquetes privados de NPM, sigue estos pasos:

  1. En Secret Manager, crea un secreto.

    1. En el campo Valor del secreto, ingresa uno o varios tokens de autenticación en el siguiente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Reemplaza lo siguiente:

    • AUTHENTICATION_TOKEN_NAME: Es un nombre único para el token que identifica el paquete que autentica.
    • TOKEN_VALUE: Es el valor del token de autenticación, que se obtiene de tu registro de NPM.

  2. Otorga acceso al secreto a tu cuenta de servicio de Dataform.

    Tu cuenta de servicio de Dataform tiene el siguiente formato:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Cuando otorgues acceso, asegúrate de otorgar el rol roles/secretmanager.secretAccessor a tu cuenta de servicio de Dataform.

Sube el secreto para la autenticación de paquetes privados a un repositorio de Dataform

Antes de instalar un paquete NPM privado en un repositorio de Dataform por primera vez, sube el secreto que contiene el token de autenticación del paquete al repositorio.

Para subir el Secret con tokens de autenticación de paquetes privados de NPM a un repositorio de Dataform, sigue estos pasos:

  1. En la consola de Google Cloud, ve a la página Dataform.

    Ir a Dataform

  2. Selecciona el repositorio en el que deseas instalar paquetes privados de NPM.

  3. En la página del repositorio, haz clic en Configuración > Configurar paquetes privados de NPM.

  4. En el panel Agregar token para secreto del paquete de npm, en el menú Secreto, selecciona el secreto que contiene los tokens de autenticación para los paquetes privados de NPM.

  5. Haz clic en Guardar.

Crea un archivo .npmrc para la autenticación de paquetes privados

Para autenticar paquetes privados de NPM en un repositorio de Dataform, debes crear un archivo .npmrc de nivel superior en el repositorio. Debes almacenar los tokens de autenticación para que todos los paquetes privados de NPM se instalen en el repositorio dentro del archivo .npmrc. Los tokens de autenticación del archivo .npmrc deben coincidir con los tokens de autenticación del secreto subido al repositorio. Para obtener más información sobre los archivos .npmrc, consulta la documentación de npmrc.

Para crear un archivo .npmrc de nivel superior en tu repositorio, sigue estos pasos:

  1. En la consola de Google Cloud, ve a la página Dataform.

    Ir a Dataform

  2. Selecciona el repositorio en el que deseas instalar paquetes privados de NPM y, luego, selecciona un lugar de trabajo.

  3. En el panel Archivos, haz clic en Más y, luego, en Crear archivo.

  4. En el panel Crear un archivo nuevo, haz lo siguiente:

    1. En el campo Agregar una ruta de acceso al archivo, ingresa .npmrc.

    2. Haz clic en Crear archivo.

Agrega un token de autenticación al archivo .npmrc en un repositorio de Dataform

Para autenticar un paquete privado de NPM en un repositorio de Dataform que ya contiene un Secret con tokens de autenticación de paquetes y un archivo .npmrc, debes agregar el token de autenticación del paquete privado al archivo .npmrc del repositorio.

En el archivo .npmrc, debes definir el alcance de tu registro de NPM y agregar el token de autenticación para el paquete privado al que se accede en ese alcance. Para obtener más información sobre los archivos .npmrc, consulta la documentación de npmrc.

El token de autenticación en el archivo .npmrc debe coincidir con el token de autenticación en el secreto subido al repositorio.

Para agregar un token de autenticación al archivo .npmrc en un repositorio de Dataform, sigue estos pasos:

  1. En la consola de Google Cloud, ve a la página Dataform.

    Ir a Dataform

  2. Selecciona el repositorio en el que deseas instalar paquetes privados de NPM y, luego, selecciona un lugar de trabajo.

  3. En el panel Files, selecciona el archivo .npmrc.

  4. En el archivo .npmrc, define el alcance del registro de NPM y el token de autenticación para el paquete privado en el siguiente formato:

    @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN

    Reemplaza lo siguiente:

    • REGISTRY-SCOPE: Es el alcance del registro de NPM al que deseas aplicar el token de autenticación.
    • NPM-REGISTRY-URL: Es la URL de tu registro de NPM, por ejemplo, https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN: Es el token de autenticación del paquete NPM privado. El token de autenticación del archivo .npmrc debe coincidir con el token de autenticación del secreto subido. El token de autenticación se proporciona como una variable de entorno en el archivo .npmrc, así que asegúrate de agregar los paréntesis de apertura ${ y cierre }.

    Puedes ingresar varios tokens de autenticación.

En la siguiente muestra de código, se muestra un token de autenticación para un paquete NPM privado que se agregó al archivo .npmrc en un repositorio de Dataform:

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

Cómo autenticar un paquete privado posterior en un repositorio de Dataform

Para autenticar un paquete NPM privado en un repositorio de Dataform que ya contiene un Secret con tokens de autenticación de paquetes y un archivo .npmrc, sigue estos pasos:

  1. En Secret Manager, muestra los secretos y selecciona el secreto que almacena los tokens de autenticación de los paquetes NPM privados de tu repositorio.

  2. Agrega una versión nueva al secreto.

    Dataform usa la versión más reciente del secreto de forma predeterminada.

    1. Agrega el token de autenticación del paquete privado al valor secreto en el siguiente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Reemplaza lo siguiente:

    • AUTHENTICATION_TOKEN_NAME: Es un nombre único para el token que identifica el paquete que autentica.
    • TOKEN_VALUE: Es el valor del token de autenticación, que se obtiene de tu registro de NPM.

    Puedes agregar varios tokens de autenticación a la vez.

  3. En Dataform, agrega el token de autenticación al archivo .npmrc en tu repositorio.

Después de autenticar el paquete privado de NPM, puedes instalarlo en el repositorio de Dataform.

Cómo crear un paquete

En esta sección, se muestra cómo crear un paquete personalizado de JavaScript que puedes usar para desarrollar flujos de trabajo en Dataform.

Para crear un paquete que puedas volver a usar en varios repositorios de Dataform, debes crear un repositorio de Dataform dedicado al paquete y conectarlo a un repositorio de Git de terceros para que esté disponible para otros repositorios de Dataform.

Luego, debes crear un archivo index.js de nivel superior y agregar el contenido del paquete exportable, como funciones y constantes, al archivo. Para ver un ejemplo de un paquete creado en Dataform, consulta dataform-package-base en GitHub.

Después de crear el paquete, puedes instalarlo en un repositorio de Dataform diferente y usar el contenido exportable del paquete, como constantes y funciones, para desarrollar flujos de trabajo.

Como alternativa a la creación de un paquete, puedes reutilizar las funciones y constantes de JavaScript en un solo repositorio de Dataform con inclusiones. Para obtener más información, consulta Cómo volver a usar variables y funciones con includes en Dataform.

Para crear tu propio paquete con código JavaScript que puedas volver a usar en Dataform, sigue estos pasos en tu lugar de trabajo:

  1. En el panel Archivos, haz clic en Más.

  2. Haz clic en Crear archivo.

    1. En el panel Crear un archivo nuevo, haz lo siguiente:

    2. En el campo Agregar una ruta de acceso al archivo, ingresa index.js.

    3. Haz clic en Crear archivo.

  3. En el archivo index.js, ingresa el código JavaScript que deseas que exporte tu paquete.

    1. Crea constantes en el siguiente formato:

      const CONSTANT_NAME = CONSTANT_VALUE;
module.exports = { CONSTANT_NAME };

      Reemplaza lo siguiente:

      • CONSTANT_NAME: Es el nombre de tu constante.
      • CONSTANT_VALUE: Es el valor de tu constante.

    2. Crea funciones con el siguiente formato:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Reemplaza lo siguiente:

      • FUNCTION_NAME: Es el nombre de tu función.
      • PARAMETERS: Son los parámetros de tu función.
      • FUNCTION_BODY: Es el código que deseas que ejecute la función.

  4. Opcional: Haz clic en Formato.

  5. Opcional: En el directorio definitions, agrega el código de tu paquete que no se exportará.

  6. Confirma y envía tus cambios.

En la siguiente muestra de código del paquete, se muestra el archivo index.js del paquete postoffice que exporta la función getDomain:

// filename index.js
// package name postoffice

const GENERIC_DOMAINS = "('samplemail.com','samplemail.co.uk','examplemailbox.com'";

function getDomain(email) {
  let cleanEmail = `trim(${email})`
  const domain = `substr(${cleanEmail}, strpos(${cleanEmail}, '@') + 1)`;
  return `case
            when ${domain} in ${common.GENERIC_DOMAINS} then ${cleanEmail}
            when ${domain} = "othermailbox.com" then "other.com"
            when ${domain} = "mailbox.com" then "mailbox.global"
            when ${domain} = "support.postman.com" then "postman.com"
            else ${domain}
          end`;
}

module.exports = { getDomain }

¿Qué sigue?