이 페이지에서 다루지 않는 문제를 해결하는 데 도움이 필요한 경우 Google Cloud 지원팀에 문의하세요.
내보낸 Google Sheets에 항목 링크가 없음
이 문제는 다음 조건으로 인해 내보내기 유틸리티가 항목 링크를 자동으로 건너뛰는 경우에 발생합니다.
권한 부족 (수정된 리소스): 링크와 연결된 소스 항목 또는 대상 항목을 보는 데 필요한 IAM 권한이 없습니다.
잘못된 항목 링크 유형: 항목 링크에서 지원되지 않거나 인식되지 않는 관계 유형을 사용합니다. 유효한 유형은
definition,related,synonym으로 제한됩니다.불완전한 항목 참조: 항목 메타데이터에 필수 스키마 필드가 누락되어 유효성 검사에서 리소스를 건너뜁니다.
이 문제를 해결하려면 다음 검사를 실행하세요.
권한 확인: 스크립트를 실행하는 주 구성원에게 필요한 역할이 부여되었는지 확인합니다.
실행 로그 검사: 터미널 또는 스크립트 로그에서
Skipping redacted entrylink가 포함된 경고를 확인합니다. 로그는 건너뛴 항목 링크의 특정 리소스 ID와 생략된 이유를 출력합니다.링크 스키마 유효성 검사: 이전에 이러한 링크를 프로그래매틱 방식으로 수정한 경우 속성이 스키마 요구사항과 일치하는지 확인합니다.
용어집 오류에 용어가 없음
용어집을 Google Sheets로 내보낼 때
비즈니스 용어집에
활성 용어가 포함되어 있음에도 불구하고 실행이 실패하거나
No terms found in the glossary메시지와 함께 빈 결과가 반환됩니다.
이 문제는 스크립트에서 지정된 용어집을 찾을 수 없거나 콘텐츠를 가져오는 데 필요한 액세스 권한이 없는 경우에 발생합니다. 일반적인 원인은 다음과 같습니다.
- 잘못된 용어집 URL: 실행 매개변수에 구성된 용어집 URL이 잘못되었거나 철자가 틀렸습니다.
- IAM 권한 부족: 스크립트를 실행하는 인증된 서비스 계정 또는 사용자 인증 정보에 대상 용어집 내에서 용어를 보거나 나열할 권한이 없습니다.
- 용어집 ID 불일치: 스크립트 명령어에 지정된 용어집 ID가 Knowledge Catalog의 실제 용어집 리소스 ID와 일치하지 않습니다.
이 문제를 해결하려면 구성 및 권한을 확인하세요.
용어집 ID 확인: Google Cloud console에서 Knowledge Catalog 용어집 페이지로 이동하여 용어집을 선택하고 리소스 ID가 유틸리티 스크립트에 전달하는 ID와 일치하는지 확인합니다.
IAM 권한 확인: 인증된 사용자 인증 정보 (서비스 계정 또는 가장된 사용자 계정)에 필요한 역할이 부여되었는지 확인합니다.
용어집 URL 구조 검증: 스크립트에 직접 리소스 경로 또는 URL을 전달하는 경우 올바른 Knowledge Catalog 리소스 형식을 따르는지 확인합니다.
projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID
Knowledge Catalog 경고에서 항목을 찾을 수 없음
항목 링크 가져오기 작업 중에 스크립트가 일시중지되고 다음과 유사한 경고가 표시됩니다.
Found X entries not found in Knowledge Catalog. EntryLinks associated with
these entries will be skipped. Continue with import? [y/N]:
이 문제는 Google Sheets에 Knowledge Catalog에 없는 데이터 애셋 또는 용어집 용어를 참조하는 항목 링크가 포함되어 있는 경우에 발생합니다.
이 문제를 해결하려면 다음 옵션 중 하나를 선택합니다.
부분 가져오기를 진행하려면 프롬프트에서
y를 입력합니다. 유틸리티는 모든 유효한 항목 링크를 가져오고 누락된 리소스를 참조하는 링크만 건너뜁니다.취소하고 누락된 리소스를 수정하려면
n을 입력하여 실행을 취소합니다. 소스 문서의 항목 ID가 Knowledge Catalog의 리소스 이름과 정확히 일치하는지 확인합니다. 누락된 리소스 또는 오타를 수정한 후 가져오기 스크립트를 다시 실행합니다.
가져오기 작업이 실패하거나 중간에 중단됨
가져오기 작업이 실행 중에 중단되거나 실패하는 경우 전체 프로세스를 다시 시작하거나 소스 Google Sheets를 수정할 필요가 없습니다.
유틸리티는 Cloud Storage 스테이징 버킷의 보관 폴더를 사용하여 가져온 배치를 추적합니다.
작업을 재개하려면 다음 단계를 따르세요.
가져오기 유틸리티를 다시 실행합니다. 유틸리티는 이전 실행의 상태를 감지하고 다음 프롬프트를 표시합니다.
Found X existing file(s) in archive folder from a previous incomplete import Continue using existing files? [y/N]:y를 입력합니다. 유틸리티는 이미 가져온 배치를 건너뛰고 나머지 파일만 처리합니다.
실행 중 스크립트 시간 초과 또는 SSL 오류
가져오기 또는 내보내기 유틸리티 스크립트를 실행하는 동안 실행이 중지되거나 시간이 초과되거나 터미널에 SSL 오류가 반환됩니다.
이 문제는 다음과 같은 네트워크 수준 오류로 인해 발생합니다.
- 기업 프록시 또는 방화벽 가로채기: 보안 프록시 또는 방화벽이 HTTPS 트래픽을 가로채고 검사하여 SSL 인증서를 무효화합니다.
- 활성 VPN 제한: VPN 구성이 특정 Google Cloud API 또는 Google Sheets 엔드포인트로의 아웃바운드 트래픽을 제한합니다.
- 로컬 네트워크 불안정: 인터넷 연결이 일시적으로 끊어져 세션이 중단되었습니다.
이러한 네트워크 문제를 해결하려면 다음 단계를 시도해 보세요.
네트워크 연결이 안정적인지 확인합니다.
프록시 및 방화벽 설정 검사
VPN 구성을 확인합니다.
기본 제공 재시도 사용: 유틸리티 스크립트에는 일시적인 네트워크 결함에 대한 기본 제공 재시도 로직이 있습니다. 네트워크가 일시적으로 끊어진 경우 실행을 다시 시작하기 전에 스크립트가 재시도 시도를 완료할 때까지 기다립니다.
잘못된 스프레드시트 URL 오류
가져오기 또는 내보내기 유틸리티를 실행하려고 하면 명령줄 인터페이스에서 Invalid spreadsheet URL 오류를 반환하고 실행이 중지됩니다.
이 문제는 스크립트에서 제공된 Google Sheets 링크를 파싱할 수 없거나 파일 보기 권한이 없는 경우에 발생합니다. 일반적인 원인은 다음과 같습니다.
- 잘못된 형식의 URL: URL이 표준 Google Sheets 경로 형식과 일치하지 않습니다.
- 스프레드시트 ID 누락: 경로에 특정 시트를 가리키는 고유한 영숫자 ID가 없습니다.
- 액세스 제한: 인증된 서비스 계정에 시트를 보거나 수정할 권한이 없어 유틸리티에서 링크를 검증할 수 없습니다.
이 문제를 해결하려면 스프레드시트 링크 및 액세스 설정을 확인하세요.
URL 프리픽스 검증: 유틸리티에 전달하는 스프레드시트 URL이 다음 표준 Google Sheets 경로로 시작하는지 확인합니다.
https://docs.google.com/spreadsheets/스프레드시트 ID 확인: URL에 시트의 고유 ID가 포함되어 있는지 확인합니다. 유효한 URL은 이 구조를 따라야 합니다:
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit액세스 권한 확인: 브라우저에서 Google Sheets를 열고 공유를 클릭한 후 서비스 계정 이메일을 편집자로 추가했는지 확인합니다.
잘못된 용어집 URL 오류
용어집 가져오기 또는 내보내기 유틸리티를 실행하려고 하면 명령줄 인터페이스에서 Invalid glossary URL 오류를 반환하고 실행이 중지됩니다.
이 문제는 스크립트에서 제공된 Knowledge Catalog 용어집 리소스 경로를 파싱할 수 없거나 리소스를 볼 권한이 없는 경우에 발생합니다. 일반적인 원인은 다음과 같습니다.
- 잘못된 형식의 리소스 경로: 리소스 경로가 표준 Knowledge Catalog 용어집 경로 형식과 일치하지 않습니다.
- 잘못된 ID: 경로에 잘못된 프로젝트 ID, 리전 위치 또는 용어집 ID가 포함되어 있습니다.
- 액세스 제한 또는 리소스 누락: 용어집이 없거나 인증된 서비스 계정에 액세스하는 데 필요한 IAM 권한이 없습니다.
이 문제를 해결하려면 용어집 리소스 경로 및 사용자 인증 정보를 확인하세요.
리소스 경로 구조 검증: 유틸리티에 전달하는 용어집 경로가 다음 표준 Knowledge Catalog 형식과 일치하는지 확인합니다.
projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID경로의 식별자 확인: 올바른 프로젝트 ID, 위치, 용어집 ID를 사용합니다.
리소스 존재 및 액세스 확인: 용어집이 지정된 ID로 존재하고 인증된 서비스 계정에 필요한 IAM 역할이 부여되었는지 확인합니다.
실행 로그 보기
가져오기 및 내보내기 유틸리티는 실행될 때 세부 실행 로그를 생성합니다. 이러한 로그는 전송 프로세스를 감사하고 건너뛴 항목 또는 형식 경고를 식별하는 데 도움이 됩니다.
- 로그 위치: 가져오기 및 내보내기 유틸리티는 로컬 실행 경로의
logs/디렉터리에 로그 파일을 씁니다. - 로그 형식: 각 로그 파일에 타임스탬프가 추가되므로 특정 실행의 로그를 찾을 수 있습니다.