Afficher des fichiers depuis Cloud Storage avec des entrées d'ensembles de fichiers

Vous pouvez créer et rechercher des entrées d'ensembles de fichiers Cloud Storage (appelés "ensembles de fichiers" dans la suite de ce document) à l'aide des API Data Catalog.

Ensemble de fichiers

Un ensemble de fichiers Cloud Storage est une entrée d'un groupe d'entrées créé par l'utilisateur. Pour en savoir plus, consultez la page Entrées et groupes d'entrées.

Il est défini par un ou plusieurs modèles de fichier qui spécifient un ensemble d'un ou plusieurs fichiers Cloud Storage.

Exigences concernant les modèles de fichier :

  • Un modèle de fichier doit commencer par gs://bucket_name/.
  • Le nom du bucket doit respecter les exigences concernant les noms de bucket Cloud Storage.
  • Les caractères génériques sont autorisés dans les parties des modèles de fichier concernant le dossier et le fichier, mais les caractères génériques ne sont pas autorisés dans les noms de buckets. Pour obtenir des exemples, consultez les articles suivants :
  • Un ensemble de fichiers doit comporter entre un et 500 modèles d'ensemble de fichiers.

Vous pouvez interroger des ensembles de fichiers Data Catalog avec Dataflow SQL, mais seulement s'ils comportent un schéma défini et qu'ils ne contiennent que des fichiers CSV sans ligne d'en-tête.

Créer des groupes d'entrées et des ensembles de fichiers

Les ensembles de fichiers doivent être placés dans un groupe d'entrées créé par l'utilisateur. Si vous n'avez pas créé de groupe d'entrées, commencez par en créer un, puis créez l'ensemble de fichiers au sein de ce groupe d'entrées. Vous pouvez définir des stratégies IAM sur le groupe d'entrées pour déterminer qui a accès aux ensembles de fichiers et aux autres entrées du groupe d'entrées.

Console

Console

  1. Accédez à la page Dataplex > Groupes d'entrées.

    Accéder aux groupes d'entrées Dataplex

  2. Cliquez sur Créer un groupe d'entrées.

  3. Remplissez le formulaire Create Entry Group (Créer un groupe d'entrées), puis cliquez sur CREATE (Créer).

  4. La page Détails du groupe d'entrées s'affiche. Après avoir sélectionné l'onglet ENTRIES (Entrées), cliquez sur CREATE (Créer).

  5. Remplissez le formulaire Create Fileset (Créer un ensemble de fichiers).

    1. Pour associer un schéma, cliquez sur Define Schema (Définir un schéma) pour ouvrir le formulaire correspondant. Cliquez sur + ADD FIELDS (AJOUTER DES CHAMPS) pour ajouter des champs individuellement ou activez l'option Edit as text (Modifier sous forme de texte) en haut à droite du formulaire pour les spécifier au format JSON.
    2. Cliquez sur Save (Enregistrer) pour enregistrer le schéma.
  6. Cliquez sur Create (Créer) pour créer l'ensemble de fichiers.

gcloud

gcloud

1. Créer un groupe d'entrées

Utilisez la commande gcloud data-catalog entry-groups create pour créer un groupe d'entrée auquel sont associés un schéma et une description.

Exemple :

gcloud data-catalog entry-groups create my_entrygroup \
    --location=us-central1

2. Créer un ensemble de fichiers dans le groupe d'entrées

Utilisez la commande gcloud data-catalog entries create pour créer un ensemble de fichiers dans un groupe d'entrées. L'exemple de commande gcloud ci-dessous crée une entrée d'ensemble de fichiers qui inclut un schéma de données d'ensemble de fichiers.

gcloud data-catalog entries create my_fileset_entry \  
    --location=us-central1 \  
    --entry-group=my_entrygroup \  
    --type=FILESET \  
    --gcs-file-patterns=gs://my-bucket/*.csv \  
    --schema-from-file=path_to_schema_file \  
    --description="Fileset description ..."

Notes sur les options :

  • --gcs-file-patterns : consultez la section Exigences concernant les modèles de fichier.
  • --schema-from-file: l'exemple suivant montre le format JSON du fichier texte de schéma accepté par l'option --schema-from-file.
    [
      {
        "column": "first_name",
        "description": "First name",
        "mode": "REQUIRED",
        "type": "STRING"
      },
      {
        "column": "last_name",
        "description": "Last name",
        "mode": "REQUIRED",
        "type": "STRING"
      },
      {
        "column": "address",
        "description": "Address",
        "mode": "REPEATED",
        "type": "STRING"
      }
    ]
    

Java

Avant d'essayer cet exemple, suivez les instructions de configuration de Java dans le guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Java.

Pour vous authentifier auprès de Data Catalog, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

import com.google.cloud.datacatalog.v1.ColumnSchema;
import com.google.cloud.datacatalog.v1.CreateEntryRequest;
import com.google.cloud.datacatalog.v1.DataCatalogClient;
import com.google.cloud.datacatalog.v1.Entry;
import com.google.cloud.datacatalog.v1.EntryGroupName;
import com.google.cloud.datacatalog.v1.EntryType;
import com.google.cloud.datacatalog.v1.GcsFilesetSpec;
import com.google.cloud.datacatalog.v1.Schema;
import java.io.IOException;

// Sample to create file set entry
public class CreateFilesetEntry {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String entryGroupId = "fileset_entry_group";
    String entryId = "fileset_entry_id";
    createFilesetEntry(projectId, entryGroupId, entryId);
  }

  // Create Fileset Entry.
  public static void createFilesetEntry(String projectId, String entryGroupId, String entryId)
      throws IOException {
    // Currently, Data Catalog stores metadata in the us-central1 region.
    String location = "us-central1";

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {
      // Construct the Entry for the Entry request.
      Entry entry =
          Entry.newBuilder()
              .setDisplayName("My Fileset")
              .setDescription("This fileset consists of ....")
              .setGcsFilesetSpec(
                  GcsFilesetSpec.newBuilder().addFilePatterns("gs://cloud-samples-data/*").build())
              .setSchema(
                  Schema.newBuilder()
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("first_name")
                              .setDescription("First name")
                              .setMode("REQUIRED")
                              .setType("STRING")
                              .build())
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("last_name")
                              .setDescription("Last name")
                              .setMode("REQUIRED")
                              .setType("STRING")
                              .build())
                      .addColumns(
                          ColumnSchema.newBuilder()
                              .setColumn("addresses")
                              .setDescription("Addresses")
                              .setMode("REPEATED")
                              .setType("RECORD")
                              .addSubcolumns(
                                  ColumnSchema.newBuilder()
                                      .setColumn("city")
                                      .setDescription("City")
                                      .setMode("NULLABLE")
                                      .setType("STRING")
                                      .build())
                              .addSubcolumns(
                                  ColumnSchema.newBuilder()
                                      .setColumn("state")
                                      .setDescription("State")
                                      .setMode("NULLABLE")
                                      .setType("STRING")
                                      .build())
                              .build())
                      .build())
              .setType(EntryType.FILESET)
              .build();

      // Construct the Entry request to be sent by the client.
      CreateEntryRequest entryRequest =
          CreateEntryRequest.newBuilder()
              .setParent(EntryGroupName.of(projectId, location, entryGroupId).toString())
              .setEntryId(entryId)
              .setEntry(entry)
              .build();

      // Use the client to send the API request.
      Entry entryCreated = dataCatalogClient.createEntry(entryRequest);
      System.out.printf("Entry created with name: %s", entryCreated.getName());
    }
  }
}

Node.js

Avant d'essayer cet exemple, suivez les instructions de configuration de Node.js dans le guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Node.js.

Pour vous authentifier auprès de Data Catalog, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

// Import the Google Cloud client library.
const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
const datacatalog = new DataCatalogClient();

async function createFileset() {
  // Create a fileset within an entry group.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'my_project';
  // const entryGroupId = 'my_entry_group';
  // const entryId = 'my_entry';

  // Currently, Data Catalog stores metadata in the us-central1 region.
  const location = 'us-central1';

  // Delete any pre-existing Entry with the same name that will be used
  // when creating the new Entry.
  try {
    const formattedName = datacatalog.entryPath(
      projectId,
      location,
      entryGroupId,
      entryId
    );
    await datacatalog.deleteEntry({name: formattedName});
  } catch (err) {
    console.log('Entry does not exist.');
  }

  // Delete any pre-existing Entry Group with the same name
  // that will be used to create the new Entry Group.
  try {
    const formattedName = datacatalog.entryGroupPath(
      projectId,
      location,
      entryGroupId
    );
    await datacatalog.deleteEntryGroup({name: formattedName});
  } catch (err) {
    console.log('Entry Group does not exist.');
  }

  // Construct the Entry Group for the Entry Group request.
  const entryGroup = {
    displayName: 'My Fileset Entry Group',
    description: 'This Entry Group consists of ....',
  };

  // Construct the Entry Group request to be sent by the client.
  const entryGroupRequest = {
    parent: datacatalog.locationPath(projectId, location),
    entryGroupId: entryGroupId,
    entryGroup: entryGroup,
  };

  // Use the client to send the API request.
  await datacatalog.createEntryGroup(entryGroupRequest);

  // Construct the Entry for the Entry request.
  const FILESET_TYPE = 4;

  const entry = {
    displayName: 'My Fileset',
    description: 'This fileset consists of ....',
    gcsFilesetSpec: {filePatterns: ['gs://my_bucket/*']},
    schema: {
      columns: [
        {
          column: 'city',
          description: 'City',
          mode: 'NULLABLE',
          type: 'STRING',
        },
        {
          column: 'state',
          description: 'State',
          mode: 'NULLABLE',
          type: 'STRING',
        },
        {
          column: 'addresses',
          description: 'Addresses',
          mode: 'REPEATED',
          subcolumns: [
            {
              column: 'city',
              description: 'City',
              mode: 'NULLABLE',
              type: 'STRING',
            },
            {
              column: 'state',
              description: 'State',
              mode: 'NULLABLE',
              type: 'STRING',
            },
          ],
          type: 'RECORD',
        },
      ],
    },
    type: FILESET_TYPE,
  };

  // Construct the Entry request to be sent by the client.
  const request = {
    parent: datacatalog.entryGroupPath(projectId, location, entryGroupId),
    entryId: entryId,
    entry: entry,
  };

  // Use the client to send the API request.
  const [response] = await datacatalog.createEntry(request);

  console.log(`Name: ${response.name}`);
  console.log(`Display name: ${response.displayName}`);
  console.log(`Type: ${response.type}`);
}
createFileset();

Python

Avant d'essayer cet exemple, suivez les instructions de configuration de Python dans le guide de démarrage rapide de Data Catalog à l'aide des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API Data Catalog Python.

Pour vous authentifier auprès de Data Catalog, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

# Import required modules.
from google.cloud import datacatalog_v1

# TODO: Set these values before running the sample.
project_id = "project_id"
fileset_entry_group_id = "entry_group_id"
fileset_entry_id = "entry_id"

# For all regions available, see:
# https://cloud.google.com/data-catalog/docs/concepts/regions
location = "us-central1"

datacatalog = datacatalog_v1.DataCatalogClient()

# Create an Entry Group.
entry_group_obj = datacatalog_v1.types.EntryGroup()
entry_group_obj.display_name = "My Fileset Entry Group"
entry_group_obj.description = "This Entry Group consists of ...."

entry_group = datacatalog.create_entry_group(
    parent=datacatalog_v1.DataCatalogClient.common_location_path(
        project_id, location
    ),
    entry_group_id=fileset_entry_group_id,
    entry_group=entry_group_obj,
)
print(f"Created entry group: {entry_group.name}")

# Create a Fileset Entry.
entry = datacatalog_v1.types.Entry()
entry.display_name = "My Fileset"
entry.description = "This fileset consists of ...."
entry.gcs_fileset_spec.file_patterns.append("gs://my_bucket/*.csv")
entry.type_ = datacatalog_v1.EntryType.FILESET

# Create the Schema, for example when you have a csv file.
entry.schema.columns.append(
    datacatalog_v1.types.ColumnSchema(
        column="first_name",
        description="First name",
        mode="REQUIRED",
        type_="STRING",
    )
)

entry.schema.columns.append(
    datacatalog_v1.types.ColumnSchema(
        column="last_name", description="Last name", mode="REQUIRED", type_="STRING"
    )
)

# Create the addresses parent column
addresses_column = datacatalog_v1.types.ColumnSchema(
    column="addresses", description="Addresses", mode="REPEATED", type_="RECORD"
)

# Create sub columns for the addresses parent column
addresses_column.subcolumns.append(
    datacatalog_v1.types.ColumnSchema(
        column="city", description="City", mode="NULLABLE", type_="STRING"
    )
)

addresses_column.subcolumns.append(
    datacatalog_v1.types.ColumnSchema(
        column="state", description="State", mode="NULLABLE", type_="STRING"
    )
)

entry.schema.columns.append(addresses_column)

entry = datacatalog.create_entry(
    parent=entry_group.name, entry_id=fileset_entry_id, entry=entry
)
print(f"Created fileset entry: {entry.name}")

API REST et ligne de commande

REST

Si vous n'avez pas accès aux bibliothèques clientes Cloud pour votre langage ou si vous souhaitez tester l'API à l'aide de requêtes REST, consultez les exemples suivants et reportez-vous aux API REST Data Catalog entryGroups.create et entryGroups.entries.create.

1. Créer un groupe d'entrées

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

  • project-id : ID de votre projet Google Cloud.
  • entryGroupId : l'ID doit commencer par une lettre ou un trait de soulignement, ne contenir que des lettres de l'alphabet latin, des chiffres et des traits de soulignement, et ne doit pas dépasser 64 caractères.
  • displayName : nom textuel du groupe d'entrées.

Méthode HTTP et URL :

POST https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId

Corps JSON de la requête :

{
  "displayName": "Entry Group display name"
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "name": "projects/my_projectid/locations/us-central1/entryGroups/my_entry_group",
  "displayName": "Entry Group display name",
  "dataCatalogTimestamps": {
    "createTime": "2019-10-19T16:35:50.135Z",
    "updateTime": "2019-10-19T16:35:50.135Z"
  }
}

2. Créer un ensemble de fichiers dans le groupe d'entrées

Avant d'utiliser les données de requête, effectuez les remplacements suivants:

  • project_id : ID de votre projet Google Cloud.
  • entryGroupId : ID du groupe d'entrées existant. L'ensemble de fichiers sera créé dans ce groupe d'entrées.
  • entryId : ID d'entrée du nouvel ensemble de fichiers. L'ID doit commencer par une lettre ou un trait de soulignement, ne doit contenir que des lettres en alphabet latin, des chiffres et des traits de soulignement, et ne doit pas contenir plus de 64 caractères.
  • description : description de l'ensemble de fichiers.
  • displayName : nom textuel de l'entrée d'ensemble de fichiers.
  • filePatterns : doit commencer par "gs://bucket_name/". Consultez la section Exigences concernant les modèles de fichier.
  • schema : schéma de l'ensemble de fichiers.

    Exemple de schéma JSON:
    { ...
      "schema": {
        "columns": [
          {
            "column": "first_name",
            "description": "First name",
            "mode": "REQUIRED",
            "type": "STRING"
          },
          {
            "column": "last_name",
            "description": "Last name",
            "mode": "REQUIRED",
            "type": "STRING"
          },
          {
            "column": "address",
            "description": "Address",
            "mode": "REPEATED",
            "subcolumns": [
              {
                "column": "city",
                "description": "City",
                "mode": "NULLABLE",
                "type": "STRING"
              },
              {
                "column": "state",
                "description": "State",
                "mode": "NULLABLE",
                "type": "STRING"
              }
            ],
            "type": "RECORD"
          }
        ]
      }
    ...
    }
    

Méthode HTTP et URL :

POST https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId

Corps JSON de la requête :

{
  "description": "Fileset description.",
  "displayName": "Display name",
  "gcsFilesetSpec": {
    "filePatterns": [
      "gs://bucket_name/file_pattern"
    ]
  },
  "type": "FILESET",
  "schema": { schema }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "name": "projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id",
  "type": "FILESET",
  "displayName": "My Fileset",
  "description": "My Fileset description.",
  "schema": {
    "columns": [
      {
        "type": "STRING",
        "description": "First name",
        "mode": "REQUIRED",
        "column": "first_name"
      },
      {
        "type": "STRING",
        "description": "Last name",
        "mode": "REQUIRED",
        "column": "last_name"
      },
      {
        "type": "RECORD",
        "description": "Address",
        "mode": "REPEATED",
        "column": "address",
        "subcolumns": [
          {
            "type": "STRING",
            "description": "City",
            "mode": "NULLABLE",
            "column": "city"
          },
          {
            "type": "STRING",
            "description": "State",
            "mode": "NULLABLE",
            "column": "state"
          }
        ]
      }
    ]
  },
  "gcsFilesetSpec": {
    "filePatterns": [
      "gs://my_bucket_name/chicago_taxi_trips/csv/shard-*.csv"
    ]
  },
  "sourceSystemTimestamps": {
    "createTime": "2019-10-23T23:11:26.326Z",
    "updateTime": "2019-10-23T23:11:26.326Z"
  },
"linkedResource": "//datacatalog.googleapis.com/projects/my_project_id/locations/us-central1/entryGroups/my_entryGroup_id/entries/my_entry_id"
}

Rôles, autorisations et stratégies IAM

Data Catalog définit les rôles d'entrée et de groupe d'entrée pour faciliter la gestion des autorisations des ensembles de fichiers et des autres ressources Data Catalog.

Rôles d'entrée Description
dataCatalog.entryOwner Propriétaire d'une entrée ou d'un groupe d'entrées spécifique.
  • Autorisations :
    • datacatalog.entries.(*)
    • datacatalog.entryGroups.get
  • Applicabilité :
    • Organisation, projet et groupe d'entrées.
dataCatalog.entryViewer Peut consulter les détails de l'entrée et du groupe d'entrées.
  • Autorisations
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • Applicabilité :
    • Organisation, projet et groupe d'entrées.
Rôles de groupe d'entrées Description
dataCatalog.entryGroupOwner Propriétaire d'un groupe d'entrées particulier.
  • Autorisations :
    • datacatalog.entryGroups.(*)
    • datacatalog entries.(*)
  • Applicabilité :
    • Au niveau de l'organisation, du projet et du groupe d'entrées.
dataCatalog.entryGroupCreator Peut créer des groupes d'entrées dans un projet. Le créateur d'un groupe d'entrées reçoit automatiquement le rôle dataCatalog.entryGroupOwner.
  • Autorisations
    • datacatalog.entryGroups.(get | create)
  • Applicabilité :
    • Au niveau de l'organisation et du projet.

Définir des stratégies IAM

Les utilisateurs disposant de l'autorisation datacatalog.<resource>.setIamPolicy peuvent définir des stratégies IAM sur des groupes d'entrées Data Catalog et d'autres ressources Data Catalog (consultez la section Rôles Data Catalog).

gcloud

Console

Accédez à la page Détails du groupe d'entrées dans l'UI de Data Catalog, puis utilisez le panneau IAM situé à droite pour accorder ou révoquer des autorisations.

Attribuer des rôles de groupe d'entrées

Exemple 1 :

Une entreprise dont les ensembles de fichiers ont des contextes commerciaux différents crée des groupes d'entrées order-files et user-files distincts :

Le groupe "order-files" contient des buckets de stockage contenant des fichiers d'ordre annulé et terminé, tandis que le groupe "user-files" contient un bucket de stockage contenant des fichiers d'informations permettant d'identifier personnellement l'utilisateur.
Figure 1. Exemple de stockage des données de commande et utilisateur dans différents groupes d'entrées.

L'entreprise attribue aux utilisateurs le rôle Lecteur de groupes d'entrées pour order-files, ce qui signifie qu'ils ne peuvent rechercher que les entrées contenues dans ce groupe d'entrées. Leurs résultats de recherche ne renvoient pas d'entrées dans le groupe d'entrées user-files.

Exemple 2 :

Une entreprise attribue le rôle Lecteur de groupes d'entrées à un utilisateur dans le projet project_entry_group seulement. L'utilisateur ne pourra afficher que les entrées de ce projet.

Effectuer des recherches dans des ensembles de fichiers

Les utilisateurs peuvent restreindre la portée de la recherche dans Data Catalog à l'aide de l'attribut type. type=entry_group limite la requête de recherche aux groupes d'entrées tandis que type=fileset ne recherche que les ensembles de fichiers. Les attributs type peuvent être utilisés conjointement avec d'autres attributs, tels que projectid.

gcloud

  • Recherchez des groupes d'entrées dans un projet:

    gcloud data-catalog search \  
        --include-project-ids=my-project
        "projectid=my-project type=entry_group"
    

  • Recherchez tous les groupes d'entrées auxquels vous avez accès:

    gcloud data-catalog search \  
        --include-project-ids=my-project
        "type=entry_group"
    

  • Recherchez des ensembles de fichiers dans un projet:

    gcloud data-catalog search \  
        --include-project-ids=my-project
        "type=entry.fileset"
    

  • Rechercher des ensembles de fichiers dans un projet. Syntaxe simplifiée:

    gcloud data-catalog search \  
        --include-project-ids=my-project
        "type=fileset"