Criar e gerenciar relatórios de inventário

Nesta página, descrevemos como criar e gerenciar configurações de relatório de inventário e relatórios de inventário gerados para que você possa receber um resumo de alto nível de todos os metadados dos objetos em um determinado bucket. Para uma visão geral dos relatórios de inventário, consulte a documentação de visão geral dos relatórios de inventário do Storage Insights.

Antes de começar

Acessar os papéis necessários

A fim de ter as permissões necessárias para criar e gerenciar relatórios de inventário, peça que o administrador conceda a você os seguintes papéis do IAM no projeto ou nos buckets de origem e destino com que você gerenciará os relatórios de inventário.

  • Para criar e gerenciar configurações de relatórios de inventário:

    • roles/storage.admin nos buckets de origem e de destino

    • roles/storageinsights.admin no projeto

  • Para ler e fazer o download de relatórios de inventário:

    • roles/storage.objectViewer no bucket de destino

    • roles/storageinsights.viewer no projeto

Esses papéis predefinidos contêm as permissões necessárias para criar e gerenciar relatórios e configurações de inventário. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

Para criar e gerenciar configurações de relatórios de inventário:

  • storage.buckets.get no bucket de origem
  • storage.objects.list no bucket de origem
  • storage.buckets.getObjectInsights no bucket de origem
  • storage.buckets.get no bucket de destino
  • storage.objects.create no bucket de destino
  • storageinsights.reportConfigs.delete no projeto
  • storageinsights.reportConfigs.get no projeto
  • storageinsights.reportConfigs.create no projeto
  • storageinsights.reportConfigs.list no projeto
  • storageinsights.reportConfigs.update no projeto

Para ler e fazer o download de relatórios de inventário:

  • storage.objects.get no bucket de destino
  • storageinsights.reportDetails.get no projeto
  • storageinsights.reportDetails.list no projeto

Também é possível conseguir essas permissões com outros papéis predefinidos. Para conferir quais papéis estão associados a quais permissões, consulte Papéis do IAM para o Cloud Storage.

Para instruções sobre como usar papéis para controlar o acesso a buckets, consulte Usar o IAM. Para ver instruções sobre como usar papéis para controlar o acesso a projetos, consulte Gerenciar o acesso.

Ativar a API Storage Insights

Console

Para ativar a API storageinsights.googleapis.com, siga as instruções em Como ativar serviços.

Linha de comando

Para ativar a API Storage Insights no projeto atual, execute o seguinte comando:

gcloud services enable storageinsights.googleapis.com

Para mais detalhes sobre como ativar serviços em um projeto do Google Cloud, consulte Como ativar e desativar serviços.

APIs REST

API JSON

Use o console do Google Cloud ou a Google Cloud CLI para ativar a API Storage Insights.

Criar uma configuração de relatório de inventário

Console

Para criar uma configuração de um relatório de inventário, siga estas etapas:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket que você quer usar como o bucket de origem.

  3. Na página Detalhes do bucket, clique na guia Relatórios de inventário.

  4. Clique em Criar configuração de relatório.

  5. Na seção Identifique a configuração do relatório, crie um nome de exibição para a configuração do relatório de inventário. O nome de exibição pode conter até 256 caracteres.

  6. Na seção Escolher campos de metadados, selecione os campos de metadados que você quer incluir nos seus relatórios de inventário.

  7. Clique em Continuar.

  8. Na seção Escolher um formato de arquivo, selecione o formato em que você quer gerar relatórios de inventário.

  9. Na seção Escolha um bucket de destino, selecione o bucket que você quer usar como um bucket de destino.

    Na seção Inserir caminho de destino (opcional), é possível especificar um caminho de destino em que os relatórios de inventário serão gerados.

  10. Na seção Opções de programação, especifique a frequência, a data de início e a data de término para gerar os relatórios.

  11. Clique em Criar.

    A página Detalhes de configuração do relatório é exibida. Os metadados dos relatórios de inventário gerados serão exibidos na página.

Linha de comando

  1. Para criar uma configuração de relatório de inventário, execute o comando gcloud storage insights inventory-reports create:

    gcloud storage insights inventory-reports create SOURCE_BUCKET_URL \
  --csv-separator=SEPARATOR \
  --csv-delimiter=DELIMITER \
  --[no]-csv-header \
  --parquet \
  --display-name=DISPLAY_NAME \
  --destination=DESTINATION_PATH \
  --metadata-fields=METADATA_FIELD \
  --schedule-starts=START_DATE \
  --schedule-repeats=FREQUENCY \
  --schedule-repeats-until=END_DATE

    Substitua:

    • SOURCE_BUCKET_URL pelo URL do bucket de origem. Por exemplo, gs://my_example_source_bucket.

    • SEPARATOR pelo caractere usado para separar os registros no arquivo CSV do relatório de inventário. \n: precisa ser \r\n ou . O valor padrão é \n. Opcional. Se a sinalização --csv-separator for usada, não será possível usar --parquet.

    • DELIMITER pelo delimitador que separa os campos no arquivo CSV do relatório de inventário. O valor pode incluir um caractere e não pode ser o mesmo valor de SEPARATOR. O valor padrão é ,. Opcional. Se --csv-delimiter for usado, não será possível usar --parquet.

    • --[no]-csv-header pela sinalização que indica se os cabeçalhos estão incluídos no arquivo CSV do relatório de inventário. Use --csv-header para incluir cabeçalhos e --no-csv-header para excluí-los. Se qualquer uma das sinalizações for usada, --parquet não poderá ser usado.

    • DISPLAY_NAME pelo nome editável da configuração de relatório de inventário. Opcional.

    • --parquet pela sinalização que gera relatórios de inventário no formato Apache Parquet em vez de CSV. Se usado, --csv-delimiter, --csv-separator e --[no-]csv-header não podem ser usados.

    • DESTINATION_PATH pelo bucket ou pasta no bucket em que os relatórios de inventário serão gerados. Por exemplo, gs://my_example_destination_bucket ou gs://my_example_destination_bucket/path/to/inventory/report.

      Ao especificar um caminho para uma pasta em um bucket, é possível usar palavras-chave no caminho, que são substituídas por seus valores correspondentes quando o relatório é gerado. Isso permite gerar relatórios em um formato particionado do Hive para carregar ou consultar os dados no BigQuery sem processamento adicional.

    • METADATA_FIELD por uma lista separada por vírgulas de campos de metadados que você quer incluir no relatório de inventário.

    • START_DATE pela data em que você quer começar a gerar relatórios de inventário. Por exemplo, 2022-01-15.

    • FREQUENCY pela frequência com que você quer que os relatórios de inventário sejam gerados. Os valores são daily ou weekly.

    • END_DATE pela data após a qual você quer parar de gerar relatórios de inventário. Precisa ser um valor posterior a START_DATE. Por exemplo, se você especificar 2022-02-15, os relatórios de inventário não serão mais gerados a partir de 16 de fevereiro de 2022.

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.storageinsights.v1.CSVOptions;
import com.google.cloud.storageinsights.v1.CloudStorageDestinationOptions;
import com.google.cloud.storageinsights.v1.CloudStorageFilters;
import com.google.cloud.storageinsights.v1.CreateReportConfigRequest;
import com.google.cloud.storageinsights.v1.FrequencyOptions;
import com.google.cloud.storageinsights.v1.LocationName;
import com.google.cloud.storageinsights.v1.ObjectMetadataReportOptions;
import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import com.google.common.collect.ImmutableList;
import com.google.type.Date;
import java.io.IOException;

public class CreateInventoryReportConfig {

  public static void createInventoryReportConfig(
      String projectId, String bucketLocation, String sourceBucket, String destinationBucket)
      throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfig reportConfig =
          ReportConfig.newBuilder()
              .setDisplayName("Example inventory report configuration")
              .setFrequencyOptions(
                  FrequencyOptions.newBuilder()
                      .setFrequency(FrequencyOptions.Frequency.WEEKLY)
                      .setStartDate(Date.newBuilder().setDay(15).setMonth(8).setYear(3022).build())
                      .setEndDate(Date.newBuilder().setDay(15).setMonth(9).setYear(3022).build())
                      .build())
              .setCsvOptions(
                  CSVOptions.newBuilder()
                      .setDelimiter(",")
                      .setRecordSeparator("\n")
                      .setHeaderRequired(true)
                      .build())
              .setObjectMetadataReportOptions(
                  ObjectMetadataReportOptions.newBuilder()
                      .addAllMetadataFields(ImmutableList.of("project", "name", "bucket"))
                      .setStorageFilters(
                          CloudStorageFilters.newBuilder().setBucket(sourceBucket).build())
                      .setStorageDestinationOptions(
                          CloudStorageDestinationOptions.newBuilder()
                              .setBucket(destinationBucket)
                              .build())
                      .build())
              .build();
      CreateReportConfigRequest request =
          CreateReportConfigRequest.newBuilder()
              .setParent(LocationName.of(projectId, bucketLocation).toString())
              .setReportConfig(reportConfig)
              .build();
      ReportConfig response = storageInsightsClient.createReportConfig(request);
      System.out.println("Created inventory report config with name " + response.getName());
    }
  }
}

APIs REST

API JSON

Para criar uma configuração de um relatório de inventário, siga estas etapas:

  1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

    Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

  2. Crie um arquivo JSON que contenha as seguintes informações, em que todos os campos são obrigatórios, a menos que especificado de outra forma:

    {
  "display_name": "DISPLAY_NAME",
  "frequency_options": {
    "frequency": "FREQUENCY",
    "start_date": "START_DATE",
    "end_date": "END_DATE",
  },
  "csv_options": {
    "record_separator": "RECORD_SEPARATOR",
    "delimiter": "DELIMITER",
    "header_required": HEADER_REQUIRED
  },
  "object_metadata_report_options": {
     "metadata_fields": [
      "METADATA_FIELD",
      ...
    ],
    "storage_filters": {
      "bucket": "SOURCE_BUCKET_NAME"
    },
    "storage_destination_options": {
      "bucket": "DESTINATION_BUCKET_NAME",
      "destination_path": "DESTINATION_PATH"
    }
  }
}

    Substitua:

    • DISPLAY_NAME pelo nome de exibição editável da configuração de relatório de inventário. Pode conter até 256 caracteres.

    • FREQUENCY pela frequência de geração de relatórios de inventário. Os valores são DAILY ou WEEKLY.

    • START_DATE pela data em que você quer começar a gerar relatórios de inventário. Não pode ser a data atual ou qualquer data passada. O valor precisa ser um objeto contendo as chaves day, month e year. Por exemplo, {"day": 15, "month": 8, "year": 2022}.

    • END_DATE pela data após a qual você quer parar de gerar relatórios de inventário. O valor precisa ser um objeto que contenha as chaves day, month e year. Por exemplo, se você especificar {"day": 15, "month": 9, "year": 2022}, os relatórios de inventário não serão mais gerados a partir de 16 de setembro de 2022.

    • RECORD_SEPARATOR pelo caractere usado para separar os registros no arquivo CSV do relatório de inventário. \n: precisa ser \r\n ou . O valor padrão é \n. Este campo é opcional.

    • DELIMITER pelo delimitador que separa os campos no arquivo CSV do relatório de inventário. O valor pode incluir um caractere e não pode ser igual ao RECORD_SEPARATOR. O valor padrão é ,. Este campo é opcional.

    • HEADER_REQUIRED pelo booleano que indica se os cabeçalhos estão incluídos no arquivo CSV. Este campo é opcional.

    • SOURCE_BUCKET_NAME pelo nome do bucket de origem que contém os objetos para os quais você quer gerar relatórios de inventário. Por exemplo, my_example_bucket.

    • METADATA_FIELD por uma lista separada por vírgulas de campos de metadados que você quer incluir no relatório de inventário.

    • DESTINATION_BUCKET_NAME pelo nome do bucket de destino em que os relatórios de inventário gerados são gerados e armazenados. Por exemplo, my_example_destination_bucket.

    • DESTINATION_PATH pelo caminho no bucket de destino em que os relatórios de inventário gerados são armazenados. Este campo é opcional.

      Ao especificar um caminho para uma pasta em um bucket, é possível usar palavras-chave no caminho, que são substituídas por seus valores correspondentes quando o relatório é gerado. Isso permite gerar relatórios em um formato particionado do Hive para carregar ou consultar os dados no BigQuery sem processamento adicional.

    O exemplo de código a seguir cria uma configuração de relatório de inventário chamada "Exemplo de configuração de relatório de inventário" que gera relatórios com uma frequência semanal:

    {
  "display_name": "Example inventory report configuration",
  "frequency_options": {
    "frequency": "WEEKLY",
    "start_date": {
      "day": 15,
      "month": 8,
      "year": 2022
    },
    "end_date": {
      "day": 15,
      "month": 9,
      "year": 2022
    },
  },
  "csv_options": {
    "record_separator": "\n",
    "delimiter": ",",
    "header_required": true
  },
  "object_metadata_report_options": {
     "metadata_fields": [
      "project",
      "name",
      "bucket"
    ],
    "storage_filters": {
      "bucket": "example_source_bucket"
    },
    "storage_destination_options": {
      "bucket": "example_destination_bucket"
    }
  }
}

  3. Para aplicar a configuração do relatório de inventário, use cURL para chamar a API JSON com uma solicitação Insert ReportConfig:

    curl -X POST --data-binary @JSON_FILE_NAME \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • JSON_FILE_NAME pelo caminho para o arquivo JSON criado na etapa anterior.

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

Conceder os papéis necessários ao agente de serviço

Um agente de serviço para envolvidos no projeto é criado automaticamente na primeira vez que você define uma configuração de relatório de inventário. O agente de serviço segue o formato de nomenclatura service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com e aparece na página do IAM no console do Google Cloud quando você seleciona a caixa de seleção Incluir concessões de funções fornecidas pelo Google.

Para permitir que o Storage Insights gere e grave relatórios de inventário, peça ao administrador para conceder ao agente de serviço os seguintes papéis do IAM:

  • roles/storage.insightsCollectorService no bucket de origem, que inclui as permissões storage.buckets.getObjectInsights e storage.buckets.get
  • roles/storage.objectCreator no bucket de destino, que inclui a permissão storage.objects.create.

Para instruções sobre como conceder papéis, consulte Usar IAM. É possível conceder o papel roles/storage.insightsCollectorService usando o console do Google Cloud ou a CLI do Google Cloud. Por exemplo: 

gcloud storage buckets add-iam-policy-binding SOURCE_BUCKET_URL \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com \
    --role=roles/storage.insightsCollectorService

Depois que o agente de serviço recebe as permissões necessárias, pode levar até 24 horas para gravar o primeiro relatório de inventário no bucket de destino.

Editar uma configuração de relatório de inventário

Depois de criar uma configuração de relatório de inventário, é possível modificar determinadas propriedades dela.

Console

Para editar a configuração de um relatório de inventário, siga as etapas abaixo:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket de origem que contém a configuração do relatório de inventário que você quer editar.

  3. Na página Detalhes do bucket do bucket de origem, clique na guia Relatórios de inventário.

  4. Clique no nome da configuração do relatório de inventário que você quer editar.

  5. Na página Detalhes da configuração do relatório exibida, edite as propriedades desejadas usando o botão Editar .

Linha de comando

Para editar a configuração de um relatório de inventário, siga as etapas abaixo:

  1. Para encontrar o nome da configuração do relatório de inventário que você quer editar, liste todas as configurações de inventário no bucket de origem usando o comando gcloud storage insights inventory-reports list:

    gcloud storage insights inventory-reports list \
  --source=SOURCE_BUCKET \
  --filter=EXPRESSION \
  --page-size=SIZE \
  --sort-by=FIELD \
  --format="yaml(name)"

    Substitua:

    • SOURCE_BUCKET pelo URL do bucket de origem que contém a configuração de relatório de inventário.

    • EXPRESSION por um filtro booleano aplicado a cada item de recurso a ser listado. Se a expressão avaliar como verdadeiro, o item será listado. Para mais detalhes e exemplos de expressões de filtro, execute $ gcloud topic filters.

    • SIZE pelo número máximo de recursos por página. O padrão é 50.

    • FIELD por uma lista separada por vírgulas de nomes de chaves de campos de recursos para ordenação. A ordem padrão é crescente. Adicione um prefixo ao campo com ~ para ordem decrescente nesse campo.

    1. Edite os campos de configuração do relatório de inventário que você quer atualizar usando o comando gcloud storage insights inventory-reports update. O exemplo a seguir atualiza a configuração do relatório de inventário para gerar relatórios de inventário diariamente no formato Apache Parquet:

      gcloud storage insights inventory-reports update CONFIG_NAME \
--parquet \
--schedule-repeats="daily"

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.ReportConfigName;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import com.google.cloud.storageinsights.v1.UpdateReportConfigRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class EditInventoryReportConfig {


  public static void editInventoryReportConfig(
          String projectId, String location, String inventoryReportConfigUuid) throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfigName name = ReportConfigName.of(projectId, location, inventoryReportConfigUuid);
      ReportConfig reportConfig = storageInsightsClient.getReportConfig(name);

      // Set any other fields you want to update here
      ReportConfig updatedReportConfig =
              reportConfig.toBuilder().setDisplayName("Updated Display Name").build();

      storageInsightsClient.updateReportConfig(
              UpdateReportConfigRequest.newBuilder()
                      // Add any fields that you want to update to the update mask, in snake case
                      .setUpdateMask(FieldMask.newBuilder().addPaths("display_name")
                              .build())
                      .setReportConfig(updatedReportConfig).build());

      System.out.println("Edited inventory report config with name " + name);
    }
  }
}

APIs REST

API JSON

Para editar a configuração de um relatório de inventário, siga estas etapas:

  1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

    Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

  2. Encontre o nome da configuração de relatório de inventário que você quer editar usando cURL para chamar a API JSON com uma solicitação Get ReportConfig:

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    Se você quiser recuperar todas as configurações de relatório de inventário em um bucket de origem específico, anexe o parâmetro de consulta filter à solicitação:

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?filter=objectMetadataReportOptions.storageFilters.bucket=BUCKET_NAME" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.
    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.
    • BUCKET_NAME pelo nome do bucket de origem que contém as configurações do relatório de inventário que você quer editar.

  3. Crie um arquivo JSON que inclua alterações nas propriedades que você quer editar. O exemplo a seguir atualiza a configuração do relatório de inventário para gerar relatórios de inventário diariamente no formato Apache Parquet:

    {
  "ReportConfig": {
    "frequency_options": {
      "frequency": "DAILY"
    },
    "parquet_options": {
    }
  }

  4. Para aplicar a configuração do relatório de inventário, use cURL para chamar a API JSON com uma solicitação Patch ReportConfig:

    curl --request PATCH \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data-binary "@JSON_FILE_NAME.json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    • REPORT_CONFIG_UUID pelo UUID gerado automaticamente da configuração de relatório de inventário.

Liste configurações de relatório de inventário

Console

Para listar as configurações do relatório de inventário em um bucket de origem, conclua as etapas abaixo:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket de origem que contém as configurações do relatório de inventário que você quer visualizar.

  3. Na página Detalhes do bucket, clique na guia Relatórios de inventário.

    As configurações do relatório de inventário no bucket de origem são exibidas.

Linha de comando

É possível listar todas as configurações de inventário em um bucket de origem usando o comando gcloud storage insights inventory-reports list:

gcloud storage insights inventory-reports list \
  --source=SOURCE_BUCKET \
  --filter=EXPRESSION \
  --page-size=SIZE \
  --sort-by=FIELD \
  --format="yaml(name)"

Substitua:

  • SOURCE_BUCKET pelo URL do bucket de origem que contém a configuração de relatório de inventário.

  • EXPRESSION por um filtro booleano aplicado a cada item de recurso a ser listado. Se a expressão avaliar como verdadeiro, o item será listado. Para mais detalhes e exemplos de expressões de filtro, execute $ gcloud topic filters.

  • SIZE pelo número máximo de recursos por página. O padrão é 50.

  • FIELD por uma lista separada por vírgulas de nomes de chaves de campos de recursos para ordenação. A ordem padrão é crescente. Adicione um prefixo ao campo com ~ para ordem decrescente nesse campo.

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.storageinsights.v1.LocationName;
import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import java.io.IOException;

public class ListInventoryReportConfigs {


  public static void listInventoryReportConfigs(String projectId, String location)
      throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      System.out.println(
          "Printing inventory report configs in project "
              + projectId
              + " and location "
              + location);
      for (ReportConfig config :
          storageInsightsClient
              .listReportConfigs(LocationName.of(projectId, location))
              .iterateAll()) {
        System.out.println(config.getName());
      }
    }
  }
}

APIs REST

API JSON

  1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

    Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

  2. É possível listar todas as configurações de relatórios de inventário em um projeto para um determinado local usando uma solicitação para listar configurações de relatório de inventário:

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    Se você quiser listar todas as configurações de relatório de inventário em um bucket de origem específico, anexe o parâmetro de consulta filter à solicitação:

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?filter=objectMetadataReportOptions.storageFilters.bucket=BUCKET_NAME" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    • BUCKET_NAME pelo nome do bucket de origem que contém as configurações do relatório de inventário que você quer listar.

Fazer o download de um relatório de inventário

Console

Download de relatórios individuais

Os relatórios de inventário são gerados e armazenados como objetos no bucket de destino. Assim, é possível fazer o download deles como o de um objeto normal.

Para fazer o download de um relatório de inventário, siga estas etapas:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket de destino que contém o relatório de inventário que você quer fazer o download.

  3. Na página Detalhes do bucket, verifique se a guia Objetos está selecionada.

  4. Clique em Download associado ao relatório de inventário que você quer fazer o download.

Se você não sabe o bucket de destino, também pode fazer o download de um relatório de inventário usando a configuração do relatório de inventário que o gerou:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket de origem que contém a configuração do relatório de inventário que gerou o relatório que você quer fazer o download.

  3. Na página Detalhes do bucket, clique no nome da configuração do relatório de inventário.

  4. Na página Detalhes de configuração do relatório exibida, navegue até a seção Histórico de relatórios de inventário e clique no caminho do objeto de destino do relatório de inventário que você quer fazer o download.

    A página Detalhes do bucket é exibida para o bucket de destino que contém o relatório de inventário.

  5. Clique em Download associado ao relatório de inventário que você quer fazer o download.

Download de fragmentos de relatório

Para fazer o download de um relatório de inventário que foi dividido em um ou mais fragmentos, conclua as seguintes etapas:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket de destino que você especificou ao criar a configuração do relatório de inventário.

  3. Na página Detalhes do bucket, verifique se há um arquivo de manifesto. A presença de um arquivo de manifesto indica que todos os fragmentos de um relatório de inventário foram gerados.

    Um exemplo de nome de arquivo de manifesto é fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json.

  4. No bucket de destino, clique em Download associado ao arquivo de manifesto. Anote os nomes dos arquivos de fragmento de que você quer fazer o download do campo report_shards_file_names.

  5. No bucket de destino, clique em Download associado aos arquivos de fragmento de que você quer fazer o download.

Linha de comando

Download de relatórios individuais

Para fazer o download de um relatório de inventário, siga estas etapas:

  1. Para listar todos os relatórios de inventário que foram gerados por uma configuração de relatório de inventário e recuperar seus REPORT_DETAIL_ID, use o comando gcloud storage insights inventory-reports details list:

    gcloud storage insights inventory-reports details list CONFIG_NAME \
  --filter=EXPRESSION \
  --page-size=SIZE \
  --sort-by=FIELD

    Substitua:

    • CONFIG_NAME pelo nome exclusivo da configuração de relatório de inventário, no formato projects/PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID.

    • EXPRESSION por um filtro booleano aplicado a cada item de recurso a ser listado. Se a expressão for avaliada como verdadeira, o item será listado. Para ver mais detalhes e exemplos de expressões de filtro, execute $ gcloud topic filters.

    • SIZE pelo número máximo de recursos por página. O padrão é 50.

    • FIELD por uma lista separada por vírgulas de nomes de chaves de campos de recursos para ordenação. A ordem padrão é crescente. Adicione um prefixo ao campo com ~ para ordem decrescente nesse campo.

    Se for bem-sucedido, o comando retornará uma saída semelhante a esta:

    REPORT_DETAIL_ID            SNAPSHOT_TIME
Report_2023-04-10T00-00     2023-04-10T00:53:03Z
Report_2023-04-12T00-00     2023-04-12T00:52:54Z
Report_2023-04-05T00-00     2023-04-05T00:53:01Z

  2. Para fazer o download de um relatório de inventário, primeiro é necessário recuperar a propriedade reportPathPrefix do objeto ReportDetail. Para acessar o reportPathPrefix de um relatório, use o comando gcloud storage insights inventory-reports details describe:

    gcloud storage insights inventory-reports details describe REPORT_DETAIL_NAME

    Substitua REPORT_DETAIL_NAME pelo nome do relatório de inventário no formato projects/PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID/reportDetails/REPORT_DETAIL_ID.

Download de fragmentos de relatório

Para fazer o download de um relatório de inventário que foi dividido em um ou mais fragmentos, conclua as seguintes etapas:

  1. Faça o download do arquivo de manifesto do relatório de inventário usando o comando gcloud storage cp:

    gcloud storage cp gs://BUCKET_NAME/MANIFEST_FILE_NAME DOWNLOAD_PATH

    Substitua:

    • BUCKET_NAME pelo nome do bucket de destino.

    • MANIFEST_FILE_NAME pelo nome do arquivo de manifesto no bucket de destino, com a seguinte convenção de nomenclatura:

      REPORT_CONFIG_UUID_TARGET_DATETIME_manifest.json

      Em que:

      • REPORT_CONFIG_UUID é o UUID gerado automaticamente da configuração de relatório de inventário que gerou os fragmentos de relatório de que você quer fazer o download.

      • TARGET_DATETIME é a data e hora em que o relatório de inventário foi gerado.

      Por exemplo, fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json.

    • DOWNLOAD_PATH com o caminho para o sistema de arquivos em que você quer salvar o relatório de inventário. Por exemplo, ./example_report.csv.

  2. Para fazer o download de um arquivo de fragmento, use o comando gcloud storage cp:

    gcloud storage cp gs://BUCKET_NAME/SHARD_FILE_NAME DOWNLOAD_PATH

    Substitua:

    • BUCKET_NAME pelo nome do bucket de destino.

    • SHARD_FILE_NAME pelo nome codificado por URL do arquivo de fragmento de que você quer fazer o download. Por exemplo, fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:54_0.csv.

    • DOWNLOAD_PATH com o caminho para o sistema de arquivos em que você quer salvar o relatório de inventário. Por exemplo, ./example_report.csv.

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.ReportConfigName;
import com.google.cloud.storageinsights.v1.ReportDetail;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import java.io.IOException;

public class GetInventoryReportNames {


  public static void getInventoryReportNames(
      String projectId, String location, String reportConfigUuid) throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfig config =
          storageInsightsClient.getReportConfig(
              ReportConfigName.of(projectId, location, reportConfigUuid));
      String extension = config.hasCsvOptions() ? "csv" : "parquet";
      System.out.println(
          "You can use the Google Cloud Storage Client "
              + "to download the following objects from Google Cloud Storage:");
      for (ReportDetail reportDetail :
          storageInsightsClient.listReportDetails(config.getName()).iterateAll()) {
        for (long index = reportDetail.getShardsCount() - 1; index >= 0; index--) {
          System.out.println(reportDetail.getReportPathPrefix() + index + "." + extension);
        }
      }
    }
  }
}

APIs REST

API JSON

Download de relatórios individuais

Para fazer o download de um relatório de inventário, siga estas etapas:

  1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

    Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

  2. Liste todos os relatórios de inventário gerados por uma configuração de relatório de inventário usando cURL para chamar a API JSON com uma solicitação para listar Detalhes do relatório de inventário:

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID/reportDetails/" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    • REPORT_CONFIG_UUID pelo UUID gerado automaticamente da configuração de relatório de inventário que gerou o relatório que você quer fazer o download.

  3. Para ver os detalhes de um relatório individual, use cURL para chamar a API JSON com uma solicitação ReportDetails Get:

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID/reportDetails/REPORT_DETAIL_ID" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    • REPORT_CONFIG_UUID pelo UUID gerado automaticamente da configuração de relatório de inventário que gerou o relatório que você quer fazer o download.

    • REPORT_DETAIL_ID pelo nome do relatório de inventário que você quer fazer o download.

Download de fragmentos de relatório

Para fazer o download de um relatório de inventário que foi dividido em um ou mais fragmentos, conclua as seguintes etapas:

  1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

    Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

  2. Para fazer o download do arquivo de manifesto do relatório de inventário, use cURL para chamar a API JSON com uma solicitação de objeto GET:

    curl -X GET \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/MANIFEST_FILE_NAME?alt=media" \

    Substitua:

    • BUCKET_NAME pelo nome do bucket de destino.

    • MANIFEST_FILE_NAME pelo nome do arquivo de manifesto no bucket de destino, com a seguinte convenção de nomenclatura:

      REPORT_CONFIG_UUID_TARGET_DATETIME_manifest.json

      Em que:

      • REPORT_CONFIG_UUID é o UUID gerado automaticamente da configuração de relatório de inventário que gerou os fragmentos de relatório de que você quer fazer o download.

      • TARGET_DATETIME é a data em que o relatório de inventário foi gerado.

    Por exemplo, fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json.

    O campo report_shards_file_names do arquivo de manifesto contém os nomes dos fragmentos do relatório de inventário sujeitos a download.

  3. Para fazer o download dos arquivos de fragmento do relatório de inventário, use curl para chamar a API Cloud Storage JSON com uma solicitação do objeto Get:

    curl -X GET \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  -o "DOWNLOAD_PATH" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/SHARD_FILE_NAME?alt=media"

    Substitua:

    • DOWNLOAD_PATH pelo caminho para o sistema de arquivos local em que você quer salvar o objeto. Por exemplo, Desktop/dog.png.

    • BUCKET_NAME pelo nome do bucket de destino que contém o relatório de inventário. Por exemplo, my-bucket.

    • SHARD_FILE_NAME pelo nome codificado por URL do arquivo de fragmento de que você quer fazer o download. Por exemplo, fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:54_0.csv.

Excluir uma configuração de relatório de inventário

Console

Para excluir a configuração de um relatório de inventário, siga estas etapas:

  1. No console do Google Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket de origem que contém a configuração do relatório de inventário que você quer excluir.

  3. Na página Detalhes do bucket do bucket de origem, clique na guia Relatórios de inventário.

  4. Clique no nome da configuração do relatório de inventário que você quer excluir.

  5. Na página Detalhes de configuração do relatório exibida, clique em Excluir .

Linha de comando

Para excluir uma configuração de relatório de inventário, use o comando gcloud storage insights inventory-reports delete:

gcloud storage insights inventory-reports delete CONFIG_NAME
  --force

Substitua CONFIG_NAME pelo nome exclusivo da configuração do relatório de inventário, no formato projects/PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID.

A sinalização --force exclui os metadados de todos os relatórios de inventário gerados pela configuração de relatório de inventário especificada. Os objetos de relatório de inventário em si não serão excluídos.

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import com.google.cloud.storageinsights.v1.ReportConfigName;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import java.io.IOException;

public class DeleteInventoryReportConfig {


  public static void deleteInventoryReportConfig(
      String projectId, String location, String inventoryReportConfigUuid) throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfigName name = ReportConfigName.of(projectId, location, inventoryReportConfigUuid);
      storageInsightsClient.deleteReportConfig(name);

      System.out.println("Deleted inventory report config with name " + name);
    }
  }
}

APIs REST

API JSON

Para excluir a configuração de um relatório de inventário, siga estas etapas:

  1. Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho Authorization.

    Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho Authorization.

  2. Para excluir uma configuração de relatório de inventário, use cURL para chamar a API JSON com uma solicitação Delete ReportConfig:

    curl --request DELETE \
'https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID?force=true' \
  --header 'Authorization: Bearer $(gcloud auth print-access-token)' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \

    Substitua:

    • YOUR_PROJECT pelo nome do projeto em que os buckets de origem e de destino residem.

    • LOCATION pelo local dos buckets de origem e de destino. Por exemplo, us-west1.

    • REPORT_CONFIG_UUID pelo UUID gerado automaticamente da configuração de relatório de inventário que você quer excluir.

O parâmetro de consulta force exclui os metadados de todos os relatórios de inventário gerados pela configuração de relatório de inventário especificada. Os objetos de relatório de inventário em si não serão excluídos.

Avançado: gerar relatórios de inventário em um formato particionado do Hive

Ao criar uma configuração de relatório de inventário, é possível especificar um caminho de destino, que é um local no bucket de destino em que os relatórios de inventário serão gerados. Isso permite que você gere relatórios de inventário em um formato Hive particionado.

Especifique um caminho de destino usando palavras-chave de marcador de posição. As palavras-chave no caminho de destino são substituídas pelos valores correspondentes quando o relatório de inventário é gerado. Por exemplo, o caminho de destino config={{report-config-id}}/date={{date}} pode ser resolvido para config=1A34-F2E456-12B456-1C3D/date=2022-05-20.

Palavras-chave do caminho de destino

É possível especificar as palavras-chave report-config-id, date ou datetime entre {{ e }}, em que:

  • report-config-id é o UUID da configuração de relatório de inventário.

  • date é a data em que o relatório de inventário é gerado. Segue o formato ISO 8601.

  • datetime é a data e a hora em que o relatório de inventário é gerado. Segue o formato ISO 8601.

As palavras-chave podem ser especificadas usando qualquer uma das seguintes ferramentas:

  • Ao usar o console do Google Cloud, especifique as palavras-chave na seção Inserir caminho do destino (opcional). Essa seção aparece quando você cria uma configuração de relatório de inventário.

  • Ao usar a CLI do Google Cloud, especifique palavras-chave de marcador de posição usando a flag --destination.

  • Ao usar a API JSON, especifique as palavras-chave de marcador de posição no campo storage_destination_options.destination_path do objeto ReportConfig.

Controle de acesso e segurança

As recomendações e considerações a seguir estão relacionadas à segurança e ao uso de relatórios de inventário e configurações:

  • Recomendamos que os usuários com o papel roles/storage.admin também tenham as permissões storageinsights.reportConfigs.* para que possam manter o controle sobre o uso de todos os recursos nos seus buckets, como a leitura de objetos e seus metadados.

  • Recomendamos que você limite o acesso aos recursos do relatório de inventário concedendo as permissões storageinsights.reportConfigs.* apenas aos indivíduos necessários.

  • Depois que uma configuração de relatório de inventário é criada, ela continua a gerar relatórios de inventário, mesmo que o usuário que criou a configuração não tenha mais as permissões necessárias. Para deixar de gerar relatórios de inventário, edite a data de término na configuração do relatório de inventário ou exclua a configuração completamente.

A seguir

  • Se você tiver problemas com a geração de relatórios de inventário, consulte a Solução de problemas para receber ajuda.