將資產中繼資料匯出至 Cloud Storage

gcloud

gcloud asset export \
    --SCOPE \
    --billing-project=BILLING_PROJECT_ID \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --content-type=CONTENT_TYPE \
    --relationship-types=RELATIONSHIP_TYPE_1,RELATIONSHIP_TYPE_2,... \
    --snapshot-time="SNAPSHOT_TIME" \
    --OUTPUT_TYPE

提供以下這些值：

• SCOPE：請使用下列其中一個值：

  • project=PROJECT_ID，其中 PROJECT_ID 是要匯出資產中繼資料的專案 ID。

  • folder=FOLDER_ID，其中 FOLDER_ID 是要匯出資產中繼資料的資料夾 ID。

    如何找出 Google Cloud 資料夾的 ID

    Google Cloud 控制台

    如要找出 Google Cloud 資料夾的 ID，請完成下列步驟：

    1. 前往 Google Cloud 控制台。

       前往 Google Cloud 控制台

    2. 按一下選單列中的「切換器」清單方塊。
    3. 從清單方塊中選取機構。
    4. 搜尋資料夾名稱。資料夾 ID 會顯示在資料夾名稱旁邊。

    gcloud CLI

    您可以使用下列指令，擷取位於機構組織層級的 Google Cloud 資料夾 ID：

    gcloud resource-manager folders list \
        --organization=$(gcloud organizations describe ORGANIZATION_NAME \
          --format="value(name.segment(1))") \
        --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
        --format="value(ID)"

    其中 TOP_LEVEL_FOLDER_NAME 是資料夾名稱的部分或完整字串比對。移除 --format 標記，即可查看找到的資料夾詳細資訊。

    先前的指令不會傳回資料夾中子資料夾的 ID。如要執行這項操作，請使用頂層資料夾的 ID 執行下列指令：

    gcloud resource-manager folders list --folder=FOLDER_ID

  • organization=ORGANIZATION_ID，其中 ORGANIZATION_ID 是擁有您要匯出資產中繼資料的機構 ID。

    如何查看機構的 ID Google Cloud

    Google Cloud 控制台

    如要找出 Google Cloud 機構的 ID，請完成下列步驟：

    1. 前往 Google Cloud 控制台。

       前往 Google Cloud 控制台

    2. 按一下選單列中的「切換器」清單方塊。
    3. 從清單方塊中選取機構。
    4. 按一下「全部」分頁標籤。機構 ID 會顯示在機構名稱旁邊。

    gcloud CLI

    您可以使用下列指令擷取機構的 ID： Google Cloud

    gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

• BILLING_PROJECT_ID：選用。預設 Cloud Asset Inventory 服務代理程式所在的專案 ID，該服務代理程式有權管理您的 BigQuery 資料集和資料表。 進一步瞭解如何設定帳單專案。

• ASSET_TYPE_#：選用。以半形逗號分隔的 可搜尋素材資源類型清單。 支援與 RE2 相容的規則運算式。如果規則運算式與任何支援的資產類型都不相符，系統會傳回 INVALID_ARGUMENT 錯誤。如未指定 --asset-types，系統會傳回所有資產類型。
• CONTENT_TYPE：選用。要擷取的中繼資料 內容類型。如果未指定 --content-type，則只會傳回基本資訊，例如資產名稱、資產上次更新時間，以及資產所屬的專案、資料夾和機構。
• RELATIONSHIP_TYPE_#：選用。您必須有 Security Command Center Premium 或 Enterprise 級別的存取權，或是 Gemini Cloud Assist 存取權，以半形逗號分隔的資產關係類型清單，列出您要擷取的類型。您必須將 CONTENT_TYPE 設為 RELATIONSHIP， 這項功能才能正常運作。
• SNAPSHOT_TIME：選用。您要擷取資產快照的時間，請採用 gcloud 主題日期時間格式。這個值不得超過 35 天前。如果未指定 --snapshot-time，系統會在目前時間拍攝快照。

• OUTPUT_TYPE：請使用下列其中一個值：

  • --output-path="gs://BUCKET_NAME/FILE_NAME"，將輸出內容寫入檔案，其中：

    • BUCKET_NAME 是要寫入的 Cloud Storage 值區名稱。
    • FILE_NAME 是要寫入 Cloud Storage bucket 的檔案。

  • --output-path-prefix="gs://BUCKET_NAME/FOLDER_NAME"，將輸出內容寫入資料夾，其中：

    • BUCKET_NAME 是要寫入資料的 Cloud Storage 值區名稱。
    • FOLDER_NAME 是要寫入 Cloud Storage 值區的資料夾。輸出內容會依資產類型分成子資料夾。子資料夾不得已存在於您指定的資料夾中。

如要瞭解所有選項，請參閱 gcloud CLI 參考資料。

範例

執行下列指令，將 my-project 專案中 2024 年 1 月 30 日的 resource 中繼資料匯出至 Cloud Storage bucket my-bucket 中的 my-file.txt 檔案。

gcloud asset export \
    --project=my-project \
    --billing-project=my-project \
    --content-type=resource \
    --snapshot-time="2024-01-30" \
    --output-path="gs://my-bucket/my-file.txt"

回覆範例

Export in progress for root asset [projects/my-project].
Use [gcloud asset operations describe projects/000000000000/operations/ExportAssets/RESOURCE/00000000000000000000000000000000] to check the status of the operation.

REST

HTTP 方法和網址：

POST https://cloudasset.googleapis.com/v1/SCOPE_PATH:exportAssets

標頭：

X-Goog-User-Project: BILLING_PROJECT_ID

JSON 要求內文：

{
  "assetTypes": [
    "ASSET_TYPE_1",
    "ASSET_TYPE_2",
    "..."
  ],
  "contentType": "CONTENT_TYPE",
  "relationshipTypes": [
    "RELATIONSHIP_TYPE_1",
    "RELATIONSHIP_TYPE_2",
    "..."
  ],
  "readTime": "SNAPSHOT_TIME",
  "outputConfig": {
    "gcsDestination": {
      OUTPUT_TYPE
    }
  }
}

提供以下這些值：

• SCOPE_PATH：請使用下列其中一個值：

  允許的值如下：

  • projects/PROJECT_ID，其中 PROJECT_ID 是要匯出資產中繼資料的專案 ID。

  • projects/PROJECT_NUMBER，其中 PROJECT_NUMBER 是專案編號，該專案含有您要匯出的資產中繼資料。

    如何找出 Google Cloud 專案編號

    Google Cloud 控制台

    如要找出專案編號，請完成下列步驟： Google Cloud

    1. 前往 Google Cloud 控制台的「Welcome」(歡迎) 頁面。

       前往「歡迎」

    2. 按一下選單列中的「切換器」清單方塊。

    3. 從清單方塊中選取機構，然後搜尋專案名稱。 專案名稱、專案編號和專案 ID 會顯示在「歡迎」標題附近。

       最多會顯示 4,000 個資源。如果找不到所需專案，請前往「管理資源」頁面，然後使用該專案的名稱篩選清單。

    gcloud CLI

    您可以使用下列指令擷取專案編號： Google Cloud

    gcloud projects describe PROJECT_ID --format="value(projectNumber)"

  • folders/FOLDER_ID，其中 FOLDER_ID 是要匯出資產中繼資料的資料夾 ID。

    如何找出 Google Cloud 資料夾的 ID

    Google Cloud 控制台

    如要找出 Google Cloud 資料夾的 ID，請完成下列步驟：

    1. 前往 Google Cloud 控制台。

       前往 Google Cloud 控制台

    2. 按一下選單列中的「切換器」清單方塊。
    3. 從清單方塊中選取機構。
    4. 搜尋資料夾名稱。資料夾 ID 會顯示在資料夾名稱旁邊。

    gcloud CLI

    您可以使用下列指令，擷取位於機構組織層級的 Google Cloud 資料夾 ID：

    gcloud resource-manager folders list \
        --organization=$(gcloud organizations describe ORGANIZATION_NAME \
          --format="value(name.segment(1))") \
        --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
        --format="value(ID)"

    其中 TOP_LEVEL_FOLDER_NAME 是資料夾名稱的部分或完整字串比對。移除 --format 標記，即可查看找到的資料夾詳細資訊。

    先前的指令不會傳回資料夾中子資料夾的 ID。如要執行這項操作，請使用頂層資料夾的 ID 執行下列指令：

    gcloud resource-manager folders list --folder=FOLDER_ID

  • organizations/ORGANIZATION_ID，其中 ORGANIZATION_ID 是擁有要匯出資產中繼資料的機構 ID。

    如何查看機構的 ID Google Cloud

    Google Cloud 控制台

    如要找出 Google Cloud 機構的 ID，請完成下列步驟：

    1. 前往 Google Cloud 控制台。

       前往 Google Cloud 控制台

    2. 按一下選單列中的「切換器」清單方塊。
    3. 從清單方塊中選取機構。
    4. 按一下「全部」分頁標籤。機構 ID 會顯示在機構名稱旁邊。

    gcloud CLI

    您可以使用下列指令擷取機構的 ID： Google Cloud

    gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

• BILLING_PROJECT_ID：預設 Cloud Asset Inventory 服務代理程式所在的專案 ID，該專案具有管理 BigQuery 資料集和資料表的權限。 進一步瞭解如何設定帳單專案。

• ASSET_TYPE_#：選用。可搜尋的素材資源類型陣列。 支援與 RE2 相容的規則運算式。如果規則運算式與任何支援的資產類型都不相符，系統會傳回 INVALID_ARGUMENT 錯誤。如未指定 assetTypes，系統會傳回所有資產類型。
• CONTENT_TYPE：選用。要擷取的中繼資料 內容類型。如果未指定 contentType，則只會傳回基本資訊，例如資產名稱、資產上次更新時間，以及資產所屬的專案、資料夾和機構。
• RELATIONSHIP_TYPE_#：選用。您必須有 Security Command Center Premium 或 Enterprise 級別的存取權，或是 Gemini Cloud Assist 存取權，以半形逗號分隔的資產關係類型清單，列出您要擷取的類型。您必須將 CONTENT_TYPE 設為 RELATIONSHIP， 這項功能才能正常運作。
• SNAPSHOT_TIME：選用。要擷取資產快照的時間，採用 RFC 3339 格式。這個值不得超過 35 天前。如果未指定 readTime，系統會在目前時間拍攝快照。

• OUTPUT_TYPE：請使用下列其中一個值：

  • "uri": "gs://BUCKET_NAME/FILE_NAME"，將輸出內容寫入檔案，其中：

    • BUCKET_NAME 是要寫入的 Cloud Storage 值區名稱。
    • FILE_NAME 是要寫入 Cloud Storage bucket 的檔案。

  • "uriPrefix": "gs://BUCKET_NAME/FOLDER_NAME"，將輸出內容寫入資料夾，其中：

    • BUCKET_NAME 是要寫入的 Cloud Storage 值區名稱。
    • FOLDER_NAME 是要寫入 Cloud Storage 值區的資料夾。輸出內容會依資產類型分成子資料夾。子資料夾不得已存在於您指定的資料夾中。

如要瞭解所有選項，請參閱 REST 參考資料。

指令範例

執行下列任一指令，將 2024 年 1 月 30 日的 resource 中繼資料匯出至 my-project 專案，並儲存到 Cloud Storage bucket my-bucket 中的 my-file.txt 檔案。

curl -X POST \
     -H "X-Goog-User-Project: BILLING_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
            "contentType": "RESOURCE",
            "readTime": "2024-01-30T00:00:00Z",
            "outputConfig": {
              "gcsDestination": {
                "uri": "gs://my-bucket/my-file"
              }
            }
          }' \
     https://cloudasset.googleapis.com/v1/projects/my-project:exportAssets

$cred = gcloud auth print-access-token

$headers = @{ 
  "X-Goog-User-Project" = "BILLING_PROJECT_ID";
  "Authorization" = "Bearer $cred"
}


$body = @"
{
  "contentType": "RESOURCE",
  "readTime": "2024-01-30T00:00:00Z",
  "outputConfig": {
    "gcsDestination": {
      "uri": "gs://my-bucket/my-file"
    }
  }
}
"@

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -Body $body `
  -Uri "https://cloudasset.googleapis.com/v1/projects/my-project:exportAssets" | Select-Object -Expand Content

回覆範例

{
  "name": "projects/000000000000/operations/ExportAssets/RESOURCE/00000000000000000000000000000000",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.asset.v1.ExportAssetsRequest",
    "parent": "projects/000000000000",
    "readTime": "2024-01-30T00:00:00Z",
    "contentType": "RESOURCE",
    "outputConfig": {
      "gcsDestination": {
        "uri": "gs://my-bucket/export.txt"
      }
    }
  }
}

C#

using Google.Api.Gax.ResourceNames;
using Google.Cloud.Asset.V1;

public class ExportAssetsSample
{
    public ExportAssetsResponse ExportAssets(string bucketName, string projectId)
    {
        string assetDumpFile = $"gs://{bucketName}/my-assets.txt";
        // Create the client
        AssetServiceClient client = AssetServiceClient.Create();
        // Build the request
        ExportAssetsRequest request = new ExportAssetsRequest
        {
            ParentAsResourceName = ProjectName.FromProject(projectId),
            OutputConfig = new OutputConfig
            {
                GcsDestination = new GcsDestination { Uri = assetDumpFile }
            }
        };
        // Start the long-running export operation
        var operation = client.ExportAssets(request);
        // Wait for it to complete (or fail)
        operation = operation.PollUntilCompleted();
        // Return the result
        return operation.Result;
    }
}

Go

// Sample asset-quickstart exports assets to given path.
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	asset "cloud.google.com/go/asset/apiv1"
	"cloud.google.com/go/asset/apiv1/assetpb"
)

func main() {
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	client, err := asset.NewClient(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	bucketName := fmt.Sprintf("%s-for-assets", projectID)
	assetDumpFile := fmt.Sprintf("gs://%s/my-assets.txt", bucketName)
	req := &assetpb.ExportAssetsRequest{
		Parent: fmt.Sprintf("projects/%s", projectID),
		OutputConfig: &assetpb.OutputConfig{
			Destination: &assetpb.OutputConfig_GcsDestination{
				GcsDestination: &assetpb.GcsDestination{
					ObjectUri: &assetpb.GcsDestination_Uri{
						Uri: string(assetDumpFile),
					},
				},
			},
		},
	}
	operation, err := client.ExportAssets(ctx, req)
	if err != nil {
		log.Fatal(err)
	}
	response, err := operation.Wait(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Print(response)
}

Java

// Imports the Google Cloud client library

import com.google.cloud.ServiceOptions;
import com.google.cloud.asset.v1.AssetServiceClient;
import com.google.cloud.asset.v1.ContentType;
import com.google.cloud.asset.v1.ExportAssetsRequest;
import com.google.cloud.asset.v1.ExportAssetsRequest.Builder;
import com.google.cloud.asset.v1.ExportAssetsResponse;
import com.google.cloud.asset.v1.GcsDestination;
import com.google.cloud.asset.v1.OutputConfig;
import com.google.cloud.asset.v1.ProjectName;
import java.io.IOException;
import java.util.Arrays;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ExportAssetsExample {

  // Use the default project Id.
  private static final String projectId = ServiceOptions.getDefaultProjectId();

  /**
   * Export assets for a project.
   *
   * @param exportPath where the results will be exported to
   * @param contentType determines the schema for the table
   * @param assetTypes a list of asset types to export. if empty, export all.
   */
  public static void exportAssets(String exportPath, ContentType contentType, String[] assetTypes)
      throws IOException,
          IllegalArgumentException,
          InterruptedException,
          ExecutionException,
          TimeoutException {
    try (AssetServiceClient client = AssetServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      OutputConfig outputConfig =
          OutputConfig.newBuilder()
              .setGcsDestination(GcsDestination.newBuilder().setUri(exportPath).build())
              .build();
      Builder exportAssetsRequestBuilder =
          ExportAssetsRequest.newBuilder()
              .setParent(parent.toString())
              .setContentType(contentType)
              .setOutputConfig(outputConfig);
      if (assetTypes.length > 0) {
        exportAssetsRequestBuilder.addAllAssetTypes(Arrays.asList(assetTypes));
      }
      ExportAssetsRequest request = exportAssetsRequestBuilder.build();
      ExportAssetsResponse response = client.exportAssetsAsync(request).get(5, TimeUnit.MINUTES);
      System.out.println(response);
    }
  }
}

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const dumpFilePath = 'gs://my-bucket/my-assets.txt';
// const contentType = 'RESOURCE';

const {AssetServiceClient} = require('@google-cloud/asset');
const client = new AssetServiceClient();

async function exportAssets() {
  const projectId = await client.getProjectId();
  const projectResource = `projects/${projectId}`;

  // TODO(developer): choose the dump file path
  // const dumpFilePath = 'Dump file path, e.g.: gs://<my_bucket>/<my_asset_file>'
  const request = {
    parent: projectResource,
    contentType: contentType,
    outputConfig: {
      gcsDestination: {
        uri: dumpFilePath,
      },
    },
  };

  // Handle the operation using the promise pattern.
  const [operation] = await client.exportAssets(request);

  // Operation#promise starts polling for the completion of the operation.
  const [result] = await operation.promise();

  // Do things with with the response.
  console.log(result);
}
exportAssets().catch(err => {
  throw err;
});

PHP

use Google\Cloud\Asset\V1\Client\AssetServiceClient;
use Google\Cloud\Asset\V1\ExportAssetsRequest;
use Google\Cloud\Asset\V1\GcsDestination;
use Google\Cloud\Asset\V1\OutputConfig;

/**
 * Export assets for given project to specified dump file path.
 *
 * @param string $projectId the project Id for export assets.
 * @param string $dumpFilePath the file path where the assets will be dumped to.
 *        e.g.: gs://[bucket-name]/[asset-file-name].
 */
function export_assets(string $projectId, string $dumpFilePath)
{
    $client = new AssetServiceClient();

    $gcsDestination = new GcsDestination(['uri' => $dumpFilePath]);
    $outputConfig = new OutputConfig(['gcs_destination' => $gcsDestination]);
    $request = (new ExportAssetsRequest())
        ->setParent("projects/$projectId")
        ->setOutputConfig($outputConfig);

    $resp = $client->exportAssets($request);

    $resp->pollUntilComplete();

    if ($resp->operationSucceeded()) {
        print('The result is dumped to $dumpFilePath successfully.' . PHP_EOL);
    } else {
        $error = $resp->getError();
        printf('There was an error: "%s".' . PHP_EOL, $error?->getMessage());
        // handleError($error)
    }
}

Python

from google.cloud import asset_v1

# TODO project_id = 'Your Google Cloud Project ID'
# TODO dump_file_path = 'Your asset dump file path'

client = asset_v1.AssetServiceClient()
parent = f"projects/{project_id}"
output_config = asset_v1.OutputConfig()
output_config.gcs_destination.uri = dump_file_path
request_options = {"parent": parent, "output_config": output_config}

if content_type is not None:
    request_options["content_type"] = content_type

response = client.export_assets(request=request_options)
print(response.result())

Ruby

require "google/cloud/asset"

asset_service = Google::Cloud::Asset.asset_service
# project_id = 'YOUR_PROJECT_ID'
formatted_parent = asset_service.project_path project: project_id
# Assets dump file path, e.g.: gs://[YOUR_BUCKET]/[YOUR_ASSETS_FILE]
# dump_file_path = 'YOUR_ASSET_DUMP_FILE_PATH'
output_config = {
  gcs_destination: {
    uri: dump_file_path
  }
}

operation = asset_service.export_assets(
  parent: formatted_parent, output_config: output_config
) do |op|
  # Handle the error.
  raise op.results.message if op.error?
end

operation.wait_until_done!
response = operation.response
puts "Exported assets to: #{response.output_config.gcs_destination.uri}"
# Do things with the result

gcloud

如要查看匯出狀態，請完成下列步驟：

1. 從匯出要求的回應中取得 OPERATION_PATH，其中包含作業 ID。回應匯出要求時會顯示 OPERATION_PATH，格式如下：

   projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
   

2. 如要檢查匯出作業的狀態，請執行下列指令並加上 OPERATION_PATH：

   gcloud asset operations describe OPERATION_PATH
   

REST

如要查看匯出狀態，請完成下列步驟：

1. 從匯出要求的回應中取得 OPERATION_PATH，其中包含作業 ID。在匯出作業的回應中，OPERATION_PATH 會顯示為 name 欄位的值，格式如下：

   projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
   

2. 如要查看匯出狀態，請提出下列要求。

   REST

   HTTP 方法和網址：

   GET https://cloudasset.googleapis.com/v1/OPERATION_PATH
   

   指令範例

   curl (Linux、macOS 或 Cloud Shell)

   curl -X GET \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        https://cloudasset.googleapis.com/v1/OPERATION_PATH

   PowerShell (Windows)

   $cred = gcloud auth print-access-token
   
   $headers = @{ 
     "Authorization" = "Bearer $cred"
   }
   
   
   Invoke-WebRequest `
     -Method GET `
     -Headers $headers `
     -Uri "https://cloudasset.googleapis.com/v1/OPERATION_PATH" | Select-Object -Expand Content

   回覆範例

   {
     "name": "projects/000000000000/operations/ExportAssets/RESOURCE/00000000000000000000000000000000",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.asset.v1.ExportAssetsRequest",
       "parent": "projects/000000000000",
       "readTime": "2024-01-30T00:00:00Z",
       "contentType": "RESOURCE",
       "outputConfig": {
         "gcsDestination": {
           "uri": "gs://my-bucket/export.txt"
         }
       }
     }
   }