JavaScript-Pakete verwenden

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

Hinweise

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    Zu Dataform

  2. Führen Sie einen oder beide der folgenden Schritte 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 das private Paket.
      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 speziell für Ihr Paket vorgesehen ist. Der Repository-Name muss mit dem Namen Ihres Pakets übereinstimmen.
      2. Verbinden Sie das Repository mit einem Drittanbieter-Git-Repository, in dem Ihr Paket gehostet wird.
      3. Arbeitsbereich im Dataform-Repository erstellen und initialisieren

  3. Prüfen Sie, ob Sie die erforderlichen Berechtigungen haben, um die Aufgaben in diesem Dokument auszuführen.

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 wird gezeigt, 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 Arten von Paketen in Dataform installieren:

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

So vermeiden Sie Probleme bei der Paketinstallation in Ihrer Produktionsumgebung:

  • 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 Workflow-Lebenszyklusumgebungen finden Sie unter Best Practices für den Workflow-Lebenszyklus.

Paket als Abhängigkeit hinzufügen

Wenn Sie ein Paket in einem Dataform-Repository installieren möchten, müssen Sie es als Abhängigkeit in der Datei package.json 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. Um Probleme bei der Paketinstallation zu vermeiden, geben Sie die Version explizit an, z. B. 3.0.0.

    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 Drittanbieter-Paket-Repositorys, 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:

  3. Klicken Sie auf Pakete installieren.

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

Das folgende Codebeispiel zeigt das öffentliche Open-Source-Paket „Slowly changing dimensions“, das der Datei .package.json 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 eine 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 eine 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 eine 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 und 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 durch 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 durch und übertragen Sie die Änderungen per Push.

Das folgende Codebeispiel zeigt die Funktion getDomain aus dem importierten Paket postoffice, 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 eine 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 eine 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. Geben Sie in die 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 und 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 durch und übertragen Sie die Änderungen per Push.

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

/*
 * 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 durch und übertragen Sie die Änderungen per Push.

Das folgende Codebeispiel zeigt, wie das postoffice-Paket in einem js-Block importiert wird und wie die getDomain-Funktion 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, damit es in einem Dataform-Repository installiert werden kann.

Wenn Sie ein privates npm-Paket in einem Dataform-Repository installieren und damit Ihren Workflow entwickeln 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

Zur Authentifizierung privater npm-Pakete in Dataform müssen Sie vor der Installation des ersten privaten npm-Pakets in einem Dataform-Repository Folgendes tun:

  1. Erstellen Sie ein Secret Manager-Secret, in dem Authentifizierungstokens privater NPM-Pakete im Dataform-Repository gespeichert werden.

    1. Fügen Sie dem Secret das Authentifizierungstoken des Pakets hinzu, das Sie von Ihrer NPM-Registrierung erhalten haben.

    Sie müssen alle Authentifizierungstokens der privaten NPM-Pakete in Ihrem Repository in einem einzelnen Secret speichern. Sie müssen ein dediziertes Secret pro Dataform-Repository erstellen. Das Secret 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 das Paket 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 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 Secret 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, mit dem das authentifizierte Paket identifiziert wird.
    • TOKEN_VALUE: Der Wert des Authentifizierungstokens, das Sie von Ihrer NPM-Registry erhalten haben.

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

    Ihr Dataform-Dienstkonto hat folgendes Format:

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

Geheimnis 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 Ihr Secret mit dem Authentifizierungstoken des Pakets in das Repository hoch.

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

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    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

Um private npm-Pakete in einem Dataform-Repository zu authentifizieren, müssen Sie im Repository eine .npmrc-Datei auf oberster Ebene erstellen. Sie müssen Authentifizierungstokens für alle privaten NPM-Pakete, die im Repository installiert werden sollen, in der Datei .npmrc speichern. Die Authentifizierungstokens in der Datei .npmrc müssen mit den Authentifizierungstokens im im Repository hochgeladenen Secret übereinstimmen. Weitere Informationen zu .npmrc-Dateien finden Sie in der npmrc-Dokumentation.

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

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    Zu Dataform

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

  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.

Einem Dataform-Repository die Datei .npmrc mit einem 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 das Authentifizierungstoken für das private Paket der .npmrc-Datei im Repository hinzufügen.

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

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

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

  1. Rufen Sie in der Google Cloud Console die Seite Dataform auf.

    Zu Dataform

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

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

  4. Definieren Sie in der Datei .npmrc den NPM-Registrierungsbereich 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: Der 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 als Umgebungsvariable in der Datei .npmrc bereitgestellt. Achten Sie also darauf, dass Sie die öffnenden ${ und schließenden } Klammern hinzufügen.

    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}

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. Listen Sie die Secrets in Secret Manager auf und wählen Sie das Secret aus, in dem die Authentifizierungstokens der privaten NPM-Pakete Ihres Repositorys 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 das Authentifizierungstoken für das private Paket dem Secret-Wert im folgenden Format hinzu:
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    Ersetzen Sie Folgendes:

    • AUTHENTICATION_TOKEN_NAME: Ein eindeutiger Name für das Token, mit dem das authentifizierte Paket identifiziert wird.
    • TOKEN_VALUE: Der Wert des Authentifizierungstokens, das Sie von Ihrer NPM-Registry erhalten haben.

    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 erstellen, das dem Paket gewidmet ist, und es mit einem Drittanbieter-Git-Repository verbinden, damit es für andere Dataform-Repositories verfügbar ist.

Anschließend müssen Sie eine index.js-Datei auf oberster Ebene erstellen und die exportierbaren Paketinhalte wie Funktionen und Konstanten in die Datei einfügen. Ein Beispiel für ein in Dataform erstelltes Paket finden Sie auf dataform-package-base auf GitHub.

Nachdem Sie das Paket erstellt haben, können Sie es in einem anderen Dataform-Repository installieren und die exportierbaren Inhalte des Pakets, z. B. Konstanten und Funktionen, zum Entwickeln von Workflows verwenden.

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

So erstellen Sie ein eigenes Paket mit JavaScript-Code, den 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 Ihr Paket exportieren soll.

    1. Erstellen Sie Konstanten im folgenden Format:

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

      Ersetzen Sie Folgendes:

      • CONSTANT_NAME: der Name Ihrer Konstanten
      • CONSTANT_VALUE: der Wert Ihrer Konstanten

    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, den die Funktion ausführen 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 durch und übertragen Sie die Änderungen per Push.

Das folgende Paketcodebeispiel zeigt die Datei index.js des Pakets postoffice, das die Funktion getDomain 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