Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

BigQuery Studio Git 저장소로 코드 관리

BigQuery Studio Git 저장소를 사용하면 BigQuery Studio 파일 브라우저에서 직접 SQL 스크립트, 노트북, 기타 코드 애셋을 버전 제어할 수 있습니다. Google Cloud 콘솔을 나가지 않고도 원격 Git 저장소를 클론하고 브랜치를 관리하며 Git 작업을 수행할 수 있습니다.

기존 저장소와 비교하여 이 통합은 왼쪽 창의 사용자 루트 폴더 아래에 간소화된 폴더 기반 환경을 제공합니다. 원격 Git 저장소에 대한 연결을 유지하면서 표준 파일 및 디렉터리와 같은 코드 애셋과 상호작용할 수 있습니다.

제한사항

BigQuery Studio Git 저장소는 사용자 루트 폴더 컨텍스트로 제한되며 비공개 사용을 위한 것입니다. 이러한 저장소를 다른 사용자와 공유하지 마세요. 이러한 저장소는 프로젝트의 애셋을 가상으로 표현한 사용자 루트 폴더에 표시되지만 기술적으로는 프로젝트 수준에서 생성됩니다.
Git 프록시와 함께 Developer Connect 계정 커넥터를 사용하는 것은 지원되지 않습니다.
마운트 위치 내의 파일 시스템 작업은 Dataform 할당량을 사용합니다.
파일 수가 많거나, 파일 크기가 크거나, 브랜치가 많거나, 커밋 기록이 깊고 복잡한 저장소는 클론하는 데 시간이 더 오래 걸립니다. 클론 작업이 작업 제한 시간을 초과하여 저장소가 생성되지 않을 수 있습니다. 커밋 기록이 깊은 저장소의 클론 시간을 줄이려면 얕은 복제를 만들면 됩니다. 필요한 경우 나중에 커밋을 더 가져올 수 있습니다.
BigQuery Studio Git 저장소 마운트에 저장된 노트북 파일의 크기는 30MB를 초과할 수 없습니다. 파일이 30MB보다 큰 경우 마운트된 위치 외부의 Colab 런타임 로컬 저장소에 저장합니다.
마운트 외부에서 Git 저장소를 변경하는 경우(예: 왼쪽 창에서 파일을 수정하거나 이름을 변경하는 경우) 해당 변경사항이 노트북 런타임의 마운트 내에 표시되는 데 최대 60초가 걸릴 수 있습니다. CACHE_TTL_SECONDS 매개변수를 생성자에 전달하여 이 기간을 조정할 수 있습니다.
```
  FuseWidget(CACHE_TTL_SECONDS=NUMBER)
```
NUMBER을 캐시가 유효하게 유지되는 시간(초)으로 바꿉니다. 이 값을 줄이면 동기화 빈도가 증가하고 Dataform 할당량이 더 빠르게 소모됩니다.

시작하기 전에

Google Cloud 프로젝트에서 Developer Connect API를 사용 설정합니다.

API 사용 설정하기

필요한 역할

BigQuery Studio Git 저장소로 코드를 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Developer Connect OAuth 사용자 (roles/developerconnect.oauthUser) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 BigQuery Studio Git 저장소로 코드를 관리하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

BigQuery Studio Git 저장소로 코드를 관리하려면 다음 권한이 필요합니다.

resourcemanager.projects.get
resourcemanager.projects.list
developerconnect.operations.list
developerconnect.operations.get
developerconnect.locations.list
developerconnect.locations.get
developerconnect.users.startOAuth
developerconnect.users.finishOAuth
developerconnect.users.fetchAccessToken
developerconnect.users.getSelf
developerconnect.users.deleteSelf
developerconnect.accountConnectors.get
developerconnect.accountConnectors.list
developerconnect.accountConnectors.gitProxyUse
developerconnect.accountConnectors.httpProxyUse
developerconnect.accountConnectors.gitProxyRead
developerconnect.accountConnectors.gitProxyWrite
developerconnect.accountConnectors.httpProxyRead
developerconnect.accountConnectors.httpProxyWrite
developerconnect.accountConnectors.fetchUserRepositories

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

저장소의 보안 고려사항

BigQuery의 코드 애셋은 Dataform에서 제공하므로 이러한 애셋에 액세스할 수 있는 사용자에 대한 다음 보안 영향을 고려해야 합니다.

코드 애셋의 공개 상태는 프로젝트 수준 Dataform 권한에 따라 제어됩니다. BigQuery 작업 사용자, BigQuery Studio 사용자, BigQuery 사용자와 같은 표준 BigQuery 역할에 포함된 dataform.repositories.list 권한이 있는 사용자는 애셋을 만들었는지 또는 애셋이 공유되었는지 여부와 관계없이 Google Cloud 프로젝트의 탐색기 패널에서 모든 코드 애셋을 볼 수 있습니다. 공개 상태를 제한하려면 dataform.repositories.list 권한을 제외하는 커스텀 역할을 만들면 됩니다.
Dataform 서비스 에이전트와 공유된 모든 보안 비밀은 이러한 애셋을 수정할 수 있는 사용자가 액세스할 수 있습니다. 사용자 인증 정보를 보호하려면 신뢰할 수 있는 사용자로 생성 및 수정 액세스 권한을 제한하고 Dataform 서비스 에이전트가 액세스할 수 있는 보안 비밀을 제한하세요. 자세한 내용은 패키지 설치 중 보안 비밀 액세스를 참조하세요.

자세한 내용은 Dataform 권한의 보안 고려사항을 참조하세요.

BigQuery Studio Git 저장소 만들기

Git 저장소를 만들 때는 다음 요구사항을 고려하세요.

원격 저장소가 공개 인터넷에 공개되어 있지 않은 경우(예: 방화벽 뒤에 있는 경우) 원격 Git 저장소를 Git 저장소에 연결할 수 없습니다. 이 경우 필요한 Dataform 이그레스 IP 주소 범위를 방화벽 규칙에 추가하여 보호된 원격 저장소에 연결할 수 있습니다.
dataform.restrictGitRemotes 조직 정책에서 허용되지 않은 원격 Git 저장소에 연결된 Git 저장소를 만들려면 먼저 정책의 allowedValues 목록에 해당 원격 Git 저장소를 추가한 후 Git 저장소를 만듭니다. 자세한 내용은 원격 저장소 제한을 참조하세요.

Git 저장소를 만들려면 다음을 수행합니다.

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

BigQuery로 이동
왼쪽 창에서 파일을 클릭하여 파일 브라우저를 엽니다.

왼쪽 창이 표시되지 않으면 왼쪽 창 펼치기를 클릭하여 창을 엽니다.
사용자 루트 노드 옆에 있는 작업 보기 > 만들기 > Git 저장소를 클릭합니다.
원격 Git 저장소의 URL을 입력합니다.
BigQuery Studio는 기존 Developer Connect 계정 커넥터를 사용할 수 있는지 감지합니다. 다음 중 한 가지 방법을 사용하시기 바랍니다.
- 계정 커넥터가 있으면 Git 저장소의 표시 이름이 미리 채워집니다. 이러한 값을 수정할 수 있습니다.
- 계정 커넥터가 없으면 계정 커넥터 만들기를 클릭하여 새 계정 커넥터를 만듭니다.
- Developer Connect 계정 커넥터를 사용하지 않으려면 다른 연결 유형 사용을 클릭하여 HTTPS 또는 SSH를 사용하여 연결합니다.
선택사항: 커밋 기록이 제한된 얕은 복제 저장소를 만들려면 고급 옵션을 클릭한 후 얕은 복제 체크박스를 선택합니다.
1. 깊이 필드에 제한된 커밋 기록에서 가져올 커밋 수를 입력합니다.
연결을 클릭합니다.

파일 수정

파일을 수정하려면 SQL 스크립트 또는 노트북과 같은 파일 노드를 클릭하여 새 편집기 탭에서 파일을 엽니다.

변경사항은 자동으로 저장됩니다.

파일 관리

각 항목과 연결된 작업 메뉴를 사용하여 표준 관리 작업을 수행할 수 있습니다. 이러한 옵션에 액세스하려면 디렉터리 또는 파일 옆에 있는 작업 열기를 클릭합니다.

디렉터리 수준에서 다음 작업을 수행할 수 있습니다.

저장소에서 만들기: SQL 쿼리, 노트북, 데이터 캔버스, 데이터 준비, 파일 또는 하위 디렉터리를 포함한 새 코드 애셋을 만듭니다.
저장소에 업로드: 로컬 머신의 기존 파일을 선택한 디렉터리로 가져옵니다.
이름 바꾸기: 디렉터리 이름을 변경합니다.
이동: 디렉터리를 재배치합니다. 디렉터리는 동일한 Git 저장소 내의 다른 위치로만 이동할 수 있습니다. 자세한 내용은 파일 및 디렉터리 이동 또는 복사를 참조하세요.
삭제: 로컬 작업공간에서 디렉터리와 모든 콘텐츠를 영구적으로 삭제합니다.

파일 수준에서 다음 작업을 수행할 수 있습니다.

열기 또는 다음에서 열기: 기본 편집기 또는 특정 애플리케이션(예: 특정 노트북 환경)에서 파일을 봅니다.
이름 바꾸기: 파일 이름을 변경합니다.
복사: 파일의 사본을 만듭니다. 동일한 Git 저장소 내의 디렉터리에만 파일을 복사할 수 있습니다.
이동: 파일을 동일한 Git 저장소 내의 다른 디렉터리로 재배치합니다. 자세한 내용은 파일 및 디렉터리 이동 또는 복사를 참조하세요.
다운로드: 파일 사본을 로컬 머신에 저장합니다.
삭제: 작업공간에서 파일을 삭제합니다.

파일 및 디렉터리 이동 또는 복사

파일과 디렉터리를 이동하거나 복사할 수 있지만 동일한 Git 저장소 내에 있어야 합니다.

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

BigQuery로 이동
왼쪽 창에서 파일을 클릭하여 파일 브라우저를 엽니다.
이동하거나 복사할 파일 또는 디렉터리를 찾습니다.
작업 열기 > 이동 또는 복사를 클릭합니다.
대화상자가 나타나면 동일한 Git 저장소 내에서 대상 디렉터리를 선택합니다.
이동 또는 복사를 클릭합니다.

변경사항 커밋 및 푸시

로컬 수정사항을 원격 저장소와 동기화하려면 다음을 수행합니다.

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

BigQuery로 이동
왼쪽 창에서 저장소를 클릭합니다.
선택사항: 수정된 파일 위로 마우스를 가져가고 차이 보기를 클릭하여 로컬 버전과 마지막으로 커밋된 버전을 한 줄씩 비교합니다.
커밋 메시지 필드에 변경사항에 대한 설명을 입력합니다.
커밋을 클릭합니다. 변경사항이 로컬 브랜치의 Git 기록에 저장됩니다.
원격 브랜치로 푸시를 클릭합니다. 변경사항이 원격 저장소와 동기화됩니다.

새 브랜치 체크아웃

로컬 브랜치를 관리하고 기존 로컬 또는 원격 추적 브랜치를 기반으로 새 로컬 브랜치를 만들 수 있습니다.

저장소 탭의 브랜치 섹션에서 체크아웃된 로컬 브랜치를 확인할 수 있습니다. CURRENT 라벨은 활성 브랜치를 나타내고 DEFAULT 라벨은 저장소의 기본 브랜치를 나타냅니다.

새 브랜치를 체크아웃하려면 다음 단계를 따르세요.

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

BigQuery로 이동
왼쪽 창에서 저장소를 클릭합니다.
브랜치 섹션을 펼칩니다.
브랜치 옆에 있는 작업 열기를 클릭한 후 새 브랜치 체크아웃을 클릭합니다.
소스 브랜치 메뉴에서 새 브랜치의 기반으로 사용할 브랜치(예: origin/main)를 선택합니다.
브랜치 이름 필드에 새 브랜치의 이름을 입력합니다.

참고: 원격 추적 브랜치를 소스로 선택한 경우 브랜치 이름 필드가 해당 브랜치 이름으로 미리 채워집니다.
결제를 클릭합니다. BigQuery Studio는 먼저 소스 브랜치를 체크아웃합니다. 제공된 브랜치 이름이 새 브랜치를 나타내는 경우 해당 소스를 기반으로 생성됩니다. 새 브랜치가 활성 브랜치가 되고 Git 저장소의 콘텐츠가 체크아웃된 브랜치의 상태를 반영하도록 자동으로 업데이트됩니다.

커밋 기록 보기

활성 브랜치의 커밋 기록을 볼 수 있습니다. 저장소가 얕은 복제로 생성된 경우 브랜치 커밋 기록 창에 저장소의 커밋 기록이 제한되어 있음을 나타내는 정보 배너가 표시됩니다. 더 많은 커밋을 가져와 로컬 기록을 확장할 수 있습니다.

커밋 기록을 보려면 다음을 수행합니다.

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

BigQuery로 이동
왼쪽 창에서 저장소를 클릭합니다.
기본 버전 제어 작업 버튼 옆에 있는 화살표 드롭다운을 클릭한 다음 커밋 기록 보기를 클릭합니다.

브랜치 커밋 기록 창이 열리고 활성 브랜치의 커밋 기록이 표시됩니다.
선택사항: 얕은 복제 저장소에 대한 추가 커밋을 가져오려면 브랜치 커밋 기록 창에서 가져오기를 클릭합니다.
1. 가져오기 (얕은 복제) 대화상자의 가져올 추가 커밋 필드에 저장소 기록에서 가져올 추가 커밋 수를 입력합니다.
  
  0를 입력하면 추가 이전 커밋이 검색되지 않지만 BigQuery Studio는 표준 가져오기를 수행하여 원격 참조 및 메타데이터를 동기화합니다.
2. 가져오기을 클릭하세요.
  
  모든 커밋이 검색될 때까지 필요에 따라 가져오기를 반복할 수 있습니다.

Git 저장소 마운트에서 노트북 파일에 액세스

BigQuery Studio Git 저장소 내에서 노트북에 액세스할 때 호스트 Git 저장소를 노트북의 런타임에 마운트할 수 있습니다. 마운트는 원격 Git 저장소가 노트북 런타임의 로컬 저장소인 것처럼 표시하는 연결입니다. 이렇게 하면 노트북이 동일한 저장소 내의 다른 파일 및 쿼리 스크립트에 직접 액세스하고 읽고 쓸 수 있습니다.

Git 저장소 마운트

Git 저장소를 마운트하려면 노트북에서 다음 Python 코드를 실행합니다.

from google_dataform_fuse_widget import FuseWidget
FuseWidget()

노트북이 마운트에 연결되면 다음과 같은 변경사항이 발생합니다.

노트북 세션의 현재 작업 디렉터리가 Git 저장소 내의 상대 경로를 반영하도록 업데이트됩니다. 이렇게 하면 경로 기반 파일 액세스가 자동으로 작동합니다.
노트북 런타임의 Git 저장소 경로가 Python 시스템 경로에 추가되므로 표준 Python 가져오기 문을 사용하여 Git 저장소의 쿼리 스크립트와 파일을 노트북에 직접 로드할 수 있습니다.

마운트 및 연결 관리

다음 컨트롤을 사용하여 작업공간을 관리합니다.

작업공간 마운트: Git 저장소의 마운트 프로세스를 시작합니다. 마운트는 공유 리소스이므로 동일한 Colab 런타임의 여러 노트북이 동일한 Git 저장소를 사용하는 경우 동일한 마운트를 사용합니다.
작업공간 마운트 해제: Git 저장소의 마운트 프로세스를 중지합니다. 작업공간을 마운트 해제하면 해당 Colab 런타임에서 이를 사용하던 모든 노트북에서 마운트를 사용할 수 없게 됩니다.
작업공간 연결: 현재 노트북 세션의 활성 마운트에 대한 연결을 시작합니다. 연결하면 Git 저장소를 포함하도록 노트북의 작업 디렉터리와 시스템 경로가 업데이트되어 파일에 액세스하고 가져올 수 있습니다.
작업공간 연결 해제: 현재 노트북 세션의 마운트 연결을 종료하고 기본 상태로 재설정합니다. 연결을 해제해도 다른 활성 노트북 세션의 마운트 연결 상태에는 영향을 미치지 않습니다. 세션 연결을 종료하려면 작업공간 연결 해제 버튼을 사용하는 것이 좋습니다.
복구: 마운트 또는 연결을 사용할 수 없게 되면 정상 상태로 복원합니다.

마운트를 초기화한 후 상태 표시줄에서 마운트의 실시간 상태 및 활성 경로를 확인합니다. 가능한 상태는 연결됨, 마운트됨, 중지됨, 비정상입니다.

다음 단계

노트북을 만드는 방법 알아보기
저장된 쿼리를 만드는 방법 알아보기
저장소 만들기 및 관리 방법 알아보기
폴더로 코드 애셋을 구성하는 방법을 알아보세요.