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 cinco padrões.
É 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 o Dataplex > Grupos de entradas.
Clique em Criar grupo de entrada.
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 este exemplo, siga as instruções de configuração do Java na O 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 este exemplo, siga as instruções de configuração do Node.js na O guia de início rápido do Data Catalog usando bibliotecas de cliente. Para mais informações, consulte a API Data Catalog Node.js documentação de referência.
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 este exemplo, siga as instruções de configuração do Python na O 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 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" } }
2. 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 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 entry-groups set-iam-policy:
gcloud data-catalog entry-groups set-iam-policy my_entrygroup \ --location=us-central1 \ policy file
Receba a política do IAM de um grupo de entrada com gcloud data-catalog entry-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 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"