BigQuery로 내보내기

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

시작하기 전에

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

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

  2. gcloud CLI 또는 API를 사용하여 Cloud 애셋 인벤토리 API를 호출하는 데 필요한 권한을 구성하세요.

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

    gcloud

    gcloud CLI를 사용하여 Cloud Asset Inventory API를 호출하는 환경을 설정하려면 로컬 클라이언트에 Google Cloud CLI를 설치하세요.

    API

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

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

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

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

    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 데이터세트 만들기

제한사항

  • 커스텀 Cloud Key Management Service(Cloud KMS) 키로 암호화된 BigQuery 테이블은 지원되지 않습니다.

  • 파티션을 나눈 테이블로 내보내지 않으면 기존 테이블에 내보내기 출력을 추가할 수 없습니다. 대상 테이블은 비어 있거나 덮어써야 합니다. 덮어쓰려면 gcloud CLI에서 --output-bigquery-force 플래그를 사용하거나 API에서 force를 사용합니다.

  • 리소스 유형별 개별 테이블로 내보내는 경우 container.googleapis.com/Clustercontainer.googleapis.com/NodePool을 제외한 Google Kubernetes Engine(GKE) 리소스 유형은 지원되지 않습니다.

내보내기에 사용될 BigQuery 스키마 설정

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

  • 리소스 또는 지정되지 않음: 콘텐츠 유형을 RESOURCE으로 설정하거나 지정하지 않고 per-asset-type 플래그를 false로 설정하거나 사용하지 않는 경우 그림 1에 표시된 스키마가 있는 BigQuery 테이블을 만듭니다. Resource.data는 JSON 문자열로 표시되는 리소스 메타데이터입니다.

    콘텐츠 유형을 RESOURCE로 설정하지 않거나 콘텐츠 유형을 설정하지 않고 per-asset-type 플래그를 true로 설정하면 애셋 유형별로 개별 테이블을 만듭니다. 각 테이블의 스키마에는 애셋 유형의 Resource.data 필드에 있는 중첩 필드에 매핑된 레코드 유형 열이 포함됩니다(BigQuery에서 지원하는 중첩 수준 최대 15개까지). 유형별 BigQuery의 예시 테이블은 projects/export-assets-examples/datasets/structured_export를 참조하세요.

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

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

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

  • OSConfig 인스턴스 인벤토리: REST API에서 OS_INVENTORY로 콘텐츠 유형을 설정하거나 gcloud CLI에서 os-inventory를 설정할 때 그림 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 테이블을 구분하려면 --per-asset-type 플래그를 사용합니다. 각 테이블의 이름은 _(밑줄) 및 ASSET_TYPE_NAME와 연결된 BIGQUERY_TABLE입니다. 영숫자가 아닌 문자는 _로 대체됩니다.

GKE 리소스 유형은 이 내보내기 유형에 지원되지 않습니다(container.googleapis.com/Clustercontainer.googleapis.com/NodePool 제외).

애셋을 리소스 유형마다 별도의 BigQuery 테이블로 내보내려면 다음 명령어를 실행합니다.

gcloud

  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

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

exportAssets 메서드를 자세히 알아보세요.

테이블로 내보내지 못하면 전체 내보내기 작업이 실패하고 첫 번째 오류를 반환합니다. 이전의 성공적인 내보내기 결과는 유지됩니다.

JSON3BigQuery 유형 사이의 호환성 문제가 해결되도록 다음 유형이 JSON 문자열에 포함합니다.

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

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

프로젝트의 애셋을 파티션을 나눈 테이블로 내보내려면 --partition-key 플래그를 사용합니다. 내보낸 스냅샷은 일일 세부사항이 있는 BIGQUERY_TABLE, 추가 타임스태프 열 두 개(partition-key 매개변수 중 하나인 readTimerequestTime)에서 BigQuery 테이블에 저장됩니다.

프로젝트의 애셋을 파티션을 나눈 테이블로 내보내려면 다음 명령어를 실행합니다.

gcloud

  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

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

exportAssets 메서드를 자세히 알아보세요.

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

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

내보내기 상태 확인

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

gcloud

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

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 CLI 또는 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 목록에서 오류 및 경고를 확인할 수 있습니다.