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

Puedes usar las API de Data Catalog para crear y buscar entradas de conjuntos de archivos de Cloud Storage (llamadas “conjuntos de archivos” en el resto de 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 un patrón de conjunto de archivos, y no puede tener más de 5.

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

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 Dataplex >. Página Grupos de entrada

    Ir a Grupos de entrada 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 gcloud, 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 de Java que se encuentran en el Guía de inicio rápido de Data Catalog con 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 de Node.js que se encuentran en el Guía de inicio rápido de Data Catalog con 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}")

LÍNEA DE REST Y CMD

REST

Si no tienes acceso a las bibliotecas cliente de Cloud para tu lenguaje o quieres probar la API con solicitudes REST, consulta los siguientes ejemplos y consulta las API 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"
  }
}

2. 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 entryGroup 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.
    • Organización, proyecto y entryGroup.
dataCatalog.entryViewer Puede ver los detalles de entrada y entryGroup.
  • Permisos
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • Aplicabilidad.
    • Organización, proyecto y entryGroup.
Funciones de entryGroup Descripción
dataCatalog.entryGroupOwner Propietario de un entryGroup en particular.
  • Permisos
    • datacatalog.entryGroups.(*)
    • datacatalog entries.(*)
  • Aplicabilidad.
    • Nivel de organización, proyecto y entryGroups.
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).

gcloud

Console

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

Otorga funciones 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 la función de Visualizador de EntryGroup 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 la función de visualizador de EntryGroup 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"