Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

JavaScript パッケージを使用する

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

Dataform リポジトリに JavaScript パッケージをインストールする。
非公開 NPM パッケージを認証して、リポジトリにインストールできるようにする。
ワークフローの開発に使用できるカスタム JavaScript パッケージを作成する。

始める前に

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

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

必要なロール

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

ワークスペースとリポジトリに対する Dataform 編集者（roles/dataform.editor）
リポジトリの Dataform 管理者（roles/dataform.admin）

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

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

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

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

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

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

公開されている公開 NPM パッケージ
公開されていない公開 NPM パッケージ
認証済みの非公開 NPM パッケージ

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

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

package.json でパッケージバージョンを明示的に指定します（例: 3.0.0）。package.json の他の dependencies オプション（>version など）は使用しないでください。
新しいパッケージバージョンを非本番環境でテストします。さまざまなワークフローライフサイクル環境の構成の詳細については、ワークフローライフサイクルのベストプラクティスをご覧ください。

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

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

ワークスペースの [ファイル] ペインで package.json を選択します。
パッケージを 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 など）に置き換えます。
[パッケージをインストール] をクリックします。
変更を 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 ファイルにインポートする手順は次のとおりです。

ワークスペースの [ファイル] ペインで、パッケージを使用する .js ファイルを選択します。
ファイルで、次の形式で関数または定数をインポートします。
```
const { EXPORT-NAME } = require("PACKAGE-NAME");
```
1. EXPORT-NAME は、使用する関数または定数の名前に置き換えます。これは、module.exports のパッケージ index.js ファイルで宣言されています。
2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。
変更を commit して push します。

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

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

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

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

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

ワークスペースの [ファイル] ペインで、パッケージを使用する .js ファイルを選択します。
ファイルで、次の形式でパッケージをインポートします。
```
const CONSTANT-NAME = require("PACKAGE-NAME");
```
1. CONSTANT-NAME は、定数の名前に置き換えます。
2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。
変更を commit して push します。

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

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

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

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

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

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

ワークスペースの [ファイル] ペインで、パッケージを使用する .sqlx ファイルを選択します。
ファイルに次の js ブロックを入力します。
```
js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
```
1. EXPORT-NAME は、パッケージ index.js ファイルの module.exports で宣言された、使用する関数または定数の名前に置き換えます。
2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。
変更を 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 ファイルにインポートする手順は次のとおりです。

ワークスペースの [ファイル] ペインで、パッケージを使用する .sqlx ファイルを選択します。
ファイルで、次の形式でパッケージをインポートします。
```
js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
```
1. CONSTANT-NAME は、定数の名前に置き換えます。
2. PACKAGE-NAME は、使用するパッケージの名前に置き換えます。
変更を 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 リポジトリにインストールする前に、次の作業を行う必要があります。

非公開 NPM パッケージの認証トークンを Dataform リポジトリに保存する専用の Secret Manager シークレットを作成します。
1. NPM レジストリから取得したパッケージの認証トークンをシークレットに追加します。
非公開 NPM パッケージのすべての認証トークンを 1 つのシークレット内のリポジトリに保存する必要があります。Dataform リポジトリごとに 1 つの専用シークレットを作成する必要があります。シークレットは JSON 形式にする必要があります。
シークレットをアップロードして Dataform リポジトリに保存します。
.npmrc ファイルを作成し、パッケージの認証トークンをファイルに追加します。

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

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

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

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

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

Secret Manager でシークレットを作成します。
1. [シークレットの値] フィールドに、次の形式で 1 つ以上の認証トークンを入力します。
```
{
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}
```
以下を置き換えます。
- AUTHENTICATION_TOKEN_NAME: 認証するパッケージを識別するトークンの一意の名前。
- TOKEN_VALUE: NPM レジストリから取得した認証トークンの値。
Dataform サービスエージェントにシークレットへのアクセス権を付与します。

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

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

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

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