JavaScript パッケージを使用する

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

始める前に

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

    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 ファイルにインポートすることもできます。

本番環境でパッケージのインストールに関する問題が発生しないようにするには、次のことをおすすめします。

  • package.json でパッケージ バージョンを明示的に指定します（例: 3.0.0）。package.json の他の dependencies オプション（>version など）は使用しないでください。

  • 新しいパッケージ バージョンを非本番環境でテストします。さまざまなコード ライフサイクル環境の構成の詳細については、コード ライフサイクルの管理をご覧ください。

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

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

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

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

次のコードサンプルは、.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"
   }
 }
 ```

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

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

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

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

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

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

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

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

/*
 * 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 します。

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

/*
 * 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 します。

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

/*
 * 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 します。

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

/*
 * 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 リポジトリへのインストールを有効にする方法について説明します。

非公開 NPM パッケージを Dataform リポジトリにインストールしてワークフローの開発に使用する場合は、まず 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 で Secret を作成する。

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

    次のように置き換えます。

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

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

    Dataform サービス アカウントの形式は次のとおりです。

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

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

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

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

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

    Dataform に移動

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

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

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

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

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

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

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

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

    Dataform に移動

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

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

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

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

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

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

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

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

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

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

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

    Dataform に移動

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

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

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

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

    次のように置き換えます。

    • REGISTRY-SCOPE: 認証トークンを適用する NPM レジストリ スコープ。
    • NPM-REGISTRY-URL: NPM レジストリの URL（例: https://npm.pkg.github.com）。
    • AUTHENTICATION-TOKEN: 非公開の NPM パッケージの認証トークン。.npmrc ファイル内の認証トークンは、アップロードされたシークレットの認証トークンと一致する必要があります。認証トークンは、.npmrc ファイルで環境変数として提供されるため、開きの ${ と } の閉じ括弧を追加してください。

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

次のコードサンプルは、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 }

次のステップ