Usar paquetes de JavaScript

En este documento se explica cómo hacer lo siguiente:

Antes de empezar

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

    Ir a Dataform

  2. Realice una o ambas de las siguientes acciones:

    1. Para instalar un paquete en un repositorio o autenticar un paquete NPM privado para habilitar su instalación, sigue estos pasos:
      1. Seleccione o cree un repositorio.
      2. Seleccione o cree un espacio de trabajo de desarrollo.
      3. Opcional: Para instalar un paquete privado, autentica el paquete privado.
      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. El nombre del repositorio debe coincidir con el nombre del 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 que tienes 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, pide a tu administrador que te conceda los siguientes roles de IAM:

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Instalar un paquete

En esta sección se muestra cómo instalar un paquete de JavaScript e importarlo a un archivo de JavaScript y a un archivo SQLX para poder usar el paquete y 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:

Después, 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:

Añadir un paquete como dependencia

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

  1. En el panel Archivos de tu espacio de trabajo, selecciona package.json.

  2. Añade el paquete al bloque dependencies:

    1. Añade un paquete NPM público publicado con el siguiente formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Haz los cambios siguientes:

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

    2. Añade un paquete NPM público no publicado con el siguiente formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Haz los cambios siguientes:

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

    3. Añade un paquete NPM privado autenticado con el siguiente formato:

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

      Haz los cambios siguientes:

      • REGISTRY-SCOPE con el nombre del paquete. REGISTRY-SCOPE debe coincidir con el ámbito del registro definido en el archivo .nmprc de tu repositorio.
      • PACKAGE-NAME con 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 Instalar paquetes.

  4. Confirma y envía los cambios.

En el siguiente código de ejemplo se muestra el paquete de dimensiones de cambio lento de código abierto público añadido 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"
   }
 }
 ```

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

Para usar una función o una constante de un paquete en un archivo JavaScript de 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 Archivos, selecciona un archivo .js en el que quieras 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. Sustituye EXPORT-NAME por el nombre de la función o la constante que quieras usar, declarada en module.exports en el archivo de paquete index.js.
    2. Sustituye PACKAGE-NAME por el nombre del paquete que quieras usar.

  3. Confirma y envía los cambios.

En el siguiente ejemplo 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();

Importar 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 Archivos, 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. Sustituye CONSTANT-NAME por el nombre de la constante.
    2. Sustituye PACKAGE-NAME por el nombre del paquete que quieras usar.

  3. Confirma y envía los cambios.

En el siguiente ejemplo 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();

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

Para usar una función o una constante de un paquete en 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 Archivos, selecciona un archivo .sqlx en el que quieras usar el paquete.

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

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

  3. Confirma y envía los cambios.

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

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

config {
    type: "table",
}

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

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

Importar 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 Archivos, selecciona un archivo .sqlx en el que quieras usar el paquete.

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

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Sustituye CONSTANT-NAME por el nombre de la constante.
    2. Sustituye PACKAGE-NAME por el nombre del paquete que quieras usar.

  3. Confirma y envía los cambios.

En el siguiente ejemplo de código se muestra el paquete postoffice importado en un bloque js y su función getDomain usada en una instrucción 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

Autenticar un paquete privado

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

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

Autenticar el primer paquete privado en un repositorio de Dataform

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

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

    1. Añade 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 único secreto de tu repositorio. Debes crear un secreto específico para cada repositorio de Dataform. El secreto debe estar en formato JSON.

  2. Sube el secreto al repositorio de Dataform.

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

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

Una vez que hayas autenticado el paquete NPM privado, podrás instalar el paquete en el repositorio de Dataform.

Crear un secreto para autenticar paquetes privados

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

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

  1. En Secret Manager, crea un secreto.

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

    Haz los cambios siguientes:

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

  2. Concede 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 concedas acceso, asegúrate de asignar el rol roles/secretmanager.secretAccessor a tu cuenta de servicio de Dataform.

Subir el secreto para autenticar paquetes privados a un repositorio de Dataform

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

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

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

    Ir a Dataform

  2. Selecciona el repositorio en el que quieras instalar paquetes NPM privados.

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

  4. En el panel Añadir token secreto de paquete de NPM, en el menú Secreto, selecciona el secreto que contenga los tokens de autenticación de los paquetes de NPM privados.

  5. Haz clic en Guardar.

Crear un archivo .npmrc para autenticar paquetes privados

Para autenticar paquetes NPM privados en un repositorio de Dataform, debes crear un archivo .npmrc de nivel superior en el repositorio. Debes almacenar tokens de autenticación de todos los paquetes privados de npm que se vayan a instalar 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 Google Cloud consola, ve a la página Dataform.

    Ir a Dataform

  2. Selecciona el repositorio en el que quieras instalar paquetes NPM privados y, a continuación, selecciona un espacio de trabajo.

  3. En el panel Archivos, haz clic en Más y, a continuación, en Crear archivo.

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

    1. En el campo Añadir una ruta de archivo, introduce .npmrc.

    2. Haz clic en Crear archivo.

Añadir un token de autenticación al archivo .npmrc de un repositorio de Dataform

Para autenticar un paquete NPM privado en un repositorio de Dataform que ya contenga un secreto con tokens de autenticación de paquetes y un archivo .npmrc, debes añadir el token de autenticación del paquete privado al archivo .npmrc del repositorio.

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

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

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

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

    Ir a Dataform

  2. Selecciona el repositorio en el que quieras instalar paquetes NPM privados y, a continuación, selecciona un espacio de trabajo.

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

  4. En el archivo .npmrc, define el ámbito del registro de NPM y el token de autenticación del paquete privado con el siguiente formato:

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

    Haz los cambios siguientes:

    • REGISTRY-SCOPE: el ámbito del registro de NPM al que quieres aplicar el token de autenticación.
    • NPM-REGISTRY-URL: la URL de tu registro de NPM. Por ejemplo, https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN: el token de autenticación del paquete de 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 añadir los corchetes de apertura ${ y de cierre }.

    Puedes introducir varios tokens de autenticación.

En el siguiente ejemplo de código se muestra un token de autenticación de un paquete privado de npm añadido al archivo .npmrc de un repositorio de Dataform:

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

Autenticar un paquete privado posterior en un repositorio de Dataform

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

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

  2. Añade una nueva versión al secreto.

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

    1. Añade el token de autenticación del paquete privado al valor secreto con el siguiente formato:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Haz los cambios siguientes:

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

    Puedes añadir varios tokens de autenticación a la vez.

  3. En Dataform, añade el token de autenticación al archivo .npmrc de tu repositorio.

Una vez que hayas autenticado el paquete NPM privado, podrás instalar el paquete en el repositorio de Dataform.

Crear un paquete

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

Para crear un paquete que puedas reutilizar 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 en otros repositorios de Dataform.

A continuación, debes crear un archivo index.js de nivel superior y añadirle el contenido del paquete exportable, como funciones y constantes. Para ver un ejemplo de un paquete creado en Dataform, consulta dataform-package-base en GitHub.

Una vez que hayas creado el paquete, podrás instalarlo en otro repositorio de Dataform 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 funciones y constantes de JavaScript en un único repositorio de Dataform con includes. Para obtener más información, consulta Reutilizar variables y funciones con includes en Dataform.

Para crear tu propio paquete con código JavaScript que puedas reutilizar en Dataform, sigue estos pasos en tu espacio de trabajo:

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

  2. Haz clic en Crear archivo.

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

    2. En el campo Añadir una ruta de archivo, introduce index.js.

    3. Haz clic en Crear archivo.

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

    1. Crea constantes con el siguiente formato:

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

      Haz los cambios siguientes:

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

    2. Crea funciones con el siguiente formato:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Haz los cambios siguientes:

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

  4. Opcional: Haz clic en Formato.

  5. Opcional: En el directorio definitions, añade el código del paquete que no se exportará.

  6. Confirma y envía los cambios.

En el siguiente ejemplo de código de 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 }

Siguientes pasos