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.
Aktivieren Sie die Cloud Asset Inventory API in dem Projekt, in dem Sie die API-Befehle ausführen werden.
Cloud Asset Inventory API aktivierenKonfigurieren Sie die Berechtigungen, die zum Aufrufen der Cloud Asset Inventory API entweder über die gcloud-Befehlszeile oder die API erforderlich sind.
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.- Installieren Sie oauth2l auf Ihrem lokalen Gerät, um mit dem Google OAuth-System zu interagieren.
- Prüfen Sie, ob Sie Zugriff auf den Unix-Befehl
curl
haben. 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
)
- Rolle „Cloud-Asset-Betrachter“ (
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
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:service-PROJECT_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com --role=roles/cloudasset.serviceAgent
- Rolle „BigQuery-Datenbearbeiter“ (
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 oderforce
mit der API.Google Kubernetes Engine-Ressourcentypen (GKE) mit Ausnahme von
container.googleapis.com/Cluster
undcontainer.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 Flagper-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.Wenn du den Inhaltstyp auf
RESOURCE
setzt oder nicht festlegst und das Flagper-asset-type
auftrue
setzt, erstellst du separate Tabellen pro Asset-Typ. Das Schema jeder Tabelle enthält Spalten vom Typ RECORD, die den verschachtelten Feldern im FeldResource.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 aufiam-policy
in der gcloud-Befehlszeile festlegen, erstellen Sie eine BigQuery-Tabelle mit dem Schema, das in Abbildung 2 gezeigt wird. Dieiam_policy
RECORD
ist vollständig erweitert.Organisationsrichtlinie: Wenn Sie den Inhaltstyp in der REST API auf
ORG_POLICY
oder auforg-policy
in der gcloud-Befehlszeile festlegen, erstellen Sie eine BigQuery-Tabelle mit dem Schema von Abbildung 3.VPCSC-Richtlinie: Wenn Sie den Inhaltstyp in der REST API auf
ACCESS_POLICY
oder aufaccess-policy
in der gcloud-Befehlszeile festlegen, erstellen Sie eine BigQuery-Tabelle mit dem Schema, das in Abbildung 4 gezeigt wird.OSConfig-Instanzinventar: Wenn Sie in der REST API oder auf
os-inventory
in der gcloud-Befehlszeile den Inhaltstyp aufOS_INVENTORY
setzen, erstellen Sie eine BigQuery-Tabelle mit dem Schema von Abbildung 5.
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
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
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:
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.
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"
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
Rufen Sie in der Cloud Console die BigQuery-Seite auf.
Zur Seite "BigQuery"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.
Wählen Sie in der Liste die gewünschte Tabelle aus.
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.
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.
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
Rufen Sie in der Cloud Console die BigQuery-Seite auf.
Zur Seite "BigQuery"Wählen Sie
Neue Abfrage erstellen aus.Geben Sie im Textbereich des Abfrageeditors eine gültige BigQuery-SQL-Abfrage ein.
(Optional) Führen Sie die folgenden Schritte aus, um den Standort der Datenverarbeitung zu ändern.
- Wählen Sie Mehr und dann Abfrageeinstellungen aus.
- Wählen Sie unter Verarbeitungsstandort die Option Automatische Auswahl und dann den Standort Ihrer Daten aus.
- Klicken Sie auf Speichern, um die Abfrageeinstellungen zu aktualisieren.
Wählen Sie Ausführen aus.
API
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 Feldquery
auf eine JobConfigurationQuery fest, die den BigQuery-Abfragejob beschreibt.Legen Sie im Feld
jobReference
das Feldlocation
dem Job entsprechend fest.
Rufen Sie
getQueryResults
auf, um die Ergebnisse abzufragen. Führen Sie die Abfrage so lange aus, bisjobComplete
gleichtrue
ist. In der Listeerrors
können Sie nach Fehlern und Warnungen suchen.