Configurer les ensembles de données Storage Insights

Ce document vous explique comment configurer les ensembles de données Storage Insights.

Avant de commencer

Avant de configurer un ensemble de données, procédez comme suit.

Obtenir les rôles requis

Pour obtenir les autorisations nécessaires pour configurer les ensembles de données, demandez à votre administrateur de vous accorder les rôles IAM suivants sur vos projets sources :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour configurer les ensembles de données. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour configurer les ensembles de données :

  • Configurer un ensemble de données :
    • storageinsights.datasetConfigs.create
    • storage.buckets.getObjectInsights
  • Lien vers l'ensemble de données BigQuery : storageinsights.datasetConfigs.linkDataset

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer l'API Storage Insights

Console

Activer l'API storageinsights.googleapis.com

Ligne de commande

Pour activer l'API Storage Insights dans votre projet actuel, exécutez la commande gcloud services enable :

gcloud services enable storageinsights.googleapis.com

Pour en savoir plus sur l'activation des services pour un projet Google Cloud , consultez Activer et désactiver des services.

Configurer Storage Intelligence

Assurez-vous que Storage Intelligence est configuré pour le projet, le dossier ou l'organisation que vous souhaitez analyser avec des ensembles de données.

Créer une configuration d'ensemble de données

Pour créer une configuration d'ensemble de données, procédez comme suit. Pour en savoir plus sur les champs que vous pouvez spécifier pour la configuration de l'ensemble de données, consultez Propriétés de configuration des ensembles de données.

Console

  1. Dans la console Google Cloud , accédez à la page Storage Insights de Cloud Storage.

    Accéder à Storage Insights

  2. Cliquez sur Configurer l'ensemble de données.

  3. Dans la section Nommer l'ensemble de données, saisissez le nom de votre ensemble de données. Si vous le souhaitez, saisissez une description de l'ensemble de données. Les noms identifient les configurations d'ensembles de données et sont immuables. Le nom peut comporter jusqu'à 128 caractères (lettres, chiffres et traits de soulignement compris) et doit commencer par une lettre.

  4. Dans la section Définir le champ d'application de l'ensemble de données, procédez comme suit :

    • Sélectionnez l'une des options suivantes :

      • Pour obtenir les métadonnées de stockage de tous les projets de l'organisation actuelle, sélectionnez Inclure l'organisation.

      • Pour obtenir les métadonnées de stockage de tous les projets des dossiers sélectionnés, cochez Inclure les dossiers (sous-organisations/services). Pour savoir comment obtenir des ID de dossiers, consultez Afficher ou répertorier des dossiers et des projets. Pour ajouter des dossiers :

        1. Dans le champ Dossier 1, saisissez l'ID du dossier.
        2. Pour ajouter plusieurs ID de dossier (facultatif), cliquez sur + Ajouter un autre dossier.
      • Pour obtenir les métadonnées de stockage des projets sélectionnés, sélectionnez Inclure des projets en fournissant leurs numéros. Pour savoir comment trouver les numéros de projet, consultez Trouver le nom, le numéro et l'ID du projet. Pour ajouter des projets, procédez comme suit :

        1. Dans le champ Projet 1, saisissez le numéro du projet.
        2. Pour ajouter plusieurs numéros de projet (facultatif), cliquez sur + Ajouter un autre projet.
      • Pour ajouter des projets ou des dossiers de manière groupée, sélectionnez Importer une liste de projets/dossiers via un fichier CSV. Le fichier CSV doit contenir les numéros de projets ou les ID de dossiers à inclure dans l'ensemble de données. Vous pouvez spécifier jusqu'à 10 000 projets ou dossiers dans une configuration d'ensemble de données.

    • Indiquez si vous souhaitez inclure automatiquement les futurs buckets dans la ressource sélectionnée.

    • Si vous le souhaitez, vous pouvez spécifier des filtres sur les buckets en fonction des régions et des préfixes de buckets. Pour ce faire, développez la section Filtres (facultatif). Les filtres sont appliqués de manière additive aux buckets.

      Vous pouvez inclure ou exclure des buckets de régions spécifiques. Par exemple, vous pouvez exclure les buckets des régions me-central1 et me-central2. Vous pouvez également inclure ou exclure des buckets par préfixe. Par exemple, pour exclure les buckets commençant par my-bucket, saisissez le préfixe my-bucket*.

  5. Cliquez sur Continuer.

  6. Dans la section Sélectionner une période de conservation, sélectionnez une période de conservation pour les données de l'ensemble de données.

  7. Les données d'activité sont incluses dans l'ensemble de données par défaut et héritent de la durée de conservation de l'ensemble de données. Pour remplacer la durée de conservation de l'ensemble de données, sélectionnez Spécifier une durée de conservation pour les données d'activité, puis indiquez le nombre de jours pendant lesquels conserver les données d'activité. Pour désactiver les données d'activité, définissez la période de conservation sur 0 jours.

  8. Dans la section Sélectionner l'emplacement où stocker l'ensemble de données configuré, sélectionnez un emplacement pour stocker l'ensemble de données. Exemple : us-central1.

  9. Dans la section Sélectionner un type de compte de service, sélectionnez un type d'agent de service pour votre ensemble de données. Choisissez un agent de service à l'échelle de la configuration ou à l'échelle du projet pour votre ensemble de données.

  10. Cliquez sur Configurer.

Ligne de commande

  1. Pour créer une configuration d'ensemble de données, exécutez la commande gcloud storage insights dataset-configs create avec les indicateurs requis :

    gcloud storage insights dataset-configs create DATASET_CONFIG_ID \
      --location=LOCATION \
      --organization=SOURCE_ORG_NUMBER \
      --retention-period-days=DATASET_RETENTION_PERIOD_DAYS \
      (SCOPE_FLAG)
    

    Remplacez :

    • DATASET_CONFIG_ID par le nom de la configuration de votre ensemble de données. Les noms identifient les configurations d'ensembles de données et sont immuables. Le nom peut comporter jusqu'à 128 caractères (lettres, chiffres et traits de soulignement compris) et doit commencer par une lettre.

    • LOCATION avec l'emplacement où stocker l'ensemble de données. Exemple : us-central1.

    • SOURCE_ORG_NUMBER par l'ID de l'organisation à laquelle appartiennent les projets sources. Pour trouver l'ID de votre organisation, consultez Obtenir l'ID de ressource de votre organisation.

    • DATASET_RETENTION_PERIOD_DAYS avec la période de conservation des données de l'ensemble de données.

    • SCOPE_FLAG avec l'un des indicateurs suivants qui définit le champ d'application des données à collecter :

      • --enable-organization-scope : permet à l'ensemble de données de collecter des insights à partir de tous les buckets de l'organisation.
      • --source-folders=[SOURCE_FOLDER_NUMBERS,...] : spécifie une liste de numéros de dossiers à inclure dans l'ensemble de données. Pour savoir comment trouver un numéro de dossier, consultez Lister tous les projets et dossiers de votre hiérarchie.
      • --source-folders-file=FILE_PATH : Spécifie plusieurs numéros de dossier en important un fichier CSV dans un bucket.
      • --source-projects=[SOURCE_PROJECT_NUMBERS,...] : spécifie une liste de numéros de projet à inclure dans l'ensemble de données. Exemple :464036093014 Pour trouver votre numéro de projet, consultez Trouver le nom, le numéro et l'ID du projet.
      • --source-projects-file=FILE_PATH : Spécifie plusieurs numéros de projet en important un fichier CSV dans un bucket.

    Vous pouvez également utiliser les options supplémentaires suivantes pour configurer l'ensemble de données :

    • Utilisez --include-buckets=BUCKET_NAMES_OR_REGEX pour inclure des buckets spécifiques par nom ou expression régulière. Vous ne pouvez pas utiliser cette option avec --exclude-buckets.

    • Utilisez --exclude-buckets=BUCKET_NAMES_OR_REGEX pour exclure des buckets spécifiques par nom ou expression régulière. Vous ne pouvez pas utiliser cette option avec --include-buckets.

    • Utilisez --project=DESTINATION_PROJECT_ID pour spécifier un projet dans lequel stocker la configuration de votre ensemble de données et l'ensemble de données généré. Si vous n'utilisez pas ce flag, le projet de destination est votre projet actif. Pour en savoir plus sur les ID de projet, consultez Créer et gérer des projets.

    • Utilisez --auto-add-new-buckets pour inclure automatiquement les buckets ajoutés aux projets sources à l'avenir.

    • Utilisez --skip-verification pour ignorer les vérifications et les échecs du processus de validation, y compris les vérifications des autorisations IAM requises. Si vous utilisez cet indicateur, il est possible que certains ou tous les buckets soient exclus de l'ensemble de données.

    • Utilisez --identity=IDENTITY_TYPE pour spécifier le champ d'application de l'agent de service créé avec la configuration de l'ensemble de données. Les valeurs sont : IDENTITY_TYPE_PER_CONFIG ou IDENTITY_TYPE_PER_PROJECT. Si non spécifié, la valeur par défaut est IDENTITY_TYPE_PER_CONFIG. Pour en savoir plus, consultez Type d'agent de service.

    • Utilisez --description=DESCRIPTION pour ajouter une description à la configuration de l'ensemble de données.

    • Utilisez --activity-data-retention-period-days=ACTIVITY_RETENTION_PERIOD_DAYS pour spécifier la durée de conservation des données d'activité dans l'ensemble de données. Par défaut, les données d'activité sont incluses dans l'ensemble de données et héritent de la durée de conservation de l'ensemble de données. Pour remplacer la durée de conservation de l'ensemble de données, spécifiez le nombre de jours pendant lesquels conserver les données d'activité. Pour exclure les données d'activité, définissez ACTIVITY_RETENTION_PERIOD_DAYS sur 0.

    L'exemple suivant crée une configuration d'ensemble de données nommée my-dataset dans la région us-central1, pour l'organisation dont l'ID est 123456789, avec une période de conservation de 30 jours et un champ d'application limité aux projets 987654321 et 123123123 :

    gcloud storage insights dataset-configs create my-dataset \
    --location=us-central1 \
    --organization=123456789 \
    --retention-period-days=30 \
    --source-projects=987654321,123123123
    

API JSON

  1. Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

  2. Créez un fichier JSON contenant les informations suivantes :

    {
      "sourceProjects": {
        "project_numbers": ["PROJECT_NUMBERS", ...]
      },
      "retentionPeriodDays": "RETENTION_PERIOD_DAYS",
      "activityDataRetentionPeriodDays": "ACTIVITY_DATA_RETENTION_PERIOD_DAYS",
      "identity": {
        "type": "IDENTITY_TYPE"
      }
    }

    Remplacez :

    • PROJECT_NUMBERS numéros des projets que vous souhaitez inclure dans l'ensemble de données. Vous pouvez spécifier un ou plusieurs projets. Les projets doivent être spécifiés sous forme de liste de chaînes.

      Vous pouvez également ajouter une organisation, ou un ou plusieurs dossiers contenant les buckets et les objets dont vous souhaitez modifier les métadonnées. Pour inclure des dossiers ou des organisations, utilisez les champs sourceFolders ou organizationScope. Pour en savoir plus, consultez la documentation de référence sur DatasetConfig.

    • RETENTION_PERIOD_DAYS avec le nombre de jours de données à capturer dans l'instantané de l'ensemble de données. Exemple : 90.

    • ACTIVITY_DATA_RETENTION_PERIOD_DAYS avec le nombre de jours de données d'activité à capturer dans l'instantané de l'ensemble de données. Par défaut, les données d'activité sont incluses dans l'ensemble de données et héritent de sa durée de conservation. Pour remplacer la durée de conservation de l'ensemble de données, spécifiez le nombre de jours pendant lesquels conserver les données d'activité. Pour exclure les données d'activité, définissez ACTIVITY_RETENTION_PERIOD_DAYS sur 0.

    • IDENTITY_TYPE avec le type de compte de service créé en même temps que la configuration de l'ensemble de données. Les valeurs sont : IDENTITY_TYPE_PER_CONFIG ou IDENTITY_TYPE_PER_PROJECT. Pour en savoir plus, consultez Type d'agent de service.

  3. Pour créer la configuration de l'ensemble de données, utilisez cURL pour appeler l'API JSON avec une requête Create DatasetConfig :

    curl -X POST --data-binary @JSON_FILE_NAME \
    "https://storageinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasetConfigs?datasetConfigId=DATASET_CONFIG_ID" \
      --header "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT)" \
      --header "Accept: application/json" \
      --header "Content-Type: application/json"

    Remplacez :

    • JSON_FILE_NAME par le chemin d'accès au fichier JSON que vous avez créé à l'étape précédente. Vous pouvez également transmettre une instance de DatasetConfig dans le corps de la requête.

    • PROJECT_ID avec l'ID du projet auquel appartiendront la configuration et l'ensemble de données.

    • LOCATION avec l'emplacement où résideront l'ensemble de données et sa configuration. Exemple : us-central1.

    • DATASET_CONFIG_ID par le nom de la configuration de votre ensemble de données. Les noms identifient les configurations d'ensembles de données et sont immuables. Le nom peut comporter jusqu'à 128 caractères (lettres, chiffres et traits de soulignement compris) et doit commencer par une lettre.

    • SERVICE_ACCOUNT par le compte de service. Exemple :test-service-account@test-project.iam.gserviceaccount.com

Pour résoudre les erreurs de traitement des instantanés enregistrées dans error_attributes_view, consultez Erreurs liées à l'ensemble de données Storage Insights.

Accorder les autorisations requises à l'agent de service

Google Cloud crée un agent de service à l'échelle de la configuration ou du projet lorsque vous créez une configuration d'ensemble de données. L'agent de service respecte le format de nom service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com et apparaît sur la page IAM de la console Google Cloud lorsque vous sélectionnez la case Inclure les attributions de rôles fournies par Google. Vous pouvez également trouver le nom de l'agent de service en affichant la ressource DatasetConfig à l'aide de l'API JSON.

Pour permettre à Storage Insights de générer et d'écrire des ensembles de données, demandez à votre administrateur d'attribuer le rôle Storage Insights Collector Service (roles/storage.insightsCollectorService) à l'agent de service dans l'organisation contenant les projets sources. Vous devez attribuer ce rôle à chaque agent de service à l'échelle de la configuration créé pour chaque configuration d'ensemble de données à partir de laquelle vous souhaitez obtenir des données. Si vous utilisez un agent de service à l'échelle du projet, vous devez attribuer ce rôle une seule fois à l'agent de service pour qu'il puisse lire et écrire des ensembles de données pour toutes les configurations d'ensembles de données du projet.

Pour savoir comment attribuer des rôles aux projets, consultez Gérer l'accès.

Pour associer un ensemble de données à BigQuery, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Storage Insights de Cloud Storage.

    Accéder à Storage Insights

  2. Cliquez sur le nom de la configuration de l'ensemble de données qui a généré l'ensemble de données que vous souhaitez associer.

  3. Dans la section Ensemble de données associé à BigQuery, cliquez sur Associer l'ensemble de données pour associer votre ensemble de données.

  1. Pour associer un ensemble de données à BigQuery, exécutez la commande gcloud storage insights dataset-configs create-link :

    gcloud storage insights dataset-configs create-link DATASET_CONFIG_ID --location=LOCATION

    Remplacez :

    • DATASET_CONFIG_ID par le nom de la configuration de l'ensemble de données qui a généré l'ensemble de données à associer.

    • LOCATION avec l'emplacement de votre ensemble de données. Par exemple, us-central1.

    Vous pouvez également spécifier un chemin d'accès complet à la configuration de l'ensemble de données. Exemple :

    gcloud storage insights dataset-configs create-link projects/DESTINATION_PROJECT_ID/locations/LOCATION/datasetConfigs/DATASET_CONFIG_ID

    Remplacez :

    • DESTINATION_PROJECT_ID par l'ID du projet contenant la configuration de l'ensemble de données. Pour en savoir plus sur les ID de projet, consultez Créer et gérer des projets.

    • DATASET_CONFIG_ID par le nom de la configuration de l'ensemble de données qui a généré l'ensemble de données à associer.

    • LOCATION par l'emplacement de votre ensemble de données et de sa configuration. Par exemple, us-central1.

  1. Vous devez installer et initialiser la gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

  2. Utilisez cURL pour appeler l'API JSON avec une requête linkDataset DatasetConfig :

    curl -X POST \
      "https://storageinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasetConfigsDATASET_CONFIG_ID:linkDataset?" \
        --header "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT)" \
        --header "Accept: application/json" \
        --header "Content-Type: application/json"
    

    Remplacez :

    • JSON_FILE_NAME par le chemin d'accès au fichier JSON que vous avez créé.

    • PROJECT_ID par l'ID du projet auquel appartient la configuration de l'ensemble de données.

    • LOCATION avec l'emplacement où résident l'ensemble de données et la configuration de l'ensemble de données. Exemple : us-central1.

    • DATASET_CONFIG_ID avec le nom de la configuration de l'ensemble de données qui a généré l'ensemble de données à associer.

    • SERVICE_ACCOUNT par le compte de service. Exemple :test-service-account@test-project.iam.gserviceaccount.com

Analyser les données et les métadonnées des objets à l'aide de BigQuery

Pour analyser le contenu d'un objet ou afficher ses métadonnées, utilisez la colonne ref, qui est renvoyée dans un ensemble de données Storage Insights, pour exécuter les fonctions ObjectRef de BigQuery. Suivez la procédure décrite dans les sections ci-dessous.

Créer une connexion à une ressource cloud dans BigQuery

Dans BigQuery, créez une connexion à une ressource cloud qui accède à Cloud Storage. La connexion aux ressources Cloud permet à BigQuery d'accéder aux données et aux métadonnées des objets Cloud Storage à l'aide de son propre compte de service. Pour en savoir plus, consultez Créer une connexion de ressource Cloud.

Utiliser la connexion à une ressource cloud avec l'ensemble de données Storage Insights

Pour analyser les données référencées dans la colonne ref qui sont renvoyées dans un ensemble de données Storage Insights, utilisez la fonction OBJ.MAKE_REF pour combiner le URI de la colonne ref avec la connexion que vous avez créée :

SELECT
OBJ.GET_ACCESS_URL(OBJ.MAKE_REF(ref.uri, "CONNECTION_ID"), "r")
FROM `PROJECT_ID.INSIGHTS_DATASET.object_attributes_view` WHERE LOCATION = "US";

Remplacez :

  • CONNECTION_ID : ID de la connexion de ressource Cloud que vous avez créée.
  • PROJECT_ID : ID du projet contenant l'ensemble de données Storage Insights.
  • INSIGHTS_DATASET : nom de l'ensemble de données Storage Insights. Exemple :storageinsights_dataset

Analyser un ensemble de données Storage Insights à l'aide d'un modèle personnalisé

BigQuery ne permet pas de créer des modèles directement dans un ensemble de données associé. Pour analyser vos données Storage Insights avec un modèle personnalisé, vous devez créer et stocker le modèle dans un ensemble de données BigQuery standard. Vous pouvez ensuite faire référence à ce modèle dans vos requêtes tout en ciblant l'ensemble de données associé pour l'analyse :

  1. Créez un modèle dans un ensemble de données BigQuery (MODEL_DATASET) dans le même projet que votre ensemble de données associé (INSIGHTS_DATASET) :

    CREATE OR REPLACE MODEL `MODEL_DATASET.gemini_model`
    REMOTE WITH CONNECTION `CONNECTION_ID`
    OPTIONS (ENDPOINT = 'gemini-2.0-flash');

    Remplacez :

    • MODEL_DATASET : nom de l'ensemble de données dans lequel vous souhaitez créer le modèle.
    • CONNECTION_ID : ID de la connexion de ressource Cloud que vous avez créée.
  2. Exécutez une requête qui fait référence au modèle pour analyser les données de votre ensemble de données Storage Insights. L'exemple suivant ajoute une description aux images de l'ensemble de données :

    SELECT
     name,
     result AS ai_description
    FROM
     AI.GENERATE_TEXT(
       MODEL `MODEL_DATASET.gemini_model`,
       (
         SELECT
           name,
           (
             'Describe this image',
             OBJ.GET_ACCESS_URL(
               OBJ.FETCH_METADATA(
                 OBJ.MAKE_REF(
                   ref.uri,
                   'CONNECTION_ID'
                 )
               ),
               'r'
             )
           ) AS prompt
         FROM
           `INSIGHTS_DATASET.object_attributes_view`
         WHERE
           contentType LIKE 'image/%'
           AND NOT name LIKE '%/'
         LIMIT 3
       )
     );

    Remplacez :

    • INSIGHTS_DATASET : nom de l'ensemble de données Storage Insights.
    • MODEL_DATASET : nom de l'ensemble de données dans lequel vous avez créé le modèle.
    • CONNECTION_ID : ID de la connexion de ressource Cloud que vous avez créée.

Analyser un ensemble de données Storage Insights à l'aide d'un modèle par défaut

Vous pouvez utiliser un modèle par défaut pour générer des insights à partir de données non structurées et détecter les informations sensibles.

Générer des insights à partir de données non structurées

L'exemple de requête suivant génère des descriptions pour les images JPEG :

SELECT AI.GENERATE(
   (
     'Return a JSON object with fields: "description" (max 20 words)',
     OBJ.GET_ACCESS_URL(
       OBJ.MAKE_REF(ref.uri, `CONNECTION_ID`),
       'r'
     )
   )
)
FROM  `PROJECT_ID.INSIGHTS_DATASET.object_attributes_view`
WHERE  name LIKE 'returns/electronics/%'
  AND contentType = 'image/jpeg';

Remplacez :

  • CONNECTION_ID : ID de la connexion de ressource Cloud que vous avez créée.
  • PROJECT_ID : ID du projet contenant l'ensemble de données Storage Insights.
  • INSIGHTS_DATASET : nom de l'ensemble de données Storage Insights.

Détection automatisée des données sensibles

Vous pouvez utiliser des modèles multimodaux pour détecter les données sensibles, telles que les informations permettant d'identifier personnellement l'utilisateur, dans vos documents.

La requête suivante montre comment analyser des documents PDF pour vérifier s'ils contiennent des informations sensibles :

SELECT AI.GENERATE(
   (
     'Does this document contain any credit card numbers or home addresses? Answer "SAFE" or "SENSITIVE".',
     OBJ.GET_ACCESS_URL(
       OBJ.MAKE_REF(ref.uri, `CONNECTION_ID`),
       'r'
     )
   )
)
FROM  `PROJECT_ID.INSIGHTS_DATASET.object_attributes_view`
WHERE contentType = 'application/pdf';

Remplacez :

  • CONNECTION_ID : ID de la connexion de ressource Cloud que vous avez créée.
  • PROJECT_ID : ID du projet contenant l'ensemble de données Storage Insights.
  • INSIGHTS_DATASET : nom de l'ensemble de données Storage Insights.

Étapes suivantes