Nach BigQuery exportieren

In diesem Thema erfahren Sie, wie Sie die Assetmetadaten für Ihre Organisation, Ihren Ordner oder Ihr Projekt in eine BigQuery-Tabelle exportieren und dann Datenanalyse für Ihr Inventar durchführen. BigQuery bietet eine SQL-ähnliche Erfahrung, in der Nutzer Daten analysieren und wertvolle Informationen gewinnen können, ohne benutzerdefinierte Skripts zu verwenden.

Hinweis

Führen Sie zuerst die folgenden Schritte aus.

1. Aktivieren Sie die Cloud Asset Inventory API in dem Projekt, in dem Sie die API-Befehle ausführen werden.
   Cloud Asset Inventory API aktivieren

2. Konfigurieren Sie die Berechtigungen, die zum Aufrufen der Cloud Asset Inventory API entweder über die gcloud-Befehlszeile oder die API erforderlich sind.

3. Führen Sie die folgenden Schritte aus, um Ihre Umgebung einzurichten:

   gcloud

   Wenn Sie Ihre Umgebung für die Verwendung der gcloud-Befehlszeile einrichten möchten, um die Cloud Asset Inventory API aufzurufen, installieren Sie die Google Cloud-Befehlszeile auf Ihrem lokalen Client.

   API

   Führen Sie die folgenden Schritte aus, um Ihre Umgebung zum Aufrufen der Cloud Asset Inventory API mit dem Unix-Befehl curl einzurichten.

   1. Installieren Sie oauth2l auf Ihrem lokalen Gerät, um mit dem Google OAuth-System zu interagieren.
   2. Prüfen Sie, ob Sie Zugriff auf den Unix-Befehl curl haben.

   3. Sie müssen Ihrem Konto eine der folgenden Rollen für Ihr Projekt, Ihren Ordner oder Ihre Organisation zuweisen.

      • Rolle „Cloud-Asset-Betrachter“ (roles/cloudasset.viewer)
      • Einfache Inhaberrolle (roles/owner)

   Beachten Sie, dass die gcloud-Befehlszeile das Abrechnungsprojekt als Nutzerprojekt verwendet. Wenn Sie eine Meldung über eine verweigerte Berechtigung erhalten, können Sie prüfen, ob sich das Abrechnungsprojekt vom Kernprojekt unterscheidet:

   gcloud config list
   

   So legen Sie das Abrechnungsprojekt auf das Nutzerprojekt fest:

   gcloud config set billing/quota_project CONSUMER_PROJECT_NUMBER
   

4. Wenn Sie Daten in ein BigQuery-Dataset in einem Projekt exportieren, für das die Cloud Asset Inventory API nicht aktiviert ist, müssen Sie dem Dienstkonto service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com im Zielprojekt außerdem folgende Rollen gewähren:

   • Rolle „BigQuery-Datenbearbeiter“ (roles/bigquery.dataEditor)
   • Rolle "BigQuery-Nutzer" (roles/bigquery.user)

   Das Dienstkonto wird durch einmal Aufrufen der API erstellt. Alternativ können Sie die folgenden Befehle verwenden, um das Dienstkonto zu erstellen und die Rolle des Dienst-Agents manuell zuzuweisen:

     gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
     gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:[e-mail] --role=roles/cloudasset.serviceAgent
   

5. Erstellen Sie ein BigQuery-Dataset.

Beschränkungen

• BigQuery-Tabellen, die mit benutzerdefinierten Cloud Key Management Service-Schlüsseln (Cloud KMS) verschlüsselt sind, werden nicht unterstützt.

• Das Anfügen der Exportausgabe an eine vorhandene Tabelle wird nur unterstützt, wenn Sie in eine partitionierte Tabelle exportieren. Die Zieltabelle muss leer sein oder muss überschrieben werden. Wenn Sie es überschreiben möchten, verwenden Sie das Flag --output-bigquery-force mit der gcloud-Befehlszeile oder force mit der API.

• Google Kubernetes Engine-Ressourcentypen (GKE) mit Ausnahme von container.googleapis.com/Cluster und container.googleapis.com/NodePool werden beim Exportieren in separate Tabellen pro Ressourcentyp nicht unterstützt.

BigQuery-Schema für den Export festlegen

Jede BigQuery-Tabelle wird durch ein Schema definiert, das unter anderem Informationen zu Spaltennamen und Datentypen enthält. Durch das Festlegen des Inhaltstyps während des Exports wird das Schema für die Tabelle bestimmt.

• Ressource oder nicht angegeben: Wenn Sie den Inhaltstyp auf RESOURCE setzen oder nicht angeben und das Flag per-asset-type auf „false“ setzen oder nicht verwenden, erstellen Sie eine BigQuery-Tabelle mit dem Schema, das in Abbildung 1 gezeigt wird. Resource.data sind die Ressourcenmetadaten, die als JSON-String dargestellt werden.

  Abbildung 1. Ressourcenschema

  

  Wenn du den Inhaltstyp auf RESOURCE setzt oder nicht festlegst und das Flag per-asset-type auf true setzt, erstellst du separate Tabellen pro Asset-Typ. Das Schema jeder Tabelle enthält Spalten vom Typ RECORD, die den verschachtelten Feldern im Feld Resource.data dieses Asset-Typs zugeordnet sind (bis zu 15 verschachtelte Ebenen, die von BigQuery unterstützt werden). BigQuery-Beispieltabellen für bestimmte Typen finden Sie unter projects/export-assets-examples/dataset/structured_export.

• IAM-Richtlinie: Wenn Sie den Inhaltstyp in der REST API auf IAM_POLICY oder auf iam-policy in der gcloud-Befehlszeile festlegen, erstellen Sie eine BigQuery-Tabelle mit dem Schema, das in Abbildung 2 gezeigt wird. Die iam_policy RECORD ist vollständig erweitert.

  Abbildung 2. IAM-Schema

  

• Organisationsrichtlinie: Wenn Sie den Inhaltstyp in der REST API auf ORG_POLICY oder auf org-policy in der gcloud-Befehlszeile festlegen, erstellen Sie eine BigQuery-Tabelle mit dem Schema von Abbildung 3.

  Abbildung 3. Organisationsrichtlinienschema

  

• VPCSC-Richtlinie: Wenn Sie den Inhaltstyp in der REST API auf ACCESS_POLICY oder auf access-policy in der gcloud-Befehlszeile festlegen, erstellen Sie eine BigQuery-Tabelle mit dem Schema, das in Abbildung 4 gezeigt wird.

  Abbildung 4. VPCSC-Richtlinienschema

  

• OSConfig-Instanzinventar: Wenn Sie in der REST API oder auf os-inventory in der gcloud-Befehlszeile den Inhaltstyp auf OS_INVENTORY setzen, erstellen Sie eine BigQuery-Tabelle mit dem Schema von Abbildung 5.

  Abbildung 5. OS Inventory-Schema

  

Asset-Snapshot exportieren

Führen Sie die folgenden Schritte aus, um einen Asset-Snapshot zu einem bestimmten Zeitstempel zu exportieren.

gcloud

Führen Sie den folgenden Befehl aus, um Assets in ein Projekt zu exportieren. Mit diesem Befehl wird der exportierte Snapshot in einer BigQuery-Tabelle unter BIGQUERY_TABLE gespeichert.

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

Dabei gilt:

• CONTENT_TYPE ist der Inhaltstyp des Assets.
• PROJECT_ID ist die ID des Projekts, dessen Metadaten exportiert werden. Dieses Projekt kann das Projekt sein, in dem Sie den Export ausführen, oder ein anderes Projekt.
• SNAPSHOT_TIME (Optional) ist die Zeit, zu der Sie einen Snapshot Ihrer Assets erstellen möchten. Der Wert muss die aktuelle Zeit oder eine Zeit in der Vergangenheit sein. Standardmäßig wird ein Snapshot zum aktuellen Zeitpunkt erstellt. Weitere Informationen zu Zeitformaten finden Sie unter gcloud topic datetimes.
• BIGQUERY_TABLE ist der Name der Tabelle, in die Sie Ihre Metadaten im Format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME exportieren.
• --output-bigquery-force überschreibt die Zieltabelle, falls sie vorhanden ist.

Wenn Sie die Assets einer Organisation oder eines Ordners exportieren möchten, können Sie anstelle von --project eines der folgenden Flags verwenden.

• --organization=ORGANIZATION_ID
• --folder=FOLDER_ID

access-policy kann nur für eine --organization exportiert werden.

API

Führen Sie den folgenden Befehl aus, um die Assetmetadaten in Ihr Projekt zu exportieren. Mit diesem Befehl wird der exportierte Snapshot in einer BigQuery-Tabelle mit dem Namen TABLE_NAME gespeichert. Weitere Informationen zur Methode „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

Separate Tabellen für jeden Ressourcentyp exportieren

Verwenden Sie das Flag --per-asset-type, um Assets in einem Projekt in separate BigQuery-Tabellen zu exportieren. Jeder Name der Tabelle ist BIGQUERY_TABLE mit _ (Unterstrich) und ASSET_TYPE_NAME verkettet. Nicht alphanumerische Zeichen werden durch _ ersetzt.

Beachten Sie, dass GKE-Ressourcentypen mit Ausnahme von container.googleapis.com/Cluster und container.googleapis.com/NodePool für diesen Exporttyp nicht unterstützt werden.

Führen Sie den folgenden Befehl aus, um Assets für jeden Ressourcentyp in BigQuery zu exportieren.

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

Dabei gilt:

• CONTENT_TYPE ist der Inhaltstyp des Assets. Mit diesem Wert wird auch das Schema für den Export bestimmt.
• PROJECT_ID ist die ID des Projekts, dessen Metadaten exportiert werden. Dieses Projekt kann das Projekt sein, in dem Sie den Export ausführen, oder ein anderes Projekt.
• SNAPSHOT_TIME (Optional) ist die Zeit, zu der Sie einen Snapshot Ihrer Assets erstellen möchten. Der Wert muss die aktuelle Zeit oder eine Zeit in der Vergangenheit sein. Standardmäßig wird ein Snapshot zum aktuellen Zeitpunkt erstellt. Weitere Informationen zu gültigen Zeitformaten finden Sie unter gcloud topic datetimes.
• BIGQUERY_TABLE ist der Name der Tabelle, in die Sie Ihre Metadaten im Format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME exportieren.
• --output-bigquery-force überschreibt die Zieltabelle, falls sie vorhanden ist.
• --per-asset-type exportiert in mehrere BigQuery-Tabellen pro Ressourcentyp.

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

Weitere Informationen zur Export-Assets-Methode

Wenn der Export in eine Tabelle fehlschlägt, schlägt der gesamte Exportvorgang fehl und der erste Fehler wird zurückgegeben. Die Ergebnisse erfolgreicher Exporte bleiben erhalten.

Die folgenden Typen sind in einem JSON-String verpackt, um das Kompatibilitätsproblem zwischen JSON3- und BigQuery-Typen zu beheben.

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

In eine partitionierte Tabelle exportieren

Verwenden Sie das Flag --partition-key, um Assets in einem Projekt in partitionierte Tabellen zu exportieren. Der exportierte Snapshot wird in einer BigQuery-Tabelle unter BIGQUERY_TABLE mit täglicher Genauigkeit und zwei zusätzlichen Zeitstempelspalten gespeichert: readTime und requestTime. Eine davon ist der Parameter partition-key.

Führen Sie den folgenden Befehl aus, um Assets in einem Projekt in partitionierte Tabellen zu exportieren.

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 \

Dabei gilt:

• CONTENT_TYPE ist der Inhaltstyp des Assets. Mit diesem Wert wird auch das Schema für den Export bestimmt.
• PROJECT_ID ist die ID des Projekts, dessen Metadaten exportiert wurden. Dieses Projekt kann das Projekt sein, in dem Sie den Export ausführen, oder ein anderes Projekt.
• SNAPSHOT_TIME (Optional) ist die Zeit, zu der Sie einen Snapshot Ihrer Assets erstellen möchten. Der Wert muss die aktuelle Zeit oder eine Zeit in der Vergangenheit sein. Standardmäßig wird ein Snapshot zum aktuellen Zeitpunkt erstellt. Weitere Informationen zu Zeitformaten finden Sie unter gcloud topic datetimes.
• BIGQUERY_TABLE ist der Name der Tabelle, in die Sie Ihre Metadaten im Format projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME exportieren.
• PARTITION_KEY ist die Spalte für Partitionsschlüssel, die in nach BigQuery partitionierte Tabellen exportiert wird.
• --output-bigquery-force überschreibt die Zieltabelle, falls sie vorhanden ist.

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

Weitere Informationen zur Export-Assets-Methode

Wenn eine Zieltabelle bereits vorhanden ist, wird das vorhandene Schema der Tabelle nach Bedarf durch Hinzufügen zusätzlicher Spalten aktualisiert. Diese Schemaaktualisierung schlägt fehl, wenn Spalten ihren Typ oder Modus ändern, z. B. optional und wiederholt. Wenn das output-bigquery-force-Flag dann auf TRUE gesetzt ist, wird die entsprechende Partition von den Snapshot-Ergebnissen überschrieben. Die Daten in einer oder mehreren Partitionen bleiben jedoch unverändert. Wenn output-bigquery-force nicht festgelegt oder FALSE ist, werden die Daten an die entsprechende Partition angehängt.

Der Exportvorgang schlägt fehl, wenn die Schemaaktualisierung oder der Versuch, Daten anzuhängen, fehlschlägt.

Exportstatus prüfen

Führen Sie die folgenden Befehle aus, um den Status eines Exports zu prüfen:

Hinweis: Vorgänge sind einem OPERATION_ID-Wert zugeordnet, der eine UUID ist. Dieser Wert ist möglicherweise vertraulich, da der Befehl gcloud asset operations describe keine zusätzlichen Berechtigungen erfordert, um erfolgreich ausgeführt zu werden. Achten Sie darauf, nur den OPERATION_ID-Wert mit vertrauenswürdigen Nutzern zu teilen.

Hinweis: Der Server lehnt Anfragen ab, wenn eine vorherige Anfrage an dasselbe Ziel innerhalb von 15 Minuten gestartet wurde und noch ausgeführt wird. Nicht definierte Ergebnisse können auftreten, wenn die Exportzeit länger als 15 Minuten ist und eine fortlaufende Anfrage für dasselbe Ziel ausgeführt wird, bevor die erste Anfrage erfolgreich ist.

gcloud

Führen Sie den folgenden Befehl aus, um den Status des Exports zu prüfen. Sie wird in der gcloud-Befehlszeile angezeigt, nachdem der Exportbefehl ausgeführt wurde.

gcloud asset operations describe OPERATION_ID

API

Um den Status des Exports anzuzeigen, führen Sie den folgenden Befehl mit der Vorgangs-ID aus, die in der Antwort Ihres Exports zurückgegeben wurde.

1. Sie finden die OPERATION_ID im Feld name der Antwort auf den Export, der so formatiert ist:

   "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
   

2. Führen Sie zum Prüfen des Exportstatus den folgenden Befehl mit der OPERATION_ID aus:

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

Asset-Snapshot ansehen

Führen Sie die folgenden Schritte aus, um die Tabelle mit den Asset-Snapshot-Metadaten aufzurufen.

Console

1. Rufen Sie in der Cloud Console die BigQuery-Seite auf.
   Zur Seite "BigQuery"

2. Um die Tabellen und Ansichten im Dataset anzuzeigen, öffnen Sie den Navigationsbereich. Wählen Sie im Abschnitt Ressourcen Ihr Projekt aus, um es zu maximieren, und wählen Sie dann ein Dataset aus.

3. Wählen Sie in der Liste die gewünschte Tabelle aus.

4. Klicken Sie auf Details und notieren Sie den Wert in Zeilenanzahl. Mit diesem Wert können Sie den Startpunkt für Ihre Ergebnisse über die gcloud-Befehlszeile oder API festlegen.

5. Um einen Beispieldatensatz anzuzeigen, wählen Sie Vorschau aus.

API

Rufen Sie tabledata.list auf, um die Daten in Ihrer Tabelle zu durchsuchen. Geben Sie im Parameter tableId den Namen Ihrer Tabelle an.

Sie können die folgenden optionalen Parameter konfigurieren, um die Ausgabe zu steuern.

• maxResults ist die maximale Anzahl von zurückzugebenden Ergebnissen.
• selectedFields ist eine durch Kommas getrennte Liste von Spalten, die zurückgegeben werden sollen. Wenn nichts angegeben ist, werden alle Spalten zurückgegeben.
• startIndex ist der nullbasierte Index der Startzeile, die gelesen werden soll.

Hinweis: Wenn Sie einen startIndex nach der letzten Zeile anfordern, wird die Methode erfolgreich zurückgegeben, allerdings ohne das Attribut rows. Die Anzahl der Zeilen in einer Tabelle erhalten Sie durch Aufrufen der Methode tables.get und Auswerten des Attributs numRows.

Die Werte werden zusammengefasst in einem JSON-Objekt zurückgegeben. Dieses Objekt muss dann wie in der Referenzdokumentation zu tabledata.list beschrieben geparst werden.

Im Export sind die Assets und zugehörigen Ressourcennamen aufgelistet.

Asset-Snapshot abfragen

Nachdem Sie den Snapshot in BigQuery exportiert haben, können Sie Abfragen mit den Asset-Metadaten ausführen. Weitere Informationen zu mehreren typischen Anwendungsfällen finden Sie unter Nach BigQuery-Beispielabfragen exportieren.

Hinweis: Einige experimentelle Felder werden in BigQuery erst einmal leer angezeigt. Legen Sie erst dann eine Abhängigkeit von den betroffenen Spalten fest, wenn die Felder ausgefüllt sind. Informationen dazu, welche Felder öffentlich sind, finden Sie im Discovery-Dokument.

BigQuery führt standardmäßig interaktive (On-Demand) Abfragejobs aus. Dies bedeutet, dass die Abfrage so bald wie möglich ausgeführt wird. Interaktive Abfragen werden hinsichtlich der Grenze gleichzeitiger Abfragen und des Tageslimits mit angerechnet.

Die Abfrageergebnisse werden entweder in einer temporären oder permanenten Tabelle gespeichert. Sie können Daten an eine vorhandene Tabelle anfügen oder Daten in einer bestehenden Tabelle überschreiben oder eine neue Tabelle erstellen, wenn nicht bereits eine mit demselben Namen vorhanden ist.

Führen Sie die folgenden Schritte aus, um eine interaktive Abfrage auszuführen, die die Ausgabe in eine temporäre Tabelle schreibt.

Console

1. Rufen Sie in der Cloud Console die BigQuery-Seite auf.
   Zur Seite "BigQuery"

2. Wählen Sie Neue Abfrage erstellen aus.

3. Geben Sie im Textbereich des Abfrageeditors eine gültige BigQuery-SQL-Abfrage ein.

4. (Optional) Führen Sie die folgenden Schritte aus, um den Standort der Datenverarbeitung zu ändern.

   1. Wählen Sie Mehr und dann Abfrageeinstellungen aus.
   2. Wählen Sie unter Verarbeitungsstandort die Option Automatische Auswahl und dann den Standort Ihrer Daten aus.
   3. Klicken Sie auf Speichern, um die Abfrageeinstellungen zu aktualisieren.

5. Wählen Sie Ausführen aus.

API

1. Zum Starten eines neuen Jobs rufen Sie die Methode jobs.insert auf. Legen Sie in der Jobressource die folgenden Parameter fest.

   • Legen Sie im Feld configuration das Feld query auf eine JobConfigurationQuery fest, die den BigQuery-Abfragejob beschreibt.

   • Legen Sie im Feld jobReference das Feld location dem Job entsprechend fest.

2. Rufen Sie getQueryResults auf, um die Ergebnisse abzufragen. Führen Sie die Abfrage so lange aus, bis jobComplete gleich true ist. In der Liste errors können Sie nach Fehlern und Warnungen suchen.