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 erforderlich sind. Verwenden Sie dazu entweder das gcloud-Tool oder die API.

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

   gcloud

   Installieren Sie das Cloud SDK auf Ihrem lokalen Client, um Ihre Umgebung so einzurichten, dass die Cloud Asset Inventory API mit dem gcloud-Tool aufgerufen wird.

   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)

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 den folgenden Befehl verwenden:

     gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
   

5. Erstellen Sie ein BigQuery-Dataset.

Hinweis: Derzeit werden mit benutzerdefinierten Cloud KMS-Schlüsseln verschlüsselte BigQuery-Tabellen nicht unterstützt.

Asset-Snapshot exportieren

Hinweis: Das Anfügen einer Exportausgabe an eine vorhandene Tabelle wird nicht unterstützt. Die Zieltabelle muss leer sein oder muss überschrieben werden. Verwenden Sie zum Überschreiben das Flag --output-bigquery-force mit dem gcloud-Tool oder verwenden Sie force mit der API.

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

Wobei:

• 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

Inhaltstyp 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 spezifiziert: Wenn Sie den Inhaltstyp auf RESOURCE setzen oder den Inhaltstyp nicht festlegen, erstellen Sie eine BigQuery-Tabelle, die das in Abbildung 1 gezeigte Schema enthält. Resource.data sind die Ressourcenmetadaten als JSON-String dargestellt.

  Abbildung 1. Ressourcenschema

  

Hinweis: Das Ressourcenschema gilt nur, wenn Sie das Flag per-asset-type nicht verwenden oder auf false setzen. Im Abschnitt Separate Tabellen pro Asset-Typ erhalten Sie Informationen zum Schema, wenn Sie das Flag per-asset-type auf true setzen.

• IAM-Richtlinie: Wenn Sie den Inhaltstyp IAM_POLICY in der REST API oder iam-policy im gcloud-Tool festlegen, erstellen Sie eine BigQuery-Tabelle, die das Schema in Abbildung 2 hat. Der RECORD iam_policy wurde vollständig erweitert.

  Abbildung 2. IAM-Schema

  

• Organisationsrichtlinie: Wenn Sie den Inhaltstyp ORG_POLICY in der REST API oder org-policy im gcloud-Tool festlegen, erstellen Sie eine BigQuery-Tabelle, die das Schema in Abbildung 3 hat.

  Abbildung 3. Organisationsrichtlinienschema

  

• VPCSCPolicy: Wenn Sie den Inhaltstyp ACCESS_POLICY in der REST API oder access-policy im gcloud-Tool festlegen, erstellen Sie eine BigQuery-Tabelle, die das Schema in Abbildung 4 hat.

  Abbildung 4. VPCSC-Richtlinienschema

  

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

  Abbildung 5. OS Inventory-Schema

  

Separate Tabellen pro Ressourcentyp

Hinweis: Diese Funktion unterstützt derzeit keine Google Kubernetes Engine-Ressourcentypen außer „container.googleapis.com/Cluster“ und „"container.googleapis.com/NodePool“.

Führen Sie die folgenden Schritte aus, um einen Asset-Snapshot unter einem bestimmten Zeitstempel pro Ressourcentyp zu exportieren:

gcloud

Führen Sie den folgenden Befehl aus, um Assets in ein Projekt pro Ressourcentyp zu exportieren. Mit diesem Befehl wird der exportierte Snapshot in null Tabellen gespeichert, wenn die Snapshot-Ergebnisse leer sind oder in mehreren BigQuery-Tabellen. Jede Tabelle enthält die Ergebnisse eines Asset-Typs. Außerdem ist BIGQUERY_TABLE mit _ (Unterstrich) und dem Namen des Asset-Typs verkettet. Nicht alphanumerische Zeichen werden durch _ ersetzt.

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

Wobei:

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

Führen Sie den folgenden Befehl aus, um Assets in ein Projekt pro Ressourcentyp zu exportieren. Mit diesem Befehl wird der exportierte Snapshot in null Tabellen gespeichert, wenn die Snapshot-Ergebnisse leer sind oder mehrere BigQuery-Tabellen. Jede Tabelle enthält die Ergebnisse eines Asset-Typs. Außerdem ist BIGQUERY_TABLE mit _ (Unterstrich) und dem Namen des Asset-Typs verkettet. Nicht alphanumerische Zeichen werden durch _ ersetzt. Weitere Informationen finden Sie unter der Methode exportAssets.

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

Wenn der Export in eine Tabelle fehlschlägt, schlägt der gesamte Exportvorgang fehl und gibt den ersten Fehler zurück. Die Ergebnisse erfolgreicher Exporte bleiben jedoch erhalten.

Wenn Sie den Inhaltstyp während des Exports festlegen, wird das Schema für jede Tabelle festgelegt.

• Ressource: Wenn Sie den Inhaltstyp RESOURCE festlegen, enthält das Schema jeder Tabelle Spalten vom Typ RECORD, die den verschachtelten Feldern im Feld Resource.data dieses Asset-Typs zugeordnet sind (bis zu 15 Ebenen von BigQuery unterstützten verschachtelten Ebenen). Weitere Informationen finden Sie unter „BigQuery-Schemata“ mit Beispieltabellen in projects/export-assets-examples/datasets/structured_export.

• IAM-Richtlinie, Organisationsrichtlinie, VPCSC-Richtlinie oder nicht angegeben: Wenn Sie den Inhaltstyp auf IAM_POLICY, ORG_POLICY, ACCESS_POLICY oder den Inhaltstyp nicht festlegen, jede Tabelle hat das gleiche Schema, wie Sie den Typ pro Asset auf „False“ festgelegt haben. Weitere Informationen finden Sie in den Schemas im Abschnitt Inhaltstyp festlegen.

Die folgenden Typen werden in einen JSON-String verpackt, um das Kompatibilitätsproblem zwischen JSON3 und BigQuery-Typen zu lösen.

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

In partitionierte Tabellen exportieren

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

gcloud

Führen Sie den folgenden Befehl aus, um Assets in ein Projekt in partitionierten Tabellen zu exportieren. Dieser Befehl speichert den exportierten Snapshot in einer BigQuery-Tabelle unter BIGQUERY_TABLE mit täglicher Granularität und zwei zusätzlichen Zeitstempelspalten, readTime und requestTime, wobei es sich um den Partitionierungsschlüssel gemäß Ihren Parameter partition-key handelt.

  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 \

Wobei:

• CONTENT_TYPE ist der Inhaltstyp des Assets.
• 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 Partitionierungsschlüsselspalte beim Exportieren in partitionierte BigQuery-Tabellen.
• --output-bigquery-force überschreibt die Zieltabelle, falls sie vorhanden ist.

API

Führen Sie den folgenden Befehl aus, um Assets in ein Projekt in partitionierten Tabellen zu exportieren. Dieser Befehl speichert den exportierten Snapshot in einer BigQuery-Tabelle unter BIGQUERY_TABLE mit täglicher Granularität und zwei zusätzlichen Zeitstempelspalten, readTime und requestTime, wobei es sich um den Partitionierungsschlüssel gemäß Ihren Parameter partition-key handelt. Weitere Informationen zur Methode „exportAssets“

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

Wenn eine Zieltabelle bereits vorhanden ist, wird das Schema der vorhandenen Tabelle bei Bedarf aktualisiert, indem zusätzliche Spalten angefügt werden. Diese Schemaaktualisierung schlägt fehl, wenn Spalten ihren Typ oder Modus ändern, z. B. optional in wiederholt. Wenn das Flag output-bigquery-force auf TRUE gesetzt ist, wird die entsprechende Partition von den Snapshot-Ergebnissen überschrieben. Die Daten in einer oder mehreren verschiedenen Partitionen bleiben jedoch intakt. Wenn output-bigquery-force nicht festgelegt oder FALSE gesetzt ist, werden die Daten an die entsprechende Partition angefügt.

Der Exportvorgang schlägt fehl, wenn eine Schemaaktualisierung oder ein Versuch zum Anfügen von Daten 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. Er wird im gcloud-Tool 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 Seite „BigQuery“ 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. Unter Umständen benötigen Sie diesen Wert, um den Startpunkt für Ihre Ergebnisse mit dem gcloud-Tool oder API festzulegen.

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.

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 Seite „BigQuery“ 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.