Exportar metadatos de recursos a 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

Proporciona los siguientes valores:

• SCOPE: usa uno de los siguientes valores:

  • project=PROJECT_ID, donde PROJECT_ID es el ID del proyecto que tiene los metadatos del recurso que quieres exportar.

  • folder=FOLDER_ID, donde FOLDER_ID es el ID de la carpeta que contiene los metadatos del recurso que quieres exportar.

    Cómo encontrar el ID de una Google Cloud carpeta

    Google Cloud consola

    Para encontrar el ID de una carpeta de Google Cloud , sigue estos pasos:

    1. Ve a la Google Cloud consola.

       Ve a la Google Cloud consola

    2. En la barra de menús, haz clic en el cuadro de lista del selector.
    3. Selecciona tu organización en el cuadro de lista.
    4. Busca el nombre de la carpeta. El ID de la carpeta se muestra junto al nombre de la carpeta.

    CLI de gcloud

    Puedes obtener el ID de una Google Cloud carpeta que se encuentre a nivel de organización con el siguiente comando:

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

    Donde TOP_LEVEL_FOLDER_NAME es una coincidencia parcial o completa de la cadena del nombre de la carpeta. Quita la marca --format para ver más información sobre las carpetas encontradas.

    El comando anterior no devuelve los IDs de las subcarpetas de las carpetas. Para ello, ejecuta el siguiente comando con el ID de una carpeta de nivel superior:

    gcloud resource-manager folders list --folder=FOLDER_ID

  • organization=ORGANIZATION_ID, donde ORGANIZATION_ID es el ID de la organización que tiene los metadatos del recurso que quieres exportar.

    Cómo encontrar el ID de una Google Cloud organización

    Google Cloud consola

    Para encontrar el ID de una organización de Google Cloud , sigue estos pasos:

    1. Ve a la Google Cloud consola.

       Ve a la Google Cloud consola

    2. En la barra de menús, haz clic en el cuadro de lista del selector.
    3. Selecciona tu organización en el cuadro de lista.
    4. Haz clic en la pestaña Todas. El ID de la organización se muestra junto al nombre de la organización.

    CLI de gcloud

    Puedes obtener el ID de una Google Cloud organización con el siguiente comando:

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

• BILLING_PROJECT_ID: opcional. El ID del proyecto en el que se encuentra el agente de servicio predeterminado de Cloud Asset Inventory, que tiene permisos para gestionar tus conjuntos de datos y tablas de BigQuery. Consulta más información sobre cómo definir el proyecto de facturación.

• ASSET_TYPE_#: opcional. Lista separada por comas de tipos de recursos que se pueden buscar. Se admiten expresiones regulares compatibles con RE2. Si la expresión regular no coincide con ningún tipo de recurso admitido, se devuelve un error INVALID_ARGUMENT. Si no se especifica --asset-types, se devuelven todos los tipos de recursos.
• CONTENT_TYPE: opcional. El tipo de contenido de los metadatos que quieras obtener. Si no se especifica --content-type, solo se devuelve información básica, como los nombres de los recursos, la última vez que se actualizaron y los proyectos, las carpetas y las organizaciones a los que pertenecen.
• RELATIONSHIP_TYPE_#: opcional. Se requiere acceso al nivel Premium o Enterprise de Security Command Center o a Gemini Cloud Assist. Lista separada por comas de tipos de relaciones de recursos que quieras obtener. Para que funcione, debes asignar el valor RELATIONSHIP a CONTENT_TYPE.
• SNAPSHOT_TIME: opcional. La hora a la que quieres hacer una captura de tus recursos, en formato de fecha y hora de gcloud topic. El valor no debe ser de hace más de 35 días. Si no se especifica --snapshot-time, se hace una captura en el momento actual.

• OUTPUT_TYPE: usa uno de los siguientes valores:

  • --output-path="gs://BUCKET_NAME/FILE_NAME" para escribir la salida en un archivo, donde:

    • BUCKET_NAME es el nombre del segmento de Cloud Storage en el que se va a escribir.
    • FILE_NAME es el archivo en el que se va a escribir en tu segmento de Cloud Storage.

  • --output-path-prefix="gs://BUCKET_NAME/FOLDER_NAME"para escribir la salida en una carpeta, donde:

    • BUCKET_NAME es el nombre del segmento de Cloud Storage en el que se va a escribir.
    • FOLDER_NAME es la carpeta en la que se escribirán los datos en tu segmento de Cloud Storage. La salida se divide en subcarpetas con el nombre de los tipos de recursos. Las subcarpetas no deben existir ya en la carpeta que especifiques.

Consulta la referencia de la CLI de gcloud para ver todas las opciones.

Ejemplo

Ejecuta el siguiente comando para exportar los metadatos de resource tal como estaban el 30 de enero del 2024 en el proyecto my-project al archivo my-file.txt del segmento de Cloud Storage my-bucket.

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"

Respuesta de ejemplo

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

Método HTTP y URL:

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

Encabezados:

X-Goog-User-Project: BILLING_PROJECT_ID

Cuerpo JSON de la solicitud:

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

Proporciona los siguientes valores:

• SCOPE_PATH: usa uno de los siguientes valores:

  Los valores permitidos son:

  • projects/PROJECT_ID, donde PROJECT_ID es el ID del proyecto que tiene los metadatos del recurso que quieres exportar.

  • projects/PROJECT_NUMBER, donde PROJECT_NUMBER es el número del proyecto que tiene los metadatos del recurso que quieres exportar.

    Cómo encontrar el Google Cloud número de proyecto

    Google Cloud consola

    Para encontrar un número de proyecto de Google Cloud , sigue estos pasos:

    1. Ve a la página Bienvenida de la Google Cloud consola.

       Ir a Bienvenida

    2. En la barra de menús, haz clic en el cuadro de lista del selector.

    3. Selecciona tu organización en el cuadro de lista y, a continuación, busca el nombre de tu proyecto. El nombre, el número y el ID del proyecto se muestran cerca del encabezado Bienvenido.

       Se muestran hasta 4000 recursos. Si no ves el proyecto que buscas, ve a la página Gestionar recursos y filtra la lista por el nombre de ese proyecto.

    CLI de gcloud

    Puedes obtener un Google Cloud número de proyecto con el siguiente comando:

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

  • folders/FOLDER_ID, donde FOLDER_ID es el ID de la carpeta que contiene los metadatos del recurso que quieres exportar.

    Cómo encontrar el ID de una Google Cloud carpeta

    Google Cloud consola

    Para encontrar el ID de una carpeta de Google Cloud , sigue estos pasos:

    1. Ve a la Google Cloud consola.

       Ve a la Google Cloud consola

    2. En la barra de menús, haz clic en el cuadro de lista del selector.
    3. Selecciona tu organización en el cuadro de lista.
    4. Busca el nombre de la carpeta. El ID de la carpeta se muestra junto al nombre de la carpeta.

    CLI de gcloud

    Puedes obtener el ID de una Google Cloud carpeta que se encuentre a nivel de organización con el siguiente comando:

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

    Donde TOP_LEVEL_FOLDER_NAME es una coincidencia parcial o completa de la cadena del nombre de la carpeta. Quita la marca --format para ver más información sobre las carpetas encontradas.

    El comando anterior no devuelve los IDs de las subcarpetas de las carpetas. Para ello, ejecuta el siguiente comando con el ID de una carpeta de nivel superior:

    gcloud resource-manager folders list --folder=FOLDER_ID

  • organizations/ORGANIZATION_ID, donde ORGANIZATION_ID es el ID de la organización que tiene los metadatos del recurso que quieres exportar.

    Cómo encontrar el ID de una Google Cloud organización

    Google Cloud consola

    Para encontrar el ID de una organización de Google Cloud , sigue estos pasos:

    1. Ve a la Google Cloud consola.

       Ve a la Google Cloud consola

    2. En la barra de menús, haz clic en el cuadro de lista del selector.
    3. Selecciona tu organización en el cuadro de lista.
    4. Haz clic en la pestaña Todas. El ID de la organización se muestra junto al nombre de la organización.

    CLI de gcloud

    Puedes obtener el ID de una Google Cloud organización con el siguiente comando:

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

• BILLING_PROJECT_ID: El ID del proyecto en el que se encuentra el agente de servicio predeterminado de Cloud Asset Inventory, que tiene permisos para gestionar tus conjuntos de datos y tablas de BigQuery. Consulta más información sobre cómo definir el proyecto de facturación.

• ASSET_TYPE_#: opcional. Una matriz de tipos de recursos que se pueden buscar. Se admiten expresiones regulares compatibles con RE2. Si la expresión regular no coincide con ningún tipo de recurso admitido, se devuelve un error INVALID_ARGUMENT. Si no se especifica assetTypes, se devuelven todos los tipos de recursos.
• CONTENT_TYPE: opcional. El tipo de contenido de los metadatos que quieras obtener. Si no se especifica contentType, solo se devuelve información básica, como los nombres de los recursos, la última vez que se actualizaron y los proyectos, las carpetas y las organizaciones a los que pertenecen.
• RELATIONSHIP_TYPE_#: opcional. Se requiere acceso al nivel Premium o Enterprise de Security Command Center o a Gemini Cloud Assist. Lista separada por comas de tipos de relaciones de recursos que quieras obtener. Para que funcione, debes asignar el valor RELATIONSHIP a CONTENT_TYPE.
• SNAPSHOT_TIME: opcional. La hora a la que quieres hacer una instantánea de tus recursos, en formato RFC 3339. El valor no debe ser de hace más de 35 días. Si no se especifica readTime, se hace una captura en el momento actual.

• OUTPUT_TYPE: usa uno de los siguientes valores:

  • "uri": "gs://BUCKET_NAME/FILE_NAME" para escribir la salida en un archivo, donde:

    • BUCKET_NAME es el nombre del segmento de Cloud Storage en el que se va a escribir.
    • FILE_NAME es el archivo en el que se va a escribir en tu segmento de Cloud Storage.

  • "uriPrefix": "gs://BUCKET_NAME/FOLDER_NAME"para escribir la salida en una carpeta, donde:

    • BUCKET_NAME es el nombre del segmento de Cloud Storage en el que se va a escribir.
    • FOLDER_NAME es la carpeta en la que se escribirán los datos en tu segmento de Cloud Storage. La salida se divide en subcarpetas con el nombre de los tipos de recursos. Las subcarpetas no deben existir ya en la carpeta que especifiques.

Consulta la referencia de REST para ver todas las opciones.

Ejemplos de comandos

Ejecuta uno de los siguientes comandos para exportar los metadatos de resource tal como estaban el 30 de enero del 2024 en el proyecto my-project al archivo my-file.txt del segmento de Cloud Storage my-bucket.

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

Respuesta de ejemplo

{
  "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

Para ver el estado de la exportación, sigue estas instrucciones:

1. Obtén el OPERATION_PATH, que incluye el ID de la operación, de la respuesta a tu solicitud de exportación. El OPERATION_PATH se muestra en la respuesta a la exportación, que tiene el siguiente formato:

   projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
   

2. Para comprobar el estado de la exportación, ejecuta el siguiente comando con OPERATION_PATH:

   gcloud asset operations describe OPERATION_PATH
   

REST

Para ver el estado de la exportación, sigue estas instrucciones:

1. Obtén el OPERATION_PATH, que incluye el ID de la operación, de la respuesta a tu solicitud de exportación. El OPERATION_PATH se muestra como el valor del campo name en la respuesta a la exportación, que tiene el siguiente formato:

   projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
   

2. Para comprobar el estado de tu exportación, haz la siguiente solicitud.

   REST

   Método HTTP y URL:

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

   Ejemplos de comandos

   curl (Linux, macOS o 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

   Respuesta de ejemplo

   {
     "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"
         }
       }
     }
   }