JavaScript-Pakete verwenden

Dieses Dokument enthält Anleitungen für folgende Aufgaben:

Hinweise

  1. Öffnen Sie in der Google Cloud Console die Seite Dataform.

    Zu Dataform

  2. Führen Sie eine oder beide der folgenden Aktionen aus:

    1. So installieren Sie ein Paket in einem Repository oder authentifizieren ein privates NPM-Paket, um die Installation zu ermöglichen:
      1. Wählen Sie ein Repository aus oder erstellen Sie eines.
      2. Wählen Sie einen Entwicklungsarbeitsbereich aus oder erstellen Sie einen.
      3. Optional: Wenn Sie ein privates Paket installieren möchten, authentifizieren Sie es.
      4. Wenn Ihr Repository keine package.json-Datei enthält, erstellen Sie package.json und verschieben Sie das Dataform-Kernpaket.
    2. So erstellen Sie ein Paket:
      1. Erstellen Sie ein Dataform-Repository, das Ihrem Paket gewidmet ist. Ordnen Sie dem Repository den Namen Ihres Pakets zu.
      2. Verbinden Sie das Repository mit einem Drittanbieter-Git-Repository, in dem Ihr Paket gehostet wird.
      3. Erstellen und initialisieren Sie einen Arbeitsbereich im Dataform-Repository.

  3. Prüfen Sie, ob Sie die erforderlichen Berechtigungen haben, um die Aufgaben in diesem Dokument ausführen zu können.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Aufgaben in diesem Dokument benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Paket installieren

In diesem Abschnitt erfahren Sie, wie Sie ein JavaScript-Paket installieren und in eine JavaScript-Datei und eine SQLX-Datei importieren, damit Sie das Paket zum Entwickeln von Workflows in Dataform verwenden können.

Wenn Sie ein Paket in Dataform verwenden möchten, müssen Sie es in Ihrem Repository installieren.

Sie können die folgenden Pakettypen in Dataform installieren:

Wenn Sie das Paket dann in einer JavaScript- oder SQLX-Datei verwenden möchten, müssen Sie den ausgewählten Inhalt des Pakets in die Datei importieren. Sie können auch ein ganzes Paket in eine JavaScript- oder SQLX-Datei importieren, anstatt den ausgewählten Inhalt.

Um Probleme mit der Paketinstallation in Ihrer Produktionsumgebung zu vermeiden, empfehlen wir Folgendes:

  • Geben Sie die Paketversion explizit in package.json an, z. B. 3.0.0. Verwenden Sie keine anderen dependencies-Optionen von package.json, z. B. >version.

  • Testen Sie neue Paketversionen in einer Nicht-Produktionsumgebung. Weitere Informationen zum Konfigurieren verschiedener Codelebenszyklusumgebungen finden Sie unter Codelebenszyklus verwalten.

Paket als Abhängigkeit hinzufügen

Wenn Sie ein Paket in einem Dataform-Repository installieren möchten, müssen Sie es in der Datei package.json als Abhängigkeit hinzufügen:

  1. Wählen Sie in Ihrem Arbeitsbereich im Bereich Dateien die Option package.json aus.

  2. Fügen Sie das Paket dem dependencies-Block hinzu:

    1. Fügen Sie ein veröffentlichtes öffentliches NPM-Paket im folgenden Format hinzu:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Ersetzen Sie Folgendes:

      • PACKAGE-NAME durch den Namen des Pakets.
      • PACKAGE-VERSION mit der neuesten Version des veröffentlichten öffentlichen NPM-Pakets. Geben Sie die Version explizit an, z. B. 3.0.0, um Probleme mit der Paketinstallation zu vermeiden.

    2. Fügen Sie ein nicht veröffentlichtes öffentliches NPM-Paket im folgenden Format hinzu:

      "PACKAGE-NAME": "PACKAGE-URL"

      Ersetzen Sie Folgendes:

      • PACKAGE-NAME durch den Namen des Pakets.
      • PACKAGE-URL durch die tar.gz URL des Paket-Repositorys des Drittanbieters, z. B. https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Fügen Sie ein authentifiziertes privates NPM-Paket im folgenden Format hinzu:

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

      Ersetzen Sie Folgendes:

      • REGISTRY-SCOPE durch den Namen des Pakets. REGISTRY-SCOPE muss mit dem Registry-Bereich übereinstimmen, der in der Datei .nmprc in Ihrem Repository definiert ist.
      • PACKAGE-NAME durch den Namen des Pakets.
      • PACKAGE-URL durch die tar.gz-URL des Paket-Repositorys, z. B. https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Klicken Sie auf Pakete installieren.

  4. Führen Sie einen Commit aus und übertragen Sie die Änderungen per Push.

Das folgende Codebeispiel zeigt das öffentliche Open-Source-Paket „Slowly changing dimensions“, das der .package.json-Datei hinzugefügt wurde:

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

Paketfunktion oder ‑konstante in eine JavaScript-Datei in Dataform importieren

Wenn Sie eine Funktion oder Konstante aus einem Paket in einer JavaScript-Datei in Dataform verwenden möchten, müssen Sie sie zuerst in die Datei importieren.

So importieren Sie eine Funktion oder Konstante aus einem Paket in eine JavaScript-Datei:

  1. Wählen Sie in Ihrem Arbeitsbereich im Bereich Dateien eine .js-Datei aus, in der Sie das Paket verwenden möchten.

  2. Importieren Sie in der Datei eine Funktion oder Konstante im folgenden Format:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Ersetzen Sie EXPORT-NAME durch den Namen der Funktion oder Konstante, die Sie verwenden möchten, die in module.exports in der Paketdatei index.js deklariert ist.
    2. Ersetzen Sie PACKAGE-NAME durch den Namen des Pakets, das Sie verwenden möchten.

  3. Führen Sie einen Commit aus und übertragen Sie die Änderungen per Push.

Das folgende Codebeispiel zeigt die Funktion getDomain aus dem Paket postoffice, die in eine JavaScript-Datei importiert und verwendet wird:

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

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

Ein ganzes Paket in eine JavaScript-Datei in Dataform importieren

So importieren Sie das gesamte Paket in eine JavaScript-Datei, anstatt ausgewählte Funktionen oder Konstanten in eine JavaScript-Datei zu importieren:

  1. Wählen Sie in Ihrem Arbeitsbereich im Bereich Dateien eine .js-Datei aus, in der Sie das Paket verwenden möchten.

  2. Importieren Sie das Paket in der Datei im folgenden Format:

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Ersetzen Sie CONSTANT-NAME durch einen Namen für die Konstante.
    2. Ersetzen Sie PACKAGE-NAME durch den Namen des Pakets, das Sie verwenden möchten.

  3. Führen Sie einen Commit aus und übertragen Sie die Änderungen per Push.

Das folgende Codebeispiel zeigt die getDomain-Funktion aus dem importierten postoffice-Paket, die in einer JavaScript-Datei verwendet wird:

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

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

Paketfunktion oder ‑konstante in eine SQLX-Datei in Dataform importieren

Wenn Sie eine Funktion oder Konstante aus einem Paket in einer SQLX-Datei verwenden möchten, müssen Sie sie zuerst in die Datei importieren.

So importieren Sie eine Funktion oder Konstante aus einem Paket in eine SQLX-Datei:

  1. Wählen Sie in Ihrem Arbeitsbereich im Bereich Dateien eine .sqlx-Datei aus, in der Sie das Paket verwenden möchten.

  2. Fügen Sie in der Datei den folgenden js-Block ein:

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Ersetzen Sie EXPORT-NAME durch den Namen der Funktion oder Konstante, die Sie verwenden möchten, die in module.exports in der Paketdatei index.js deklariert ist.
    2. Ersetzen Sie PACKAGE-NAME durch den Namen des Pakets, das Sie verwenden möchten.

  3. Führen Sie einen Commit aus und übertragen Sie die Änderungen per Push.

Im folgenden Codebeispiel wird die getDomain-Funktion aus dem postoffice-Paket in einen js-Block importiert und in einer SELECT-Anweisung in einer SQLX-Datei verwendet:

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

config {
    type: "table",
}

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

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

Ein ganzes Paket in eine SQLX-Datei in Dataform importieren

So importieren Sie das gesamte Paket in eine SQLX-Datei, anstatt ausgewählte Funktionen oder Konstanten in eine JavaScript-Datei zu importieren:

  1. Wählen Sie in Ihrem Arbeitsbereich im Bereich Dateien eine .sqlx-Datei aus, in der Sie das Paket verwenden möchten.

  2. Importieren Sie das Paket in der Datei im folgenden Format:

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Ersetzen Sie CONSTANT-NAME durch einen Namen für die Konstante.
    2. Ersetzen Sie PACKAGE-NAME durch den Namen des Pakets, das Sie verwenden möchten.

  3. Führen Sie einen Commit aus und übertragen Sie die Änderungen per Push.

Das folgende Codebeispiel zeigt das postoffice-Paket, das in einen js-Block importiert wurde, und die getDomain-Funktion, die in einer SELECT-Anweisung in einer SQLX-Datei verwendet wird:

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

config {
    type: "table",
}

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

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

Privates Paket authentifizieren

In diesem Abschnitt erfahren Sie, wie Sie ein privates NPM-Paket in Dataform authentifizieren, um die Installation in einem Dataform-Repository zu ermöglichen.

Wenn Sie ein privates NPM-Paket in einem Dataform-Repository installieren und zum Entwickeln Ihres Workflows verwenden möchten, müssen Sie das Paket zuerst in Dataform authentifizieren. Der Authentifizierungsprozess unterscheidet sich für das erste private Paket in einem Repository und ein nachfolgendes privates Paket in einem Repository.

Erstes privates Paket in einem Dataform-Repository authentifizieren

Wenn Sie private NPM-Pakete in Dataform authentifizieren möchten, müssen Sie Folgendes tun, bevor Sie das erste private NPM-Paket in einem Dataform-Repository installieren:

  1. Erstellen Sie ein Secret Manager-Secret, um Authentifizierungstokens privater NPM-Pakete im Dataform-Repository zu speichern.

    1. Fügen Sie dem Secret das Authentifizierungstoken des Pakets hinzu, das Sie aus Ihrer NPM-Registry abgerufen haben.

    Sie müssen alle Authentifizierungstokens der privaten NPM-Pakete in Ihrem Repository in einem einzigen Secret speichern. Sie müssen ein eigenes Secret pro Dataform-Repository erstellen. Das Geheimnis muss im JSON-Format vorliegen.

  2. Laden Sie das Secret in das Dataform-Repository hoch.

  3. Erstellen Sie eine .npmrc-Datei und fügen Sie der Datei das Authentifizierungstoken des Pakets hinzu.

    Das Authentifizierungstoken in der Datei .npmrc muss mit dem Authentifizierungstoken im hochgeladenen Secret übereinstimmen.

Nachdem Sie das private NPM-Paket authentifiziert haben, können Sie es im Dataform-Repository installieren.

Secret für die Authentifizierung privater Pakete erstellen

Wenn Sie private NPM-Pakete in einem Dataform-Repository authentifizieren möchten, müssen Sie ein Secret Manager-Secret erstellen und Authentifizierungstokens für alle privaten Pakete definieren, die Sie im Secret im Dataform-Repository installieren möchten. Definieren Sie für jedes private NPM-Paket ein Authentifizierungstoken und speichern Sie alle Authentifizierungstokens in einem einzelnen Secret für jedes Repository. Das Geheimnis muss im JSON-Format vorliegen.

So erstellen Sie ein Secret mit Authentifizierungstokens für private NPM-Pakete:

  1. Erstellen Sie ein Secret in Secret Manager.

    1. Geben Sie im Feld Secret-Wert ein oder mehrere Authentifizierungstokens im folgenden Format ein:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Ersetzen Sie Folgendes:

    • AUTHENTICATION_TOKEN_NAME: Ein eindeutiger Name für das Token, der das zu authentifizierende Paket identifiziert.
    • TOKEN_VALUE: der Wert des Authentifizierungstokens, der aus Ihrer NPM-Registry abgerufen wurde.

  2. Gewähren Sie dem Dataform-Dienstkonto Zugriff auf das Secret.

    Das Dataform-Dienstkonto hat folgendes Format:

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. Achten Sie beim Gewähren des Zugriffs darauf, Ihrem Dataform-Dienstkonto die Rolle roles/secretmanager.secretAccessor zuzuweisen.

Geheimes Schlüssel für die Authentifizierung privater Pakete in ein Dataform-Repository hochladen

Bevor Sie ein privates NPM-Paket zum ersten Mal in einem Dataform-Repository installieren, laden Sie das Secret mit dem Authentifizierungstoken des Pakets in das Repository hoch.

So laden Sie das Secret mit den Authentifizierungstokens für private NPM-Pakete in ein Dataform-Repository hoch:

  1. Öffnen Sie in der Google Cloud Console die Seite Dataform.

    Zu Dataform

  2. Wählen Sie das Repository aus, in dem Sie private NPM-Pakete installieren möchten.

  3. Klicken Sie auf der Repository-Seite auf Einstellungen > Private NPM-Pakete konfigurieren.

  4. Wählen Sie im Bereich Secret-Token für npm-Paket hinzufügen im Menü Secret das Secret mit den Authentifizierungstokens für private npm-Pakete aus.

  5. Klicken Sie auf Speichern.

.npmrc-Datei für die Authentifizierung privater Pakete erstellen

Wenn Sie private NPM-Pakete in einem Dataform-Repository authentifizieren möchten, müssen Sie im Repository eine .npmrc-Datei auf oberster Ebene erstellen. Sie müssen Authentifizierungstokens für alle privaten NPM-Pakete speichern, die im Repository in der .npmrc-Datei installiert werden sollen. Die Authentifizierungstokens in der Datei .npmrc müssen mit den Authentifizierungstokens in dem Geheimnis übereinstimmen, das in das Repository hochgeladen wurde. Weitere Informationen zu .npmrc-Dateien finden Sie in der npmrc-Dokumentation.

So erstellen Sie eine .npmrc-Datei der obersten Ebene in Ihrem Repository:

  1. Öffnen Sie in der Google Cloud Console die Seite Dataform.

    Zu Dataform

  2. Wählen Sie das Repository aus, in dem Sie private NPM-Pakete installieren möchten, und dann einen Arbeitsbereich.

  3. Klicken Sie im Bereich Dateien auf  Mehr und dann auf Datei erstellen.

  4. Führen Sie im Bereich Neue Datei erstellen die folgenden Schritte aus:

    1. Geben Sie im Feld Dateipfad hinzufügen .npmrc ein.

    2. Klicken Sie auf Datei erstellen.

Datei .npmrc in einem Dataform-Repository ein Authentifizierungstoken hinzufügen

Wenn Sie ein privates NPM-Paket in einem Dataform-Repository authentifizieren möchten, das bereits ein Secret mit Paketauthentifizierungstokens und eine .npmrc-Datei enthält, müssen Sie der .npmrc-Datei im Repository das Authentifizierungstoken für das private Paket hinzufügen.

In der Datei .npmrc müssen Sie den Umfang Ihrer NPM-Registry definieren und das Authentifizierungstoken für das private Paket hinzufügen, auf das in diesem Umfang zugegriffen wird. Weitere Informationen zu .npmrc-Dateien finden Sie in der npmrc-Dokumentation.

Das Authentifizierungstoken in der Datei .npmrc muss mit dem Authentifizierungstoken in dem Secret übereinstimmen, das in das Repository hochgeladen wurde.

So fügen Sie der Datei .npmrc in einem Dataform-Repository ein Authentifizierungstoken hinzu:

  1. Öffnen Sie in der Google Cloud Console die Seite Dataform.

    Zu Dataform

  2. Wählen Sie das Repository aus, in dem Sie private NPM-Pakete installieren möchten, und dann einen Arbeitsbereich.

  3. Wählen Sie im Bereich Dateien die Datei .npmrc aus.

  4. Definieren Sie in der .npmrc-Datei den NPM-Registry-Umfang und das Authentifizierungstoken für das private Paket im folgenden Format:

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

    Ersetzen Sie Folgendes:

    • REGISTRY-SCOPE: den NPM-Registry-Bereich, auf den Sie das Authentifizierungstoken anwenden möchten.
    • NPM-REGISTRY-URL: die URL Ihrer NPM-Registry, z. B. https://npm.pkg.github.com.
    • AUTHENTICATION-TOKEN: das Authentifizierungstoken für das private NPM-Paket. Das Authentifizierungstoken in der Datei .npmrc muss mit dem Authentifizierungstoken im hochgeladenen Secret übereinstimmen. Das Authentifizierungstoken wird in der Datei .npmrc als Umgebungsvariable angegeben. Fügen Sie also die öffnenden Klammern ${ und die schließenden Klammern } hinzu.

    Sie können mehrere Authentifizierungstokens eingeben.

Das folgende Codebeispiel zeigt ein Authentifizierungstoken für ein privates NPM-Paket, das der Datei .npmrc in einem Dataform-Repository hinzugefügt wurde:

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

Ein nachfolgendes privates Paket in einem Dataform-Repository authentifizieren

So authentifizieren Sie ein privates NPM-Paket in einem Dataform-Repository, das bereits ein Secret mit Paketauthentifizierungstokens und eine .npmrc-Datei enthält:

  1. Liste die Secrets in Secret Manager auf und wähle das Secret aus, in dem die Authentifizierungstokens der privaten NPM-Pakete deines Repositories gespeichert sind.

  2. Fügen Sie dem Secret eine neue Version hinzu.

    Dataform verwendet standardmäßig die neueste Version des Secrets.

    1. Fügen Sie dem geheimen Wert das Authentifizierungstoken für das private Paket im folgenden Format hinzu:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Ersetzen Sie Folgendes:

    • AUTHENTICATION_TOKEN_NAME: Ein eindeutiger Name für das Token, der das zu authentifizierende Paket identifiziert.
    • TOKEN_VALUE: der Wert des Authentifizierungstokens, der aus Ihrer NPM-Registry abgerufen wurde.

    Sie können mehrere Authentifizierungstokens gleichzeitig hinzufügen.

  3. Fügen Sie in Dataform das Authentifizierungstoken der Datei .npmrc in Ihrem Repository hinzu.

Nachdem Sie das private NPM-Paket authentifiziert haben, können Sie das Paket im Dataform-Repository installieren.

Paket erstellen

In diesem Abschnitt erfahren Sie, wie Sie ein benutzerdefiniertes JavaScript-Paket erstellen, mit dem Sie Workflows in Dataform entwickeln können.

Wenn Sie ein Paket erstellen möchten, das Sie in mehreren Dataform-Repositories wiederverwenden können, müssen Sie ein Dataform-Repository speziell für das Paket erstellen und es mit einem Drittanbieter-Git-Repository verbinden, um es für andere Dataform-Repositories verfügbar zu machen.

Anschließend müssen Sie eine index.js-Datei auf oberster Ebene erstellen und der Datei den exportierbaren Paketinhalt hinzufügen, z. B. Funktionen und Konstanten. Ein Beispiel für ein in Dataform erstelltes Paket finden Sie auf GitHub unter dataform-package-base.

Nachdem Sie das Paket erstellt haben, können Sie es in einem anderen Dataform-Repository installieren und die exportierbaren Inhalte des Pakets wie Konstanten und Funktionen verwenden, um Workflows zu entwickeln.

Alternativ zum Erstellen eines Pakets können Sie JavaScript-Funktionen und ‑Konstanten mithilfe von Includes in einem einzigen Dataform-Repository wiederverwenden. Weitere Informationen finden Sie unter Variablen und Funktionen mit Includes in Dataform wiederverwenden.

So erstellen Sie in Ihrem Arbeitsbereich ein eigenes Paket mit JavaScript-Code, das Sie in Dataform wiederverwenden können:

  1. Klicken Sie im Bereich Dateien auf Mehr.

  2. Klicken Sie auf Datei erstellen.

    1. Führen Sie im Bereich Neue Datei erstellen die folgenden Schritte aus:

    2. Geben Sie im Feld Dateipfad hinzufügen index.js ein.

    3. Klicken Sie auf Datei erstellen.

  3. Geben Sie in der Datei index.js den JavaScript-Code ein, den Sie aus dem Paket exportieren möchten.

    1. Erstellen Sie Konstanten im folgenden Format:

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

      Ersetzen Sie Folgendes:

      • CONSTANT_NAME: der Name der Konstante
      • CONSTANT_VALUE: der Wert der Konstante

    2. Erstellen Sie Funktionen im folgenden Format:

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      Ersetzen Sie Folgendes:

      • FUNCTION_NAME: Der Name Ihrer Funktion.
      • PARAMETERS: die Parameter Ihrer Funktion.
      • FUNCTION_BODY: Der Code, der von der Funktion ausgeführt werden soll.

  4. Optional: Klicken Sie auf Formatieren.

  5. Optional: Fügen Sie im Verzeichnis definitions den Code Ihres Pakets hinzu, der nicht exportiert werden soll.

  6. Führen Sie einen Commit aus und übertragen Sie die Änderungen per Push.

Das folgende Paketcodebeispiel zeigt die index.js-Datei des postoffice-Pakets, das die getDomain-Funktion exportiert:

// 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 }

Nächste Schritte