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는 저장소의 .npmrc 파일에 정의된 레지스트리 범위와 일치해야 합니다.
      • 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"
   }