使用 SQL 查詢資產

注意： 如要使用這項功能，必須具備Security Command Center 進階版或 Enterprise 方案的存取權，或是Gemini Cloud Assist。

新註冊 Security Command Center 進階或 Enterprise 級別的客戶，最多可能需要 6 小時才能存取 API，最多可能需要 48 小時才能取得歷來資料。

您可以使用與 BigQuery SQL 相容的方言，查詢專案、資料夾或機構中的資產。

事前準備

1. 在您執行 Cloud Asset Inventory 指令的專案中，啟用 Cloud Asset Inventory API。

   啟用 Cloud Asset Inventory API

2. 請確認您的帳戶具有呼叫 Cloud Asset Inventory API 的正確角色。 如要瞭解各通話類型的個別權限，請參閱「權限」。

限制

• 資產類型名稱已將 . 和 / 替換為 _。舉例來說，compute.googleapis.com/Instance 會變為 compute_googleapis_com_Instance。

• 要求必須是 SELECT 查詢。

• 不支援舊版 BigQuery SQL。

• 系統不支援大於 10 GB 的查詢結果。

• 如果查詢結果超過 10 MB 或 1,000 個資料列，一律會分成數頁顯示。

• 查詢處理時間不得超過 6 小時。

• 查詢結果只能匯出至US 多區域的 BigQuery 資料集。

可查詢的資料表

您可以查詢下列資料表：

• 如果是 RESOURCE 內容類型，資料集中的資料表名稱會對應至資產類型名稱 (假設資產類型存在)。舉例來說，compute_googleapis_com_Instance 資料表包含 Compute Engine 執行個體中繼資料。

• 對於非 RESOURCE 內容類型，資料集中的資料表名稱會對應至 RPC/REST 內容類型名稱。例如：ACCESS_POLICY。

• 如要查詢資源類型中的資源標準中繼資料，請使用資料表名稱 STANDARD_METADATA。這包括 resource.DATA 以外的所有欄位，因為 resource.DATA 適用於各個資源類型。

查詢資產中繼資料

控制台

如要查詢專案、資料夾或機構的資產中繼資料，請完成下列步驟：

1. 在 Google Cloud 控制台，前往「Asset Inventory」(資產清單) 頁面的「Asset query」(資產查詢) 分頁標籤。

   前往資產查詢

   如果沒有看到「資產查詢」分頁，您需要存取 Security Command Center Premium 或 Enterprise 級別，或 Gemini Cloud Assist。

2. 切換至要查詢的專案、資料夾或機構。
3. 按一下「資產查詢」分頁標籤。

4. 如要查詢資產中繼資料，請使用範例查詢或自行建構查詢：

   • 如要使用範例，請點選「查詢程式庫」分頁中的項目，預覽查詢。按一下「套用」，將該範例複製到「編輯查詢」方塊，然後編輯查詢或按一下「執行」來執行查詢。
   • 如要自行建立查詢，請直接在「編輯查詢」方塊中輸入查詢文字，然後按一下「執行」來執行查詢。如要協助撰寫自己的查詢，可以點選「選取資料表」窗格中的資料表，預覽其結構定義和內容。如要瞭解如何建構查詢，請參閱 查詢語法。

   與查詢相符的資產中繼資料會顯示在「Query result」(查詢結果) 分頁中。

5. 選用：如要以 CSV 格式下載查詢結果集，請按一下「匯出」。

   CSV 檔案大小上限為 2 MB。如果檔案大小超過上限，導致下載要求失敗，系統會顯示訊息，說明如何匯出完整結果。

gcloud

gcloud asset query \
    --SCOPE \
    --statement="SQL_SELECT_QUERY" \
    --timeout="TIMEOUTs"

提供以下這些值：

• 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))"

• SQL_SELECT_QUERY：SQL SELECT 查詢。
• TIMEOUT：選用。用戶端等待查詢完成的時間上限 (以秒為單位)，超過後就會繼續執行。使用逾時設定以非同步方式執行查詢，並使用工作參照稍後擷取結果。

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

範例

執行下列指令，取得 my-project 專案中前兩個 Compute Engine 執行個體的名稱和資產類型。

gcloud asset query \
    --project=my-project \
    --statement="
      SELECT
        name, assetType
      FROM
        compute_googleapis_com_Instance
      LIMIT 2"

完成工作回覆

以下範例顯示先前查詢的回應。回應會包含工作參照，並告知工作是否已完成 (done: true)。如果工作已完成，queryResult 物件會填入適當資料，結果則會列在後方。

done: true
jobReference: 0000000000000000000000000000000000000000000000000000000000000000
queryResult:
  nextPageToken: ''
  totalRows: '2'

name: //compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/instance-1
assetType: compute.googleapis.com/Instance

name: //compute.googleapis.com/projects/my-project/zones/us-central1-c/instances/instance-2
assetType: compute.googleapis.com/Instance

未完成的工作回覆

如果您在要求中設定逾時時間，系統會非同步執行查詢，並傳送回應，指出工作尚未完成 (done: false)。這類回應包含工作參照和未填入資料的 queryResult 物件：

done: false
jobReference: 0000000000000000000000000000000000000000000000000000000000000000
queryResult:
  nextPageToken: ''
  totalRows: '0'

工作完成且資料可用後，您可以使用 jobReference 值稍後擷取查詢結果。

REST

HTTP 方法和網址：

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

JSON 要求內文：

{
  "statement": "SQL_SELECT_QUERY",
  "timeout": "TIMEOUTs",
  "pageSize": "PAGE_SIZE",
  "pageToken": "PAGE_TOKEN"
}

提供以下這些值：

• 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))"

• SQL_SELECT_QUERY：SQL SELECT 查詢。
• TIMEOUT：選用。用戶端等待查詢完成的時間上限 (以秒為單位)，超過後就會繼續執行。使用逾時設定以非同步方式執行查詢，並使用工作參照稍後擷取結果。

• PAGE_SIZE：選用。每頁要傳回的結果數。上限為 500 個。如果值設為 0 或負值，系統將會選取適當的預設值。系統會傳回 nextPageToken，以擷取後續結果。

• PAGE_TOKEN：選用。如果要求的回應內容很長，系統會將其分開顯示在多個頁面。如未指定 pageToken，系統會傳回第一頁。 如要呼叫後續頁面，請使用先前回應的 nextPageToken 做為 pageToken 值。

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

指令範例

執行下列任一指令，取得 my-project 專案中前兩個 Compute Engine 執行個體的名稱和資產類型。

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell，系統會自動登入 gcloud CLI。您可以執行 gcloud auth list。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
            "statement": "
              SELECT
                name, assetType
              FROM
                compute_googleapis_com_Instance
              LIMIT 2"
          }' \
     https://cloudasset.googleapis.com/v1/projects/my-project:queryAssets

PowerShell (Windows)

注意：以下指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。如要查看有效帳戶，請執行 gcloud auth list。

$cred = gcloud auth print-access-token

$headers = @{ 
  "Authorization" = "Bearer $cred"
}


$body = @"
{
  "statement": "
    SELECT
      name, assetType
    FROM
      compute_googleapis_com_Instance
    LIMIT 2"
}
"@

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

完成工作回覆

以下範例顯示先前查詢的回應。回應會包含工作參照，並告知工作是否已完成 ("done": true)。如果工作已完成，queryResult 物件就會填入適當資料。

查詢結果會分成 rows (包含資產中繼資料的陣列) 和 schema (描述 rows 陣列中每個資產的結構定義物件)。這麼做是為了盡量減少大型回應中的欄位名稱和型別重複情形。

同樣地，f 和 v 會用於 rows 陣列，而不是 fields 和 value，盡可能縮減回應大小。

{
  "jobReference": "0000000000000000000000000000000000000000000000000000000000000000",
  "done": true,
  "queryResult": {
    "rows": [
      {
        "f": [
          {
            "v": "//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/instance-1"
          },
          {
            "v": "compute.googleapis.com/Instance"
          }
        ]
      },
      {
        "f": [
          {
            "v": "//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/instance-2"
          },
          {
            "v": "compute.googleapis.com/Instance"
          }
        ]
      }
    ],
    "schema": {
      "fields": [
        {
          "field": "name",
          "type": "STRING",
          "mode": "NULLABLE",
          "fields": []
        },
        {
          "field": "assetType",
          "type": "STRING",
          "mode": "NULLABLE",
          "fields": []
        }
      ]
    },
    "nextPageToken": "",
    "totalRows": "1"
  }
}

未完成的工作回覆

如果您在要求中設定逾時時間，系統會非同步執行查詢，並傳送指出工作尚未完成 ("done": false) 的回應。這類回應包含工作參照和未填入資料的 queryResult 物件：

{
  "jobReference": "0000000000000000000000000000000000000000000000000000000000000000",
  "done": false,
  "queryResult": {
    "rows": [],
    "schema": {
      "fields": []
    },
    "nextPageToken": "",
    "totalRows": "0"
  }
}

工作完成且資料可用後，您可以使用 jobReference 值擷取查詢結果。

稍後再擷取查詢結果

如要稍後再擷取需要一段時間才能完成的要求，請提出下列其中一項要求。

gcloud

gcloud asset query \
    --SCOPE \
    --job-reference="JOB_REFERENCE"

提供以下這些值：

• 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))"

• JOB_REFERENCE：先前回應中傳回的工作參照值。

範例

執行下列指令，取得先前在 my-project 專案中執行的查詢結果。

gcloud asset query \
    --project=my-project \
    --job-reference="0000000000000000000000000000000000000000000000000000000000000000"

REST

HTTP 方法和網址：

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

JSON 要求內文：

{
  "jobReference": "JOB_REFERENCE",
  "pageToken": "PAGE_TOKEN"
}

提供以下這些值：

• 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))"

• JOB_REFERENCE：先前回應中傳回的工作參照值。
• PAGE_TOKEN：選用。如果要求的回應內容很長，系統會將其分開顯示在多個頁面。如未指定 pageToken，系統會傳回第一頁。 如要呼叫後續頁面，請使用先前回應的 nextPageToken 做為 pageToken 值。

指令範例

執行下列其中一個指令，取得先前執行查詢的結果。

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell，系統會自動登入 gcloud CLI。您可以執行 gcloud auth list。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d '{
            "jobReference": "0000000000000000000000000000000000000000000000000000000000000000"
          }' \
     https://cloudasset.googleapis.com/v1/projects/my-project:queryAssets

PowerShell (Windows)

注意：以下指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。如要查看有效帳戶，請執行 gcloud auth list。

$cred = gcloud auth print-access-token

$headers = @{ 
  "Authorization" = "Bearer $cred"
}


$body = @"
{
  "jobReference": "0000000000000000000000000000000000000000000000000000000000000000"
}
"@

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

將查詢結果匯出至 BigQuery

查詢結果會以 Query Assets API 回應的形式傳回。如要將結果匯出至自己的 BigQuery 資料表，請在要求中指定 BigQuery 目的地。如果沒有，您必須先建立 BigQuery 資料集，才能提出這些要求。

gcloud

gcloud asset query \
    --SCOPE \
    --billing-project=BILLING_PROJECT_ID \
    --statement="SQL_SELECT_QUERY" \
    --bigquery-table=projects/BIGQUERY_PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME \
    --write-disposition="WRITE_METHOD"

提供以下這些值：

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

  • project=PROJECT_ID，其中 PROJECT_ID 是專案的 ID，該專案含有您要透過 SQL 查詢匯出的資產中繼資料。

  • folder=FOLDER_ID，其中 FOLDER_ID 是資料夾的 ID，該資料夾含有您要透過 SQL 查詢匯出的資產中繼資料。

    如何找出 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 是要透過 SQL 查詢匯出資產中繼資料的機構 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))"

• SQL_SELECT_QUERY：SQL SELECT 查詢。
• BIGQUERY_PROJECT_ID：要匯出至其中的 BigQuery 資料表所在專案 ID。
• DATASET_ID：BigQuery 資料集的 ID。
• TABLE_NAME：要將中繼資料匯出至其中的 BigQuery 資料表。如果不存在，系統會建立該目錄。

• WRITE_METHOD：指定 BigQuery 目的地資料表或資料分割區已存在時的行為。支援的值如下：

  • write-empty：預設值。如果現有資料表含有資料，工作結果會傳回重複錯誤。
  • write-append：將資料附加至資料表或最新分區。
  • write-truncate：覆寫整個資料表或所有分區資料。

範例

執行下列指令，取得 my-project 專案中前兩個 Compute Engine 執行個體的名稱和資產類型，並將結果匯出至 my-project 專案中的 my-table BigQuery 資料表，如果資料表已存在，則覆寫整個資料表。

gcloud asset query \
  --project=my-project \
  --statement="
    SELECT
      name, assetType
    FROM
      compute_googleapis_com_Instance
    LIMIT 2" \
  --bigquery-table=projects/my-project/datasets/my-dataset/tables/my-table \
  --write-disposition="write-truncate"

REST

HTTP 方法和網址：

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

標頭：

X-Goog-User-Project: BILLING_PROJECT_ID

JSON 要求內文：

{
  "statement": "SQL_SELECT_QUERY",
  "outputConfig": {
    "bigqueryDestination": {
      "dataset": "projects/BIGQUERY_PROJECT_ID/datasets/DATASET_ID",
      "table": "TABLE_NAME",
      "writeDisposition": "WRITE_METHOD"
    }
  },
  "pageSize": "PAGE_SIZE"
}

提供以下這些值：

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

  允許的值如下：

  • projects/PROJECT_ID，其中 PROJECT_ID 是專案的 ID，該專案含有您要透過 SQL 查詢匯出的資產中繼資料。

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

    如何找出 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，該資料夾含有您要透過 SQL 查詢匯出的資產中繼資料。

    如何找出 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 是要透過 SQL 查詢匯出資產中繼資料的機構 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 資料集和資料表的權限。 進一步瞭解如何設定帳單專案。

• SQL_SELECT_QUERY：SQL SELECT 查詢。
• BIGQUERY_PROJECT_ID：要匯出至其中的 BigQuery 資料表所在專案 ID。
• DATASET_ID：BigQuery 資料集的 ID。
• TABLE_NAME：要將中繼資料匯出至其中的 BigQuery 資料表。如果不存在，系統會建立該目錄。

• WRITE_METHOD：指定 BigQuery 目的地資料表或資料分割區已存在時的行為。支援的值如下：

  • WRITE_EMPTY：預設值。如果現有資料表含有資料，工作結果會傳回重複錯誤。
  • WRITE_APPEND：將資料附加至資料表或最新分區。
  • WRITE_TRUNCATE：覆寫整個資料表或所有分區資料。

• PAGE_SIZE：選用。每頁要傳回的結果數。上限為 500 個。如果值設為 0 或負值，系統將會選取適當的預設值。系統會傳回 nextPageToken，以擷取後續結果。

指令範例

執行下列任一指令，取得 my-project 專案中前兩個 Compute Engine 執行個體的名稱和資產類型，並將結果匯出至 my-project 專案的 my-table BigQuery 資料表。如果資料表已存在，系統會覆寫整個資料表。

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell，系統會自動登入 gcloud CLI。您可以執行 gcloud auth list。

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 '{
            "statement": "
              SELECT
                name, assetType
              FROM
                compute_googleapis_com_Instance
              LIMIT 2",
            "outputConfig": {
              "bigqueryDestination": {
                "dataset": "projects/my-project/datasets/my-dataset",
                "table": "my-table",
                "writeDisposition": "WRITE_TRUNCATE"
              }
            }
          }' \
     https://cloudasset.googleapis.com/v1/projects/my-project:queryAssets

PowerShell (Windows)

注意：以下指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。如要查看有效帳戶，請執行 gcloud auth list。

$cred = gcloud auth print-access-token

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


$body = @"
{
  "statement": "
    SELECT
      name, assetType
    FROM
      compute_googleapis_com_Instance
    LIMIT 2",
  "outputConfig": {
    "bigqueryDestination": {
      "dataset": "projects/my-project/datasets/my-dataset",
      "table": "my-table",
      "writeDisposition": "WRITE_TRUNCATE"
    }
  }
}
"@

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

其他 SQL 查詢範例

下列程式碼範例顯示可用於搜尋資產的特定 SQL 查詢，有助於您建構自己的查詢。

特定地區的 Compute Engine VM 執行個體

此外，請傳回 name 和建立時間。

SELECT
  name,
  resource.DATA.creationTimestamp
FROM
  compute_googleapis_com_Instance
WHERE
  resource.location LIKE '%asia%'

在 Kubernetes Pod 中執行的應用程式詳細資料

傳回應用程式 ingress-nginx 的命名空間、版本和時間戳記。進一步瞭解 BigQuery 中使用的 JSON 函式。

SELECT
  name AS pod_name,
  JSON_EXTRACT_SCALAR(resource.data.metadata, '$.namespace') AS namespace,
  resource.data.metadata.creationTimestamp AS creation_time,
  JSON_EXTRACT_SCALAR(resource.data.metadata.labels, "$['app.kubernetes.io/name']") AS app_label,
  resource.data.metadata.labels['app.kubernetes.io/version'] AS version
FROM
  k8s_io_Pod
WHERE
  JSON_EXTRACT_SCALAR(resource.data.metadata, '$.namespace') = "default"
  AND JSON_EXTRACT_SCALAR(resource.data.metadata.labels, "$['app.kubernetes.io/name']") = "ingress-nginx"

每個專案中的 BigQuery 資料集數量

  SELECT
    ancestor AS project,
    COUNT(*)
  FROM
    bigquery_googleapis_com_Dataset
  CROSS JOIN
    UNNEST (ancestors) AS ancestor
  WHERE
    ancestor LIKE '%project%'
  GROUP BY
    ancestor
  ORDER BY
    2 DESC

各個區域的 Compute Engine VM 執行個體數量

SELECT
  resource.location,
  COUNT(*)
FROM
  compute_googleapis_com_Instance
GROUP BY
  resource.location

區域中所有資源的名稱和 assetType

SELECT
  name,
  assetType
FROM
  STANDARD_METADATA
WHERE
  resource.location LIKE '%asia%'

公開可用的 Cloud Storage bucket

此外，請傳回其 name。

SELECT
  name
FROM
  IAM_POLICY
CROSS JOIN
  UNNEST(iamPolicy.bindings) AS binding
WHERE
  ('allUsers' IN UNNEST(binding.members)
  OR 'allAuthenticatedUsers' IN UNNEST(binding.members))
  AND assetType = 'storage.googleapis.com/Bucket'

未連接 VM 執行個體的子網路

SELECT
  subnetwork_table.name
FROM
  compute_googleapis_com_Subnetwork AS subnetwork_table
LEFT JOIN (
  SELECT
    interface.subnetwork AS subnetwork
  FROM
    compute_googleapis_com_Instance
  CROSS JOIN
    UNNEST(resource.DATA.networkInterfaces) AS interface) AS instance_table
ON
  SUBSTR(subnetwork_table.name, 25) = SUBSTR(instance_table.subnetwork,38)
WHERE
  instance_table.subnetwork IS NULL
  AND NOT subnetwork_table.name LIKE '%default%'