Use as APIs do Data Catalog para criar e pesquisar entradas do conjunto de arquivos do Cloud Storage (chamadas de "conjuntos de arquivos" no restante deste documento).
Conjuntos de arquivo
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:
- Nomes de caractere curinga
- Documentação de referência da API GcsFilesetSpec.filePatterns
- Um conjunto de arquivos precisa ter um e não pode ter mais de 500 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
Acesse a página Dataplex > Grupos de entradas.
Clique em Criar grupo de entradas.
Preencha o formulário Criar grupo de entrada e clique em CRIAR.
A página Detalhes do grupo de entrada é aberta. Com a guia ENTRADAS selecionada, clique em CRIAR.
Preencha o formulário Criar conjunto de arquivos.
- 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.
- Clique em Salvar para salvar o esquema.
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 gcloud
, 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 esta amostra, siga as instruções de configuração de Java no Guia de início rápido do Data Catalog usando 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.
Node.js
Antes de testar esta amostra, siga as instruções de configuração de Node.js no Guia de início rápido do Data Catalog usando 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.
Python
Antes de testar esta amostra, siga as instruções de configuração de Python no Guia de início rápido do Data Catalog usando 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.
REST e LINHA DE CMD
REST
Se você não tiver acesso às bibliotecas de cliente do Cloud para sua linguagem ou quiser testar a API usando solicitações REST, consulte os exemplos a seguir e consulte as documentações entryGroups.create e entryGroups.entries.create da API REST do Data Catalog.
1. Criar um grupo de entrada
Antes de usar os dados da solicitação, faça as substituições a seguir:
- project-id: é o ID do projeto do Google Cloud.
- entryGroupId: o ID precisa começar com uma letra ou um sublinhado, conter apenas letras, números e sublinhados do inglês e ter no máximo 64 caracteres.
- displayName: o nome textual do grupo de entradas.
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" } }
2. Criar um conjunto de arquivos no grupo de entrada
Antes de usar os dados da solicitação, 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 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.
|
dataCatalog.entryViewer |
Pode visualizar detalhes de entry e entryGroup.
|
Papéis de entryGroup | Descrição |
---|---|
dataCatalog.entryGroupOwner |
Proprietário de um entryGroup específico.
|
dataCatalog.entryGroupCreator |
Pode criar entryGroups dentro de um projeto. O criador de um entryGroup recebe automaticamente o papel dataCatalog.entryGroupOwner .
|
Como definir políticas do 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).
gcloud
Defina a política do IAM de um grupo de entrada com gcloud data-catalog input-groups set-iam-policy:
gcloud data-catalog entry-groups set-iam-policy my_entrygroup \ --location=us-central1 \ policy file
Conseguir a política do IAM de um grupo de entrada com gcloud data-catalog input-groups get-iam-policy
gcloud data-catalog entry-groups get-iam-policy my_entrygroup \ --location=us-central1
Console
Navegue até a página Detalhes do grupo de entrada na IU do Data Catalog e use o painel do IAM localizado no lado direito para conceder ou revogar permissões.
Como 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:
A empresa concede aos usuários o papel Leitor do EntryGroup 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 Leitor do EntryGroup a um usuário apenas no projeto project_entry_group
. O usuário só poderá ver as entradas nesse projeto.
Como 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 entradas em um projeto:
gcloud data-catalog search \ --include-project-ids=my-project "projectid=my-project type=entry_group"
Pesquise todos os grupos de entradas 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 com sintaxe simplificada:
gcloud data-catalog search \ --include-project-ids=my-project "type=fileset"