JavaScript パッケージを使用する

このドキュメントでは、次の方法について説明します。

始める前に

  1. コンソールで、[Dataform] ページに移動します。 Google Cloud

    Dataform に移動

  2. 次のいずれかまたは両方を行います。

    1. リポジトリにパッケージをインストールする、または非公開 NPM パッケージを認証してインストールできるようにするには、次の操作を行います。
      1. リポジトリを作成または選択します。
      2. 開発ワークスペースを作成または選択します。
      3. 省略可: 非公開パッケージをインストールするには、 非公開パッケージを認証します。
      4. リポジトリに package.json ファイルが含まれていない場合は、package.json を作成して Dataform コアパッケージを移動します。
    2. パッケージを作成するには、次の操作を行います。
      1. パッケージ専用の Dataform リポジトリ を作成します。リポジトリ名をパッケージの名前に合わせます。
      2. リポジトリを接続して、 パッケージをホストするサードパーティの Git リポジトリに接続します。
      3. Dataform リポジトリに ワークスペースを作成して初期化します。

  3. このドキュメントのタスクを完了するために必要な権限が付与されていることを確認します。

必要なロール

このドキュメントのタスクを実行するために必要な権限を取得するには、管理者に次の IAM のロールを付与するよう依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

パッケージをインストールする

このセクションでは、JavaScript パッケージをインストールして JavaScript ファイルと SQLX ファイルにインポートし、パッケージを使用して Dataform でワークフローを開発する方法について説明します。

Dataform でパッケージを使用するには、リポジトリにインストールする必要があります。

Dataform には、次の種類のパッケージをインストールできます。

JavaScript ファイルまたは SQLX ファイルでパッケージを使用するには、パッケージの選択したコンテンツをファイルにインポートする必要があります。選択したコンテンツの代わりに、パッケージ全体を JavaScript ファイルまたは SQLX ファイルにインポートすることもできます。

本番環境でのパッケージのインストールに関する問題を回避するため、次のことをおすすめします。

パッケージを依存関係として追加する

Dataform リポジトリにパッケージをインストールするには、package.json ファイルに依存関係として追加する必要があります。

  1. ワークスペースの [ファイル] ペインで package.json を選択します。

  2. パッケージを dependencies ブロックに追加します。

    1. 公開されている公開 NPM パッケージを次の形式で追加します。

      "PACKAGE-NAME": "PACKAGE-VERSION"

      以下を置き換えます。

      • PACKAGE-NAME は、パッケージの名前に置き換えます。
      • PACKAGE-VERSION は、 公開されている公開 NPM パッケージの最新バージョンに置き換えます。パッケージのインストールに関する問題を回避するため、バージョンを明示的に指定します（例: 3.0.0）。

    2. 公開されていない公開 NPM パッケージを次の形式で追加します。

      "PACKAGE-NAME": "PACKAGE-URL"

      以下を置き換えます。

      • PACKAGE-NAME は、パッケージの名前に置き換えます。
      • PACKAGE-URL は、サードパーティ パッケージ リポジトリの tar.gz URL（https://github.com/user/sample-package-repository/archive/master.tar.gz など）に置き換えます。

    3. 認証済みの非公開 NPM パッケージを次の形式で追加します。

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

      以下を置き換えます。

      • REGISTRY-SCOPE は、パッケージの名前に置き換えます。 REGISTRY-SCOPE は、リポジトリの .npmrc ファイルで定義されているレジストリ スコープ と一致する必要があります。
      • PACKAGE-NAME は、パッケージの名前に置き換えます。
      • PACKAGE-URL は、パッケージ リポジトリの tar.gz URL（https://github.com/user/sample-package-repository/archive/master.tar.gz など）に置き換えます。

  3. [パッケージをインストール] をクリックします。

  4. 変更を commit して push します。

次のコードサンプルは、.package.json ファイルに追加された公開されているオープンソースの Slowly changing dimensions パッケージを示しています。

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

パッケージの関数または定数を Dataform の JavaScript ファイルにインポートする

Dataform の JavaScript ファイル内でパッケージの関数または定数を使用するには、まずファイルにインポートする必要があります。

パッケージの関数または定数を JavaScript ファイルにインポートする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .js ファイルを選択します。

  2. ファイルで、次の形式で関数または定数をインポートします。

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. EXPORT-NAME は、使用する関数または 定数の名前に置き換えます。これは、module.exports の パッケージ index.js ファイルで宣言されています。
    2. PACKAGE-NAME は、使用するパッケージの 名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、postoffice パッケージの getDomain 関数をインポートして JavaScript ファイルで使用する方法を示しています。

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

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

パッケージ全体を Dataform の JavaScript ファイルにインポートする

選択した関数または定数を JavaScript ファイルにインポートするのではなく、パッケージ全体を JavaScript ファイルにインポートする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .js ファイルを選択します。

  2. ファイルで、次の形式でパッケージをインポートします。

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. CONSTANT-NAME は、定数の名前に置き換えます。
    2. PACKAGE-NAME は、使用するパッケージの 名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、インポートされた postoffice パッケージの getDomain 関数を JavaScript ファイルで使用する方法を示しています。

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

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

パッケージの関数または定数を Dataform の SQLX ファイルにインポートする

SQLX ファイル内でパッケージの関数または定数を使用するには、まずファイルにインポートする必要があります。

パッケージの関数または定数を SQLX ファイルにインポートする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .sqlx ファイルを選択します。

  2. ファイルに次の js ブロックを入力します。

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. EXPORT-NAME は、パッケージ index.js ファイルの module.exports で宣言された、使用する関数または定数の名前に置き換えます。
    2. PACKAGE-NAME は、使用するパッケージの 名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、postoffice パッケージの getDomain 関数を js ブロックにインポートして SQLX ファイルの SELECT ステートメントで使用する方法を示しています。

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

config {
    type: "table",
}

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

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

パッケージ全体を Dataform の SQLX ファイルにインポートする

選択した関数または定数を JavaScript ファイルにインポートするのではなく、パッケージ全体を SQLX ファイルにインポートする手順は次のとおりです。

  1. ワークスペースの [ファイル] ペインで、パッケージを使用する .sqlx ファイルを選択します。

  2. ファイルで、次の形式でパッケージをインポートします。

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. CONSTANT-NAME は、定数の名前に置き換えます。
    2. PACKAGE-NAME は、使用するパッケージの 名前に置き換えます。

  3. 変更を commit して push します。

次のコードサンプルは、postoffice パッケージを js ブロックにインポートし、その getDomain 関数を SQLX ファイルの SELECT ステートメントで使用する方法を示しています。

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

config {
    type: "table",
}

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

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

非公開パッケージを認証する

このセクションでは、Dataform で非公開 NPM パッケージを認証して、Dataform リポジトリにインストールできるようにする方法について説明します。

Dataform リポジトリに非公開 NPM パッケージ をインストールしてワークフローの開発に使用するには、まず Dataform でパッケージを認証する 必要があります。認証プロセスは、リポジトリ内の最初の非公開パッケージとリポジトリ内の後続の非公開パッケージで異なります。

Dataform リポジトリで最初の非公開パッケージを認証する

Dataform で非公開 NPM パッケージを認証するには、まず最初の非公開 NPM パッケージを Dataform リポジトリにインストールする前に、次の作業を行う必要があります。

  1. 非公開 NPM パッケージの認証トークンを Dataform リポジトリに保存する専用の Secret Manager シークレットを作成します。

    1. NPM レジストリから取得したパッケージの認証トークンをシークレットに追加します。

    非公開 NPM パッケージのすべての認証トークンを 1 つのシークレット内のリポジトリに保存する必要があります。Dataform リポジトリごとに 1 つの専用シークレットを作成する必要があります。シークレットは JSON 形式にする必要があります。

  2. シークレットをアップロードして Dataform リポジトリに保存します。

  3. .npmrc ファイルを作成し、パッケージの認証トークン をファイルに追加します。

    .npmrc ファイルの認証トークンは、アップロードされたシークレットの認証トークンと一致する必要があります。

非公開 NPM パッケージを認証したら、Dataform リポジトリにパッケージを インストールできます。

非公開パッケージの認証用のシークレットを作成する

Dataform リポジトリで非公開 NPM パッケージを認証するには、Secret Manager のシークレットを作成し、シークレット内の Dataform リポジトリにインストールするすべての非公開パッケージの認証トークンを定義する必要があります。非公開 NPM パッケージごとに 1 つの認証トークンを定義し、リポジトリごとに 1 つのシークレットにすべての認証トークンを保存します。シークレットは JSON 形式にする必要があります。

非公開 NPM パッケージの認証トークンを使用してシークレットを作成するには、次の手順に従います。

  1. Secret Manager でシークレットを作成します。

    1. [シークレットの値] フィールドに、次の形式で 1 つ以上の認証トークンを入力します。
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    以下を置き換えます。

    • AUTHENTICATION_TOKEN_NAME: 認証するパッケージを識別するトークンの一意の名前。
    • TOKEN_VALUE: NPM レジストリから取得した認証トークンの値。

  2. Dataform サービス エージェントにシークレットへのアクセス権を付与します。

    Dataform サービス エージェント ID は次の形式です。

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. アクセス権を付与する際は、Dataform サービス エージェントに roles/secretmanager.secretAccessor ロールを付与してください。

非公開パッケージ認証用のシークレットを Dataform リポジトリにアップロードする

Dataform リポジトリに非公開 NPM パッケージを初めてインストールする前に、パッケージの認証トークンを含むシークレットをリポジトリにアップロードします。

非公開 NPM パッケージの認証トークンを含むシークレットを Dataform リポジトリにアップロードする手順は次のとおりです。

  1. コンソールで、[Dataform] ページに移動します。 Google Cloud

    Dataform に移動

  2. 非公開 NPM パッケージをインストールするリポジトリを選択します。

  3. リポジトリ ページで、[設定] > [非公開 NPM パッケージを設定] の順にクリックします。

  4. [NPM パッケージ シークレット トークンを追加] ペインの [シークレット] メニューで、非公開 NPM パッケージの認証トークンを含むシークレットを選択します。

  5. [保存] をクリックします。

非公開パッケージ認証用の .npmrc ファイルを作成する

Dataform リポジトリで非公開 NPM パッケージを認証するには、リポジトリに最上位の .npmrc ファイルを作成する必要があります。リポジトリにインストールするすべての非公開 NPM パッケージの認証トークンを .npmrc ファイルに保存する必要があります。.npmrc ファイル内の認証トークンは、リポジトリにアップロードされたシークレットの認証トークンと一致する必要があります。 ファイルの詳細については、npmrc のドキュメントをご覧ください。.npmrc

リポジトリに最上位の .npmrc ファイルを作成する手順は次のとおりです。

  1. コンソールで、[Dataform] ページに移動します。 Google Cloud

    Dataform に移動

  2. 非公開 NPM パッケージをインストールするリポジトリを選択し、ワークスペースを選択します。

  3. [ファイル] ペインで、 [その他] をクリックし、 [ファイルを作成] をクリックします。

  4. [新しいファイルを作成] ペインで、次の操作を行います。

    1. [ファイルパスを追加] フィールドに「.npmrc」と入力します。

    2. [ファイルを作成] をクリックします。

Dataform リポジトリの .npmrc ファイルに認証トークンを追加する

パッケージ認証トークンと .npmrc ファイルを含むシークレットをすでに含む Dataform リポジトリで非公開NPM パッケージを認証するには、非公開パッケージの認証トークンをリポジトリ内の .npmrc ファイルに追加する必要があります。

.npmrc ファイルで、NPM レジストリのスコープを定義し、そのスコープでアクセスされる非公開パッケージの認証トークンを追加する必要があります。 .npmrc ファイルの詳細については、npmrc のドキュメントをご覧ください。

.npmrc ファイル内の認証トークンは、リポジトリにアップロードされたシークレットの認証トークンと一致する必要があります。

Dataform リポジトリの .npmrc ファイルに認証トークンを追加する手順は次のとおりです。

  1. コンソールで、[Dataform] ページに移動します。 Google Cloud

    Dataform に移動

  2. 非公開 NPM パッケージをインストールするリポジトリを選択し、ワークスペースを選択します。

  3. [ファイル] ペインで、.npmrc ファイルを選択します。

  4. .npmrc ファイルで、非公開パッケージの NPM レジストリ スコープと認証トークンを次の形式で定義します。

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

    以下を置き換えます。

    複数の認証トークンを入力できます。

次のコードサンプルは、Dataform リポジトリの .npmrc ファイルに追加された非公開 NPM パッケージの認証トークンを示しています。

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

Dataform リポジトリで後続の非公開パッケージを認証する

パッケージ認証トークンと .npmrc ファイルを含むシークレットをすでに含む Dataform リポジトリで非公開 NPM パッケージを認証するには、次の手順を行います。

  1. Secret Manager で、シークレットを一覧表示し、リポジトリの非公開 NPM パッケージの認証トークンを保存するシークレットを選択します。

  2. シークレットに新しいバージョンを追加します。

    Dataform はデフォルトで最新バージョンのシークレットを使用します。

    1. 非公開パッケージの認証トークンを次の形式でシークレット値に追加します。
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    以下を置き換えます。

    • AUTHENTICATION_TOKEN_NAME: 認証するパッケージを識別するトークンの一意の名前。
    • TOKEN_VALUE: NPM レジストリから取得した認証トークンの値。

    複数の認証トークンを一度に追加できます。

  3. Dataform で、リポジトリの .npmrc ファイルに認証トークンを追加します。

非公開 NPM パッケージを認証したら、Dataform リポジトリにパッケージをインストールできます。

パッケージを作成する

このセクションでは、Dataform でワークフローの開発に使用できるカスタム JavaScript パッケージを作成する方法について説明します。

複数の Dataform リポジトリで再利用できるパッケージを作成するには、パッケージ専用の Dataform リポジトリを作成し、サードパーティの Git リポジトリに接続して他の Dataform リポジトリで使用できるようにする必要があります。

次に、最上位の index.js ファイルを作成し、関数や定数など、エクスポート可能なパッケージ コンテンツをファイルに追加する必要があります。Dataform で作成されたパッケージの例については、 GitHub の dataform-package-base をご覧ください。

パッケージを作成したら、別の Dataform リポジトリにパッケージを インストール し、パッケージにエクスポート可能なコンテンツ（定数や関数など）を 使用してワークフローを開発できます。

パッケージを作成する代わりに、インクルードを使用して単一の Dataform リポジトリ全体で JavaScript 関数と定数を再利用できます。 詳細については、 Dataform でインクルードを使用して変数と関数を再利用するをご覧ください。

Dataform で再利用できる JavaScript コードを使用して独自のパッケージを作成するには、ワークスペースで次の操作を行います。

  1. [ファイル] ペインで、 [その他] をクリックします。

  2. [ファイルを作成] をクリックします。

    1. [新しいファイルを作成] ペインで、次の操作を行います。

    2. [ファイルパスを追加] フィールドに「index.js」と入力します。

    3. [ファイルを作成] をクリックします。

  3. index.js ファイルに、パッケージでエクスポートする JavaScript コードを入力します。

    1. 次の形式で定数を作成します。

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

      以下を置き換えます。

      • CONSTANT_NAME: 定数の名前
      • CONSTANT_VALUE: 定数の値

    2. 次の形式で関数を作成します。

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      以下を置き換えます。

      • FUNCTION_NAME: 関数の名前
      • PARAMETERS: 関数のパラメータ
      • FUNCTION_BODY: 関数で実行するコード

  4. 省略可: [書式] をクリックします。

  5. 省略可: definitions ディレクトリに、エクスポートしないパッケージのコードを追加します。

  6. 変更を commit して push します。

次のパッケージ コードサンプルは、getDomain 関数をエクスポートする postoffice パッケージの index.js ファイルを示しています。

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

次のステップ