BigQuery로 내보내기

이 주제에서는 조직, 폴더 또는 프로젝트의 애셋 메타데이터를 BigQuery 테이블로 내보낸 다음 인벤토리에서 데이터 분석을 실행하는 방법을 보여줍니다. BigQuery는 사용자가 커스텀 스크립트를 사용하지 않고도 데이터를 분석하고 의미 있는 정보를 생성할 수 있는 SQL과 유사한 환경을 제공합니다.

시작하기 전에

시작하기 전에 다음 단계를 완료하세요.

  1. API 명령어를 실행할 프로젝트에서 Cloud 애셋 인벤토리 API를 사용 설정합니다.
    Cloud 애셋 인벤토리 API 사용 설정

  2. API 또는 gcloud 도구를 사용하여 Cloud 애셋 인벤토리 API를 호출하기 위해 필요한 권한을 구성합니다.

  3. 다음 단계에 따라 환경 설정을 완료합니다.

    gcloud

    gcloud 도구를 사용하여 Cloud 애셋 인벤토리 API를 호출하는 환경을 설정하려면 로컬 클라이언트에 Cloud SDK를 설치합니다.

    API

    Unix curl 명령어로 Cloud 애셋 인벤토리 API를 호출하도록 환경을 설정하려면 다음 단계를 완료합니다.

    1. Google OAuth 시스템과 상호작용할 수 있도록 로컬 머신에 oauth2l을 설치합니다.
    2. Unix curl 명령어에 대한 액세스 권한이 있는지 확인하세요.
    3. 프로젝트, 폴더 또는 조직에서 다음 역할 중 하나를 계정에 부여했는지 확인합니다.

      • Cloud 애셋 뷰어 역할(roles/cloudasset.viewer)
      • 소유자 기본 역할(roles/owner)

    gcloud 도구는 결제 프로젝트를 소비자 프로젝트로 사용합니다. 권한 거부 메시지가 표시되면 결제 프로젝트가 핵심 프로젝트와 다른지 확인할 수 있습니다.

    gcloud config list
    

    결제 프로젝트를 소비자 프로젝트로 설정합니다.

    gcloud config set billing/quota_project CONSUMER_PROJECT_NUMBER
    
  4. Cloud 애셋 인벤토리 API가 사용 설정되지 않은 프로젝트의 BigQuery 데이터 세트로 내보내는 경우 대상 프로젝트의 service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com 서비스 계정에도 다음 역할을 부여해야 합니다.

    • BigQuery 데이터 편집자 역할(roles/bigquery.dataEditor)
    • BigQuery 사용자 역할(roles/bigquery.user)

    API를 한 번 호출하여 서비스 계정을 만들거나 다음 명령어를 사용하여 서비스 계정을 만들고 서비스 에이전트 역할을 수동으로 부여할 수 있습니다.

      gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
      gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com --role=roles/cloudasset.serviceAgent
    

  5. BigQuery 데이터 세트 만들기

애셋 스냅샷 내보내기

특정 해당 타임스탬프에서 애셋 스냅샷을 내보내려면 다음 단계를 완료합니다.

gcloud

프로젝트에서 애셋을 내보내려면 다음 명령어를 실행합니다. 이 명령어는 내보낸 스냅샷을 BIGQUERY_TABLE의 BigQuery 테이블에 저장합니다.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force

각 항목의 의미는 다음과 같습니다.

  • CONTENT_TYPE은 애셋의 콘텐츠 유형입니다.
  • PROJECT_ID는 메타데이터를 내보내는 프로젝트의 ID입니다. 이 프로젝트는 내보내기를 실행 중인 프로젝트이거나 다른 프로젝트일 수 있습니다.
  • SNAPSHOT_TIME (선택사항)은 애셋의 스냅샷을 만들려는 시간입니다. 값은 현재 시간 또는 과거 시간이어야 합니다. 기본적으로 현재 시간으로 스냅샷을 찍습니다. 시간 형식에 대한 자세한 내용은 gcloud topic datetimes를 참조하세요.
  • BIGQUERY_TABLE은 메타데이터를 내보내는 테이블이며 projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME 형식입니다.
  • --output-bigquery-force는 대상 테이블을 덮어씁니다.

조직 또는 폴더의 애셋을 내보내려면 --project 대신 다음 플래그 중 하나를 사용합니다.

access-policy--organization용으로만 내보낼 수 있습니다.

API

프로젝트에서 애셋 메타데이터를 내보내려면 다음 명령어를 실행합니다. 이 명령어는 내보낸 스냅샷을 TABLE_NAME이라는 이름의 BigQuery 테이블에 저장합니다. exportAssets 메서드 자세히 알아보기

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

콘텐츠 유형 설정

모든 BigQuery 테이블은 열 이름, 데이터 유형, 기타 정보를 설명하는 스키마로 정의됩니다. 내보내기 중에 콘텐츠 유형을 설정하면 테이블의 스키마가 결정됩니다.

  • 리소스 또는 지정되지 않음: 콘텐츠 유형을 RESOURCE로 설정하거나 콘텐츠 유형을 설정하지 않는 경우 그림 1의 스키마가 있는 BigQuery 테이블을 만듭니다. Resource.data는 JSON 문자열로 표시되는 리소스 메타데이터입니다.

  • IAM 정책: REST API에서 콘텐츠 유형을 IAM_POLICY로 설정하거나 gcloud 도구에서 iam-policy로 설정하는 경우 그림 2에 표시된 스키마가 있는 BigQuery 테이블을 만듭니다. iam_policy RECORD가 완전히 확장됩니다.

  • 조직 정책: REST API에서 콘텐츠 유형을 ORG_POLICY로 설정하거나 gcloud 도구에서 org-policy로 설정하는 경우 그림 3에 표시된 스키마가 있는 BigQuery 테이블을 만듭니다.

  • VPCSC 정책: REST API에서 콘텐츠 유형을 ACCESS_POLICY로 설정하거나 gcloud 도구에서 access-policy로 설정하는 경우 그림 4에 표시된 스키마가 있는 BigQuery 테이블을 만듭니다.

  • OSConfig 인스턴스 인벤토리: REST API에서 OS_INVENTORY로 콘텐츠 유형을 설정하거나 gcloud 도구에서 os-inventory를 설정할 때 그림 5에 표시된 스키마가 있는 BigQuery 테이블을 만듭니다.

리소스 유형별 개별 테이블

리소스 유형별 특정 타임스탬프로 애셋 스냅샷을 내보내려면 다음 단계를 완료하세요.

gcloud

리소스 유형별로 프로젝트의 애셋을 내보내려면 다음 명령어를 실행합니다. 이 명령어는 스냅샷 결과가 비어 있거나 여러 BigQuery 테이블에 있는 경우 내보낸 스냅샷을 0 테이블에 저장합니다. 각 테이블에는 한 가지 애셋 유형의 결과가 포함되며 _(밑줄) 및 애셋 유형 이름과 연결된 BIGQUERY_TABLE이 있습니다. 영숫자가 아닌 문자는 _로 대체됩니다.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force \
     --per-asset-type

각 항목의 의미는 다음과 같습니다.

  • CONTENT_TYPE은 애셋의 콘텐츠 유형입니다.
  • PROJECT_ID는 메타데이터를 내보내는 프로젝트의 ID입니다. 이 프로젝트는 내보내기를 실행 중인 프로젝트이거나 다른 프로젝트일 수 있습니다.
  • SNAPSHOT_TIME (선택사항)은 애셋의 스냅샷을 만들려는 시간입니다. 값은 현재 시간 또는 과거 시간이어야 합니다. 기본적으로 현재 시간으로 스냅샷을 찍습니다. 유효한 시간 형식에 대한 자세한 내용은 gcloud topic datetimes를 참조하세요.
  • BIGQUERY_TABLE은 메타데이터를 내보내는 테이블이며 projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME 형식입니다.
  • --output-bigquery-force는 대상 테이블을 덮어씁니다.
  • --per-asset-type은 리소스 유형별로 여러 BigQuery 테이블로 내보냅니다.

API

리소스 유형별로 프로젝트의 애셋을 내보내려면 다음 명령어를 실행합니다. 이 명령어는 스냅샷 결과가 비어 있거나 여러 BigQuery 테이블에 있는 경우 내보낸 스냅샷을 0 테이블에 저장합니다. 각 테이블에는 한 가지 애셋 유형의 결과가 포함되며 _(밑줄) 및 애셋 유형 이름과 연결된 BIGQUERY_TABLE이 있습니다. 영숫자가 아닌 문자는 _로 대체됩니다. 자세한 내용은 exportAssets 메서드를 참조하세요.

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "separateTablesPerAssetType": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

테이블로 내보내지 못하면 전체 내보내기 작업이 실패하고 첫 번째 오류가 반환됩니다. 그러나 성공한 내보내기는 유지됩니다.

내보내기 중에 콘텐츠 유형을 설정하면 각 테이블의 스키마가 결정됩니다.

  • 리소스: 콘텐츠 유형을 RESOURCE로 설정하면 각 테이블의 스키마에 해당 애셋 유형의 Resource.data 필드의 중첩 필드에 매핑된 레코드 유형 열이 포함됩니다(BigQuery가 지원하는 최대 15개의 중첩 수준). projects/export-assets-examples/datasets/structured_export에서 예시 테이블의 유형별 BigQuery 스키마를 참조하세요.

  • IAM 정책, 조직 정책, VPCSC 정책 또는 지정되지 않음: 콘텐츠 유형을 IAM_POLICY, ORG_POLICY, ACCESS_POLICY로 설정하거나 콘텐츠 유형을 설정하지 않은 경우 애셋별 유형을 False로 설정하면 각 테이블은 동일한 스키마를 갖습니다. 자세한 내용은 콘텐츠 유형 설정 섹션의 스키마를 참조하세요.

JSON3BigQuery 유형 사이의 호환성 문제를 해결하기 위해 다음 유형이 JSON 문자열에 포함합니다.

  • google.protobuf.Timestamp
  • google.protobuf.Duration
  • google.protobuf.FieldMask
  • google.protobuf.ListValue
  • google.protobuf.Value
  • google.protobuf.Struct
  • google.api.*

파티션을 나눈 테이블로 내보내기

파티션을 나눈 테이블의 지정된 타임스탬프에서 애셋 스냅샷을 내보내려면 다음 단계를 완료합니다.

gcloud

파티션을 나눈 테이블의 프로젝트에서 애셋을 내보내려면 다음 명령어를 실행합니다. 이 명령어는 내보낸 스냅샷을 BIGQUERY_TABLE의 BigQuery 테이블에 매일 새부적으로 저장하며 일별 및 두 개의 추가 타임스탬프 열, readTimerequestTime, 둘 중 하나가 그 중 하나는 partition-key 매개변수에 따라 파티션 키가 됩니다.

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --partition-key 'PARTITION_KEY' \
     --output-bigquery-force \

각 항목의 의미는 다음과 같습니다.

  • CONTENT_TYPE은 애셋의 콘텐츠 유형입니다.
  • PROJECT_ID는 메타데이터를 내보낸 프로젝트의 ID입니다. 이 프로젝트는 내보내기를 실행 중인 프로젝트이거나 다른 프로젝트일 수 있습니다.
  • SNAPSHOT_TIME (선택사항)은 애셋의 스냅샷을 만들려는 시간입니다. 값은 현재 시간 또는 과거 시간이어야 합니다. 기본적으로 현재 시간으로 스냅샷을 찍습니다. 시간 형식에 대한 자세한 내용은 gcloud topic datetimes를 참조하세요.
  • BIGQUERY_TABLE은 메타데이터를 내보내는 테이블이며 projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME 형식입니다.
  • PARTITION_KEY는 BigQuery로 파티션을 나눈 테이블로 내보낼 때 파티션 키 열입니다.
  • --output-bigquery-force는 대상 테이블을 덮어씁니다.

API

파티션을 나눈 테이블의 프로젝트에서 애셋을 내보내려면 다음 명령어를 실행합니다. 이 명령어는 내보낸 스냅샷을 BIGQUERY_TABLE의 BigQuery 테이블에 매일 새부적으로 저장하며 일별 및 두 개의 추가 타임스탬프 열, readTimerequestTime, 둘 중 하나가 그 중 하나는 partition-key 매개변수에 따라 파티션 키가 됩니다. exportAssets 메서드 자세히 알아보기

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "partitionSpec": {"partitionKey": "PARTITION_KEY"} \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

대상 테이블이 이미 존재하는 경우 필요에 따라 열을 추가하여 기존 테이블의 스키마가 업데이트됩니다. 열이 유형이나 모드를 변경하면 (예: 선택적 열에서 반복적인 열로 변경) 이 스키마 업데이트가 실패합니다. 그런 다음 output-bigquery-force 플래그를 TRUE로 설정하면 해당 파티션이 스냅샷 결과로 덮어쓰기되지만 1개 이상의 다른 파티션에 있는 데이터는 그대로 유지됩니다. output-bigquery-force가 설정되지 않았거나 FALSE인 경우 해당 파티션에 데이터를 추가합니다.

스키마 업데이트 또는 데이터 추가가 실패하면 내보내기 작업이 실패합니다.

내보내기 상태 확인

내보내기 상태를 확인하려면 다음 명령어를 실행하세요.

gcloud

내보내기 상태를 확인하려면 다음 명령어를 실행합니다. 내보내기 명령어를 실행한 후 gcloud 도구에 표시됩니다.

gcloud asset operations describe OPERATION_ID

API

내보내기 상태를 보려면 내보내기 응답에 반환된 작업 ID를 사용하여 다음 명령어를 실행합니다.

  1. 내보내기에 대한 응답의 name 필드에서 OPERATION_ID를 찾을 수 있으며, 응답 형식은 다음과 같습니다.

    "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
    
  2. 내보내기 상태를 확인하려면 OPERATION_ID와 함께 다음 명령어를 실행합니다.

    gcurl https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
    

애셋 스냅샷 보기

애셋 스냅샷 메타데이터가 포함된 테이블을 보려면 다음 단계를 완료합니다.

Console

  1. Cloud Console에서 BigQuery 페이지로 이동합니다.
    BigQuery 페이지로 이동

  2. 데이터 세트의 테이블과 뷰를 표시하려면 탐색 패널을 엽니다. 리소스 섹션에서 프로젝트를 선택하여 펼친 다음 데이터 세트를 선택합니다.

  3. 목록에서 테이블을 선택합니다.

  4. 세부정보를 선택하고 행 개수 값을 확인합니다. gcloud 도구 또는 API를 사용하여 결과의 시작점을 제어하려면 이 값이 필요할 수 있습니다.

  5. 샘플 데이터 세트를 보려면 미리보기를 선택합니다.

API

테이블 데이터를 찾아보려면 tabledata.list를 호출하세요. tableId 매개변수에 테이블 이름을 지정합니다.

다음과 같은 선택적 매개변수를 구성하여 출력을 제어할 수 있습니다.

  • maxResults는 반환할 최대 결과 수입니다.
  • selectedFields는 반환할 열을 쉼표로 구분한 목록입니다. 지정하지 않으면 모든 열이 반환됩니다.
  • startIndex는 읽기를 시작할 행의 0부터 시작하는 색인입니다.

반환되는 값은 JSON 객체에 래핑되므로 tabledata.list 참조 문서의 설명에 따라 객체를 파싱해야 합니다.

내보내기에 애셋과 애셋의 리소스 이름이 나열됩니다.

애셋 스냅샷 쿼리

스냅샷을 BigQuery로 내보낸 후 애셋 메타데이터에서 쿼리를 실행할 수 있습니다. 몇 가지 일반적인 사용 사례에 대한 자세한 내용은 BigQuery 샘플 쿼리로 내보내기를 참조하세요.

기본적으로 BigQuery는 대화형 또는 주문형 쿼리 작업을 실행합니다. 따라서 쿼리가 최대한 빠르게 실행됩니다. 대화형 쿼리는 동시 비율 한도와 일일 한도에 반영됩니다.

쿼리 결과는 임시 또는 영구 테이블에 저장됩니다. 데이터를 기존 테이블에 추가하거나 덮어쓸지, 혹은 동일한 이름의 테이블이 존재하지 않을 경우 새 테이블을 만들지 선택할 수 있습니다.

임시 테이블에 출력을 작성하는 대화형 쿼리를 실행하려면 다음 단계를 완료합니다.

Console

  1. Cloud Console에서 BigQuery 페이지로 이동합니다.
    BigQuery 페이지로 이동

  2. 새 쿼리 작성을 선택합니다.

  3. 쿼리 편집기 텍스트 영역에 유효한 BigQuery SQL 쿼리를 입력합니다.

  4. (선택사항) 데이터 처리 위치를 변경하려면 다음 단계를 완료합니다.

    1. 더보기를 선택한 다음 쿼리 설정을 선택합니다.
    2. 처리 위치에서 자동 선택을 선택한 후 데이터의 위치를 선택합니다.
    3. 쿼리 설정을 업데이트하려면 저장을 선택합니다.
  5. 실행을 선택합니다.

API

  1. 새 작업을 시작하려면 jobs.insert 메서드를 호출합니다. 작업 리소스에서 다음 매개변수를 설정합니다.

    • configuration 필드에서 query 필드를 BigQuery 쿼리 작업을 설명하는 JobConfigurationQuery로 설정합니다.

    • jobReference 필드에서 location 필드를 작업에 적합하도록 설정합니다.

  2. 결과를 폴링하려면 getQueryResults을 호출합니다. jobCompletetrue가 될 때까지 폴링해야 합니다. errors 목록에서 오류 및 경고를 확인할 수 있습니다.