JavaScript 패키지 사용

이 문서에서는 다음을 수행하는 방법을 보여줍니다.

• Dataform 저장소에 JavaScript 패키지를 설치합니다.
• 저장소에 설치할 수 있도록 비공개 NPM 패키지를 인증합니다.
• 워크플로를 개발하는 데 사용할 수 있는 맞춤 JavaScript 패키지를 만듭니다.

시작하기 전에

1. Google Cloud 콘솔에서 Dataform 페이지로 이동합니다.

   Dataform으로 이동

2. 다음 중 하나 또는 둘 다를 실행합니다.

   1. 저장소에 패키지를 설치하거나 비공개 NPM 패키지를 인증하여 설치를 사용 설정하려면 다음 단계를 따르세요.
      1. 저장소를 선택하거나 만듭니다.
      2. 개발 작업공간을 선택하거나 만듭니다.
      3. (선택사항) 비공개 패키지를 설치하려면 비공개 패키지를 인증합니다.
      4. 저장소에 package.json 파일이 없으면 package.json을 만들고 Dataform Core 패키지를 이동합니다.
   2. 패키지를 만들려면 다음 단계를 따르세요.
      1. 패키지 전용 Dataform 저장소를 만듭니다. 저장소 이름을 패키지 이름과 일치시킵니다.
      2. 패키지를 호스팅하는 서드 파티 Git 저장소에 저장소를 연결합니다.
      3. Dataform 저장소에서 작업공간을 만들고 초기화합니다.

3. 이 문서의 태스크를 완료하는 데 필요한 권한이 있는지 확인합니다.

필요한 역할

이 문서의 태스크를 완료하는 데 필요한 권한을 얻으려면 관리자에게 다음 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 파일에 패키지를 종속 항목으로 추가해야 합니다.

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을 제3자 패키지 저장소의 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. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 .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에서 자바스크립트 파일로 패키지 함수 또는 상수 가져오기

Dataform에서 JavaScript 파일 내 패키지의 함수 또는 상수를 사용하려면 먼저 이를 파일로 가져와야 합니다.

패키지의 함수 또는 상수를 JavaScript 파일로 가져오려면 다음 단계를 따르세요.

1. 작업공간의 파일 창에서 패키지를 사용하려는 .js 파일을 선택합니다.

2. 파일에서 다음 형식으로 함수 또는 상수를 가져옵니다.

   const { EXPORT-NAME } = require("PACKAGE-NAME");
   

   1. EXPORT-NAME을 패키지 index.js 파일의 module.exports에서 선언된 사용하려는 함수 또는 상수의 이름으로 바꿉니다.
   2. PACKAGE-NAME을 사용하려는 패키지 이름으로 바꿉니다.

3. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 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. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 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. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 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. 변경사항을 커밋하고 푸시합니다.

다음 코드 샘플은 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 저장소에 설치하도록 설정하는 방법을 설명합니다.

Dataform 저장소에 비공개 NPM 패키지를 설치하고 이를 사용하여 워크플로를 개발하려면 먼저 Dataform에서 패키지를 인증해야 합니다. 저장소의 첫 번째 비공개 패키지와 저장소의 후속 비공개 패키지의 인증 프로세스는 다릅니다.

Dataform 저장소에서 첫 번째 비공개 패키지 인증

Dataform에서 비공개 NPM 패키지를 인증하려면 Dataform 저장소에 첫 번째 비공개 NPM 패키지를 설치하기 전에 다음을 실행해야 합니다.

1. Dataform 저장소에 비공개 NPM 패키지의 인증 토큰을 저장하는 데 전용된 Secret Manager 보안 비밀을 만듭니다.

   1. NPM 레지스트리에서 가져온 패키지의 인증 토큰을 보안 비밀에 추가합니다.

   저장소의 비공개 NPM 패키지의 모든 인증 토큰을 단일 보안 비밀에 저장해야 합니다. Dataform 저장소당 전용 보안 비밀을 하나씩 만들어야 합니다. 보안 비밀은 JSON 형식이어야 합니다.

2. Dataform 저장소에 보안 비밀을 업로드합니다.

3. .npmrc 파일을 만들고 패키지의 인증 토큰을 파일에 추가합니다.

   .npmrc 파일의 인증 토큰이 업로드된 보안 비밀의 인증 토큰과 일치해야 합니다.

비공개 NPM 패키지를 인증한 후에는 Dataform 저장소에 패키지를 설치할 수 있습니다.

비공개 패키지 인증을 위한 보안 비밀 만들기

Dataform 저장소에서 비공개 NPM 패키지를 인증하려면 Secret Manager 보안 비밀을 만들고 보안 비밀 내에서 Dataform 저장소에 설치하려는 모든 비공개 패키지의 인증 토큰을 정의해야 합니다. 비공개 NPM 패키지마다 인증 토큰을 하나 정의하고 모든 인증 토큰을 각 저장소의 단일 보안 비밀에 저장합니다. 보안 비밀은 JSON 형식이어야 합니다.

비공개 NPM 패키지의 인증 토큰으로 보안 비밀을 만들려면 다음 단계를 따르세요.

1. Secret Manager에서 보안 비밀을 만듭니다.

   1. 보안 비밀 값 필드에 다음 형식으로 인증 토큰을 하나 이상 입력합니다.

   {
     "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
   }
   

   다음을 바꿉니다.

   • AUTHENTICATION_TOKEN_NAME: 인증한 패키지를 식별하는 토큰의 고유한 이름입니다.
   • TOKEN_VALUE: NPM 레지스트리에서 가져온 인증 토큰의 값입니다.

2. Dataform 서비스 계정에 보안 비밀에 대한 액세스 권한을 부여합니다.

   Dataform 서비스 계정의 형식은 다음과 같습니다.

   [e-mail]
   

   1. 액세스 권한을 부여할 때는 Dataform 서비스 계정에 roles/secretmanager.secretAccessor 역할을 부여해야 합니다.

Dataform 저장소에 비공개 패키지 인증을 위한 보안 비밀 업로드

Dataform 저장소에 비공개 NPM 패키지를 처음 설치하기 전에 패키지의 인증 토큰이 포함된 보안 비밀을 저장소에 업로드합니다.

비공개 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 저장소에 설치하고 패키지에서 내보낼 수 있는 콘텐츠(예: 상수 및 함수)를 사용하여 워크플로를 개발할 수 있습니다.

패키지를 만드는 대신 include로 단일 Dataform 저장소에서 JavaScript 함수 및 상수를 재사용할 수 있습니다. 자세한 내용은 Dataform에서 include로 변수 및 함수 재사용을 참고하세요.

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. 변경사항을 커밋하고 푸시합니다.

다음 패키지 코드 샘플은 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 }

다음 단계

• 필요한 Dataform Core 패키지를 관리하는 방법은 Dataform Core 패키지 관리를 참고하세요.
• Dataform의 패키지에 대한 자세한 내용은 패키지를 사용하여 여러 저장소 간에 코드 재사용을 참조하세요.
• JavaScript 변수 및 함수를 Dataform에서 재사용할 수 있는 방법을 알아보려면 Dataform에서 include로 변수 및 함수 재사용을 참조하세요.