Supervisa los archivos de Cloud Storage con entradas de conjuntos de archivos

Puedes usar la API de Data Catalog para crear y buscar entradas de conjuntos de archivos de Cloud Storage (denominados conjuntos de archivos en este documento).

Conjuntos de archivos

Un conjunto de archivos de Cloud Storage es una entrada dentro de un grupo de entradas creado por el usuario. Para obtener más información, consulta Entradas y grupos de entradas.

Se define mediante uno o más patrones de archivo que especifican un conjunto de uno o más archivos de Cloud Storage.

Requisitos del patrón de archivo:

  • Un patrón de archivo debe comenzar con gs://bucket_name/.
  • El nombre del depósito debe seguir los requisitos del nombre del depósito de Cloud Storage.
  • Los comodines se permiten en las partes de la carpeta y del archivo de los patrones de archivo, pero no se permiten comodines en los nombres de depósitos. Por ejemplo, consulta:
  • Un conjunto de archivos debe tener uno y no puede tener más de 5 patrones de conjuntos de archivos.

Puedes consultar conjuntos de archivos de Data Catalog con Dataflow SQL, pero solo si tienen un esquema definido y solo contienen archivos CSV sin filas de encabezado.

Crea grupos de entrada y conjuntos de archivos

Los conjuntos de archivos deben colocarse dentro del grupo de entrada creado por el usuario. Si no creaste un grupo de entrada, primero crea uno y, luego, crea el conjunto de archivos dentro del grupo de entrada. Puedes establecer políticas de IAM en el grupo de entrada para definir quién tiene acceso a los conjuntos de archivos y otras entradas dentro del grupo de entrada.

Console

Console

  1. Ve a la página Dataplex > Grupos de entradas.

    Ir a Grupos de entradas de Dataplex

  2. Haz clic en Crear grupo de entrada.

  3. Completa el formulario Crear grupo de entrada (Create Entry Group) y haz clic en CREAR (CREATE).

  4. Se abrirá la página Detalles del grupo de entrada (Entry group details). Con la pestaña ENTRADAS seleccionada, haz clic en CREAR.

  5. Completa el formulario Crear conjunto de archivos (Create Fileset).

    1. Para adjuntar un esquema, haz clic en Definir esquema (Define Schema) a fin de abrir el formulario correspondiente. Haz clic en + ADD FIELDS a fin de agregar campos de forma individual o selecciona Editar como texto (Edit as text) en la esquina superior derecha del formulario para especificar los campos en formato JSON.
    2. Haz clic en Guardar (Save) para guardar el esquema.

  6. Haz clic en Crear (Create) para crear el conjunto de archivos.

gcloud

gcloud

1. Crea un grupo de entrada

Usa el comando gcloud data-catalog entry-groups create para crear un grupo de entradas con un esquema y una descripción adjuntos.

Ejemplo:

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

2. Crea un conjunto de archivos dentro del grupo de entrada

Usa el comando gcloud data-catalog entries create para crear un conjunto de archivos dentro de un grupo de entradas. Este ejemplo de comando de Google Cloud CLI, a continuación, crea una entrada de conjunto de archivos que incluye el esquema de datos.

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

Notas de las marcas:

  • --gcs-file-patterns: Consulta los Requisitos del patrón de archivos.
  • --schema-from-file: En el siguiente ejemplo, se muestra el formato JSON del archivo de texto del esquema que acepta la marca --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

Antes de probar esta muestra, sigue las instrucciones de configuración para Java que se encuentran en la Guía de inicio rápido de Data Catalog sobre el uso de bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Java de Data Catalog.

Para autenticarte en Data Catalog, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de Data Catalog sobre el uso de bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Node.js de Data Catalog.

Para autenticarte en Data Catalog, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de Data Catalog sobre el uso de bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Python de Data Catalog.

Para autenticarte en Data Catalog, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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}")

REST y línea de comandos

REST

Si no tienes acceso a las bibliotecas cliente de Cloud para tu idioma o quieres probar la API con solicitudes REST, consulta los siguientes ejemplos y consulta las APIs de REST de Data Catalog entryGroups.create y entryGroups.entries.create.

  1. Crea un grupo de entrada

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project-id: el ID del proyecto de Google Cloud
  • entryGroupId: El ID debe comenzar con una letra o un guion bajo, contener solo letras del alfabeto inglés, números y guiones bajos, y tener 64 caracteres como máximo.
  • displayName: El nombre textual del grupo de entrada

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "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"
  }
}
  1. Crea un conjunto de archivos dentro del grupo de entrada

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • project_id: el ID del proyecto de Google Cloud
  • entryGroupId: ID del entryGroup existente. El conjunto de archivos se creará en este entryGroup.
  • entryId: EntryId del conjunto de archivos nuevo. El ID debe comenzar con una letra o un guion bajo, contener solo letras del alfabeto inglés, números y guiones bajos, y tener como máximo 64 caracteres.
  • description: Es la descripción del conjunto de archivos.
  • displayName: Es el nombre textual de la entrada del conjunto de archivos.
  • filePatterns: Debe comenzar con “gs://bucket_name/”. Consulta Requisitos del patrón de archivos.
  • schema: Es el esquema del conjunto de archivos.

    Esquema JSON de ejemplo: 
    { ...
  "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étodo HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Funciones, permisos y políticas de IAM

Data Catalog define las funciones de entrada y grupo de entradas para facilitar la administración de permisos de conjuntos de archivos y otros recursos de Data Catalog.

Funciones de entrada Descripción
dataCatalog.entryOwner Propietario de una entrada o un grupo de entradas en particular.
  • Permisos
    • datacatalog.entries.(*)
    • datacatalog.entryGroups.get
  • Aplicabilidad.
    • Nivel de organización, proyecto y entryGroup
dataCatalog.entryViewer Puede ver los detalles de entrada y entryGroup.
  • Permisos
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • Aplicabilidad.
    • Nivel de organización, proyecto y entryGroup
Funciones de grupo de entrada Descripción
dataCatalog.entryGroupOwner Propietario de un entryGroup en particular.
  • Permisos
    • datacatalog.entryGroups.(*)
    • datacatalog entries.(*)
  • Aplicabilidad.
    • Nivel de organización, proyecto y entryGroup
dataCatalog.entryGroupCreator Puede crear entryGroups dentro de un proyecto. El creador de un entryGroup recibe de forma automática la función dataCatalog.entryGroupOwner.
  • Permisos
    • datacatalog.entryGroups.(get | create)
  • Aplicabilidad.
    • Nivel de organización y proyecto

Configura políticas de IAM

Los usuarios con el permiso datacatalog.<resource>.setIamPolicy pueden establecer políticas de IAM en grupos de entradas de Data Catalog y otros recursos de Data Catalog (consulta funciones de Data Catalog).

Console

Navega a la página Detalles del grupo de entrada en la IU de Data Catalog y usa el panel de IAM ubicado en el lado derecho para otorgar o revocar permisos.

gcloud

Otorga roles de grupo de entrada

Ejemplo 1

Una empresa con diferentes contextos empresariales para sus conjuntos de archivos crea grupos de entrada order-files y user-files independientes:

El grupo order-files tiene buckets de almacenamiento con archivos de pedidos cancelados y completados, mientras que el grupo user-files tiene un bucket de almacenamiento con archivos de PII.
Figure 1. Un ejemplo de cómo almacenar datos de pedidos y datos de usuarios en diferentes grupos de entradas.

La empresa otorga a los usuarios el rol de visualizador de grupos de entrada para order-files, lo que significa que solo pueden buscar entradas contenidas en ese grupo de entrada. Sus resultados de la búsqueda no muestran entradas en el grupo de entrada user-files.

Ejemplo 2

Una empresa otorga el rol de visualizador de grupo de entrada a un usuario solo en el proyecto project_entry_group. El usuario solo podrá ver las entradas dentro de ese proyecto.

Busca conjuntos de archivos

Los usuarios pueden restringir el alcance de la búsqueda en Data Catalog mediante la faceta type. type=entry_group restringe la búsqueda a los grupos de entrada, mientras que type=fileset solo busca conjuntos de archivos. Las facetas type se pueden usar junto con otras facetas, como projectid.

gcloud

  • Busca grupos de entrada en un proyecto:

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

  • Busca todos los grupos de entrada a los que puedas acceder:

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

  • Busca conjuntos de archivos en un proyecto:

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

  • Busca conjuntos de archivos en un proyecto (sintaxis simplificada): 

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