Mostrar arquivos do Cloud Storage com entradas do conjunto de arquivos

Use a API Data Catalog para criar e pesquisar entradas de conjunto de arquivos do Cloud Storage (chamadas de conjuntos de arquivos neste documento).

Conjuntos de arquivos

Um conjunto de arquivos do Cloud Storage é uma entrada dentro de um grupo de entradas criado pelo usuário. Para mais informações, consulte Entradas e grupos de entradas.

Ele é definido por um ou mais padrões de arquivo que especificam um conjunto de um ou mais arquivos do Cloud Storage.

Requisitos de padrão de arquivo:

  • Um padrão de arquivo precisa começar com gs://bucket_name/.
  • O nome do intervalo precisa seguir os requisitos de nome do intervalo do Cloud Storage.
  • Caracteres curinga são permitidos na pasta e em partes de padrões de arquivo, mas caracteres curinga não são permitidos em nomes de intervalo. Para exemplos, veja:
  • Um conjunto de arquivos precisa ter um e não pode ter mais de cinco padrões de conjunto de arquivos.

É possível consultar conjuntos de arquivos do Data Catalog com o Dataflow SQL, mas somente se eles tiverem um esquema definido e contiverem apenas arquivos CSV sem linhas de cabeçalho.

Criar grupos de entradas e conjuntos de arquivos

Os conjuntos de arquivos precisam ser colocados em um grupo de entrada criado pelo usuário. Se você não criou um grupo de entrada, primeiro crie o grupo de entrada e, em seguida, crie o conjunto de arquivos dentro do grupo de entrada. É possível definir políticas do IAM no grupo de entrada para definir quem tem acesso a conjuntos de arquivos e outras entradas no grupo.

Console

Console

  1. Acesse a página Dataplex > Grupos de entrada.

    Acessar os grupos de entrada do Dataplex

  2. Clique em Criar grupo de entrada.

  3. Preencha o formulário Criar grupo de entrada e clique em CRIAR.

  4. A página Detalhes do grupo de entrada é aberta. Com a guia ENTRADAS selecionada, clique em CRIAR.

  5. Preencha o formulário Criar conjunto de arquivos.

    1. Para anexar um esquema, clique em Definir esquema para abrir o formulário de esquema. Clique em + ADICIONAR CAMPOS para adicionar campos individualmente ou alterne para Editar como texto no canto superior direito do formulário para especificar os campos no formato JSON.
    2. Clique em Salvar para salvar o esquema.

  6. Clique em Criar para criar o conjunto de arquivos.

gcloud

gcloud

1. Criar um grupo de entrada

Use o comando gcloud data-catalog entry-groups create para criar um grupo de entrada com um esquema e uma descrição anexados.

Exemplo:

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

2. Criar um conjunto de arquivos no grupo de entrada

Use o comando gcloud data-catalog entries create para criar um conjunto de arquivos em um grupo de entrada. Este exemplo de comando da CLI do Google Cloud, abaixo, cria uma entrada de conjunto de arquivos que inclui o esquema de dados do conjunto de arquivos.

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

Sinalizar notas:

  • --gcs-file-patterns: consulte Requisitos de padrão de arquivo.
  • --schema-from-file: a amostra a seguir mostra o formato JSON do arquivo de texto do esquema aceito pela sinalização --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 testar este exemplo, siga as instruções de configuração do Java no Guia de início rápido do Data Catalog: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Catalog Java.

Para autenticar no Data Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 testar este exemplo, siga as instruções de configuração do Node.js no Guia de início rápido do Data Catalog: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Catalog Node.js.

Para autenticar no Data Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Data Catalog: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Catalog Python.

Para autenticar no Data Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento 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 e linha de comando

REST

Se você não tiver acesso às bibliotecas do Cloud Client para seu idioma ou querer testar a API usando solicitações REST, consulte os exemplos a seguir e consulte a documentação da API REST entryGroups.create e entryGroups.entries.create.

  1. Criar um grupo de entrada

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project-id: é o ID do projeto do Google Cloud.
  • entryGroupId: o ID deve começar com uma letra ou um sublinhado, conter somente letras, números e sublinhados ingleses e ter no máximo 64 caracteres.
  • displayName: o nome textual do grupo de entrada.

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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. Criar um conjunto de arquivos no grupo de entrada

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • project_id: é o ID do projeto do Google Cloud.
  • entryGroupId: ID do entryGroup existente. O conjunto de arquivos será criado neste entryGroup.
  • entryId: entryId do novo conjunto de arquivos. O código precisa começar com uma letra ou sublinhado, conter apenas letras, números e sublinhados em inglês e ter no máximo 64 caracteres.
  • description: descrição do conjunto de arquivos.
  • displayName: o nome textual da entrada do conjunto de arquivos.
  • filePatterns: precisa começar com "gs://bucket_name/". Consulte Requisitos de padrão de arquivo.
  • schema: esquema do conjunto de arquivos.

    Exemplo 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"
      }
    ]
  }
...
}

Método HTTP e URL:

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

Corpo JSON da solicitação:

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

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

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

Papéis, permissões e políticas do IAM

O Data Catalog define os papéis entry e entryGroup para facilitar o gerenciamento de permissões de conjuntos de arquivos e outros recursos do Data Catalog.

Papéis de entrada Descrição
dataCatalog.entryOwner Proprietário de uma determinada entrada ou grupo de entradas.
  • Permissões:
    • datacatalog.entries.(*)
    • datacatalog.entryGroups.get
  • Aplicabilidade:
    • Nível da organização, do projeto e do entryGroup
dataCatalog.entryViewer Pode visualizar detalhes de entry e entryGroup.
  • Permissões
    • datacatalog.entries.get
    • datacatalog.entryGroups.get
  • Aplicabilidade:
    • Nível da organização, do projeto e do entryGroup
Papéis do grupo de entrada Descrição
dataCatalog.entryGroupOwner Proprietário de um entryGroup específico.
  • Permissões:
    • datacatalog.entryGroups.(*)
    • datacatalog entries.(*)
  • Aplicabilidade:
    • Nível da organização, do projeto e do entryGroup
dataCatalog.entryGroupCreator Pode criar entryGroups dentro de um projeto. O criador de um entryGroup recebe automaticamente o papel dataCatalog.entryGroupOwner.
  • Permissões:
    • datacatalog.entryGroups.(get | create)
  • Aplicabilidade:
    • Nível da organização e do projeto

Configurar políticas de IAM

Os usuários com permissão datacatalog.<resource>.setIamPolicy podem definir políticas do IAM em grupos de entrada do Data Catalog e outros recursos do Data Catalog (consulte Papéis do Data Catalog).

Console

Navegue até a página Detalhes do grupo de entrada na interface do Data Catalog e use o painel do IAM localizado no lado direito para conceder ou revogar permissões.

gcloud

Conceder papéis do grupo de entrada

Exemplo 1

Uma empresa com diferentes contextos de negócios para seus conjuntos de arquivos cria grupos de entrada order-files e user-files separados:

O grupo de arquivos de pedidos tem intervalos de armazenamento com arquivos de pedidos cancelados e concluídos, enquanto o grupo de arquivos de usuários tem um bucket de armazenamento com arquivos de PII.
Figura 1. Exemplo de como armazenar dados de pedidos e de usuários em diferentes grupos de entrada.

A empresa concede aos usuários o papel de leitor do grupo de entrada para order-files, o que significa que eles só podem pesquisar entradas contidas nesse grupo de entrada. Os resultados da pesquisa não retornam entradas no grupo de entradas user-files.

Exemplo 2

Uma empresa concede o papel de leitor do grupo de entrada a um usuário apenas no projeto project_entry_group. O usuário só poderá ver as entradas nesse projeto.

Pesquisar conjuntos de arquivos

Os usuários podem restringir o escopo da pesquisa no Data Catalog usando o atributo type. type=entry_group restringe a consulta de pesquisa a grupos de entrada, enquanto type=fileset pesquisa apenas conjuntos de arquivos. Os atributos type podem ser usados em conjunto com outros atributos, como projectid.

gcloud

  • Pesquisar grupos de entrada em um projeto:

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

  • Pesquisar todos os grupos de entrada que você pode acessar:

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

  • Pesquisar conjuntos de arquivos em um projeto:

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

  • Pesquisar conjuntos de arquivos em um projeto (sintaxe simplificada): 

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