BigQuery へのエクスポート

このトピックでは、組織、フォルダ、またはプロジェクトのアセットメタデータを BigQuery テーブルにエクスポートし、インベントリに対してデータ分析を行う方法を説明します。BigQuery は、カスタムスクリプトを使用しなくてもデータを分析し、有用な分析情報を提供できる SQL のような操作性を備えています。

始める前に

始める前に、次の手順を行います。

API コマンドを実行するプロジェクトで Cloud Asset Inventory API を有効にします。
Cloud Asset Inventory API を有効にする
gcloud CLI または API を使用して Cloud Asset Inventory API を呼び出すために必要な権限を構成します。
環境を設定するには、次の手順を実行します。
gcloud
gcloud CLI を使用して Cloud Asset Inventory API を呼び出すように環境を設定するには、ローカルクライアントに Google Cloud CLI をインストールします。
API
Unix の curl コマンドで Cloud Asset Inventory API を呼び出すように環境を設定するには、次の手順を行います。
1. ローカルマシンに oauth2l をインストールし、Google OAuth システムを操作できるようにします。
2. Unix curl コマンドにアクセスできるかを確認します。
3. プロジェクト、フォルダ、組織で、次のいずれかのロールがアカウントに付与されていることを確認します。
  - Cloud Asset 閲覧者のロール（roles/cloudasset.viewer）
  - オーナーの基本ロール（roles/owner）
gcloud CLI は、請求先プロジェクトをコンシューマプロジェクトとして使用します。権限拒否のメッセージが表示された場合は、請求先プロジェクトがコアプロジェクトと異なるかどうかを確認できます。
```
gcloud config list
```
請求先プロジェクトをコンシューマプロジェクトに設定するには:
```
gcloud config set billing/quota_project CONSUMER_PROJECT_NUMBER
```
Cloud Asset Inventory API が有効になっていないプロジェクト内の BigQuery データセットにエクスポートする場合は、宛先プロジェクトの service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com サービスアカウントに次のロールを付与する必要もあります。
- BigQuery データ編集者のロール（roles/bigquery.dataEditor）
- BigQuery ユーザーのロール（roles/bigquery.user）
サービスアカウントは、API を 1 回呼び出すことで作成されます。または、次のコマンドを使用してサービスアカウントを作成し、サービスエージェントのロールを手動で付与することもできます。
```
  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
```
BigQuery データセットを作成します。

制限事項

カスタム Cloud Key Management Service（Cloud KMS）鍵で暗号化された BigQuery テーブルはサポートされていません。
パーティション分割テーブルにエクスポートする場合を除き、既存のテーブルへのエクスポート出力の追加はサポートされていません。宛先テーブルは空にするか、上書きする必要があります。上書きするには、gcloud CLI で --output-bigquery-force フラグを使用するか、API で force を使用します。
Google Kubernetes Engine（GKE）リソースタイプは、container.googleapis.com/Cluster と container.googleapis.com/NodePool を除き、リソースタイプごとに別々のテーブルにエクスポートする場合はサポートされません。

エクスポート用の BigQuery スキーマの設定

すべての BigQuery テーブルは、列名、データ型、その他の情報を記述するスキーマによって定義されます。エクスポート中にコンテンツタイプを設定すると、テーブルのスキーマが決まります。

リソースまたは未指定: コンテンツタイプを RESOURCE に設定する、または指定せず、そして per-asset-type フラグを false に設定する、または使用しない場合、図 1 に示すスキーマを含む BigQuery テーブルを作成します。Resource.data は、JSON 文字列として表現されるリソースメタデータです。

図 1:リソーススキーマ

コンテンツタイプを RESOURCE に設定する、または設定せず、そして per-asset-type フラグを true に設定する場合、アセットタイプ別の個別のテーブルを作成します。各テーブルのスキーマには、そのアセットタイプの Resource.data フィールドのネストされたフィールド（BigQuery でサポートされる最大 15 のネストレベルまで）にマッピングされた RECORD 型の列が含まれます。種類別の BigQuery のサンプルテーブルについては、projects/export-assets-examples/datasets/structured_export をご覧ください。
IAM ポリシー: コンテンツタイプをREST API で IAM_POLICY または gcloud CLI で iam-policy に設定した場合、図 2 に示すスキーマを含む BigQuery テーブルを作成します。iam_policy RECORD は完全に展開されています。

図 2.IAM スキーマ
組織のポリシー: コンテンツタイプをREST API で ORG_POLICY または gcloud CLI で org-policy に設定した場合、図 3 に示すスキーマを含む BigQuery テーブルを作成します。

図 3.組織のポリシーのスキーマ
VPCSC ポリシー: コンテンツタイプをREST API で ACCESS_POLICY または gcloud CLI で access-policy に設定した場合、図 4 に示すスキーマを含む BigQuery テーブルを作成します。

図 4.VPCSC ポリシーのスキーマ
OSConfig インスタンスインベントリ: コンテンツタイプを REST API で OS_INVENTORY または gcloud CLI で os-inventory に設定した場合、図 5 に示すスキーマを含む BigQuery テーブルを作成します。

図 5. OS インベントリのスキーマ

アセットスナップショットのエクスポート

任意のタイムスタンプにおけるアセットスナップショットをエクスポートするには、次の手順を行います。

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 の代わりに次のいずれかのフラグを使用します。

--organization=ORGANIZATION_ID
--folder=FOLDER_ID

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/Cluster と container.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 メソッドをご覧ください。

いずれかのテーブルへのエクスポートが失敗すると、エクスポート操作全体が失敗し、最初のエラーが返されます。前回成功したエクスポートの結果は保持されます。

次のタイプは、JSON3 と BigQuery の型との互換性の問題を解決するために、JSON 文字列でパックしています。

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

パーティション分割テーブルへのエクスポート

プロジェクト内のアセットをパーティション分割テーブルにエクスポートするには、--partition-key フラグを使用します。エクスポートされたスナップショットは、BigQuery テーブル BIGQUERY_TABLE に 1 日単位で 2 つのタイムスタンプ列（readTime と requestTime）に格納されます。これらの列のうち 1 つは partition-key パラメータです。

プロジェクト内のアセットをパーティション分割テーブルにエクスポートするには、次のコマンドを実行します。

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 に設定すると、対応するパーティションはスナップショットの結果によって上書きされますが、1 つ以上の別のパーティション内のデータはそのまま残ります。output-bigquery-force が未設定または FALSE の場合、対応するパーティションにデータが追加されます。

スキーマの更新またはデータの追加が失敗すると、エクスポート操作は失敗します。

エクスポートのステータスの確認

エクスポートのステータスを確認するには、次のコマンドを実行します。

gcloud

エクスポートのステータスを確認するには、次のコマンドを実行します。これは、エクスポートコマンドを実行すると、gcloud CLI に表示されます。

gcloud asset operations describe OPERATION_ID

API

エクスポートのステータスを表示するには、エクスポートに対するレスポンスで返されたオペレーション ID を使用して次のコマンドを実行します。

OPERATION_ID は、エクスポートに対するレスポンスの name フィールドにあります。形式は次のとおりです。
```
"name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
```
エクスポートのステータスを確認するには、OPERATION_ID を指定して次のコマンドを実行します。
```
gcurl https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
```

アセットスナップショットの表示

アセットスナップショットのメタデータを含むテーブルを表示するには、次の手順を行います。

コンソール

Cloud Console の BigQuery ページに移動します。
BigQuery ページに移動
データセット内のテーブルとビューを表示するには、ナビゲーションパネルを開きます。[リソース] セクションでプロジェクトを展開し、データセットを選択します。
リストからテーブルを選択します。
[詳細] を選択し、[行数] の値を書き留めます。gcloud CLI または API を使用して結果の開始点を制御するために、この値が必要になることがあります。
データのサンプルセットを表示するには、[プレビュー] を選択します。

API

テーブルのデータを閲覧するには、tabledata.list を呼び出します。tableId パラメータで、テーブルの名前を指定します。

次の省略可能パラメータを構成すると、出力を制御できます。

maxResults は返される結果の最大数です。
selectedFields は返される列のカンマ区切りのリストです。指定しなければ、すべての列が返されます。
startIndex は、読み取りを開始する行を指し示す、ゼロから始まるインデックスです。

値は 1 つの JSON オブジェクトにラップされて返されます。このオブジェクトは、tabledata.list リファレンスドキュメントに記載されている手順に従って解析する必要があります。

エクスポートは、アセットとそのリソース名の一覧を表示します。

アセットスナップショットの照会

スナップショットを BigQuery にエクスポートすると、アセットのメタデータに対してクエリを実行できます。一般的なユースケースの詳細については、BigQuery サンプルクエリへのエクスポートをご覧ください。

デフォルトでは、BigQuery によってインタラクティブな、すなわちオンデマンド型のクエリジョブが実行されます。すなわち、クエリは可能な限り速やかに実行されます。インタラクティブクエリは、同時実行のレート制限と毎日の制限に対してカウントされます。

クエリの結果は、一時テーブルまたは永続テーブルのいずれかに保存されます。既存のテーブルにデータを追加するか、既存のテーブルのデータを上書きするか、同じ名前のテーブルが存在しない場合は新しいテーブルを作成できます。

出力を一時テーブルに書き込むインタラクティブクエリを実行するには、次の手順を実行します。

コンソール

Cloud Console の BigQuery ページに移動します。
BigQuery ページに移動
[クエリを新規作成] を選択します。
[クエリエディタ] テキスト領域に、有効な BigQuery SQL クエリを入力します。
（省略可）データ処理ロケーションを変更するには、次の手順を実行します。
1. [展開]、[クエリの設定] の順に選択します。
2. [処理を行うロケーション] で [自動選択] を選択し、データのロケーションを選択します。
3. クエリの設定を更新するには、[保存] を選択します。
[実行] を選択します。

API

新しいジョブを開始するには、jobs.insert メソッドを呼び出します。ジョブリソースで、次のパラメータを設定します。
- configuration フィールドで、query フィールドを、BigQuery クエリジョブを記述する JobConfigurationQuery に設定します。
- jobReference フィールドで、ジョブに適した location フィールドを設定します。
結果を取得するには、getQueryResults を呼び出します。jobComplete が true と等しくなるまで取得を続けます。エラーと警告は、errors リストで確認できます。

BigQuery へのエクスポート

始める前に

gcloud

API

制限事項

エクスポート用の BigQuery スキーマの設定

アセット スナップショットのエクスポート

gcloud

API

リソースタイプごとの別々のテーブルのエクスポート

gcloud

API

パーティション分割テーブルへのエクスポート

gcloud

API

エクスポートのステータスの確認

gcloud

API

アセット スナップショットの表示

コンソール

API

アセット スナップショットの照会

コンソール

API

アセットスナップショットのエクスポート

アセットスナップショットの表示

アセットスナップショットの照会