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 bucket debe seguir los requisitos del nombre del bucket 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:
- Nombres comodín
- Documentación de referencia de la API de GcsFilesetSpec.filePatterns
Un conjunto de archivos debe tener uno y no puede tener más de 500 patrones de conjuntos de archivos.

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

Crea grupos de entradas 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

Ve a la página Dataplex > Grupos de entrada.

Ir a los grupos de entrada de Dataplex
Haz clic en Crear grupo de entrada.
Completa el formulario Crear grupo de entrada (Create Entry Group) y haz clic en CREAR (CREATE).
Se abrirá la página Detalles del grupo de entrada (Entry group details). Con la pestaña ENTRADAS seleccionada, haz clic en CREAR.
Completa el formulario Crear conjunto de archivos.
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.
Haz clic en Crear (Create) para crear el conjunto de archivos.

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 de 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 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 para Node.js que se encuentran en la 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.

// 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 con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Python de Data Catalog.

# 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 inglés, números y guiones bajos, y tener un máximo de 64 caracteres.
displayName: Es el nombre textual del grupo de entrada.

HTTP method and 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:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: project-id" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId"

PowerShell (Windows)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/projects/project-id/locations/region/entryGroups?entryGroupId=entryGroupId" | Select-Object -Expand Content

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.

Ejemplo de esquema 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"
      }
    ]
  }
...
}

HTTP method and 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:

curl (Linux, macOS o Cloud Shell)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: project_id" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId"

PowerShell (Windows)

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project_id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/projects/project_id/locations/region/entryGroups/entryGroupId/entries?entryId=entryId" | Select-Object -Expand Content

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

Establece la política de IAM de un grupo de entrada con gcloud data-catalog input-groups set-iam-policy:

gcloud data-catalog entry-groups set-iam-policy my_entrygroup \  
    --location=us-central1 \  
    policy file

Obtén la política de IAM de un grupo de entrada con gcloud data-catalog input-groups get-iam-policy.

gcloud data-catalog entry-groups get-iam-policy my_entrygroup \  
    --location=us-central1

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 de archivos de pedido tiene buckets de almacenamiento con archivos de pedidos cancelados y completados, mientras que el grupo de archivos de usuario tiene un bucket de almacenamiento con archivos de PII. — **Figure 1.** Ejemplo de cómo almacenar los datos de pedidos y del usuario en diferentes grupos de entrada.

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 tienes acceso:

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"