Guia do usuário do SDK CatalogAPI - MaxCompute: Central de Documentação do Alibaba Cloud

Gerencie recursos de metadados do MaxCompute programaticamente com o SDK CatalogAPI para Java e Python.

Versão do produto: v0.2.2Repositório do SDK:aliyun/aliyun-odps-openapi-sdk

Visão geral

O SDK CatalogAPI é um SDK aberto para gerenciar o catálogo de dados do MaxCompute. Ele fornece acesso programático a recursos de metadados como Project, Schema, Table, Connection, Role, Taxonomy, DataPolicy, DataScan e Model.

Recursos

Capacidades principais:

Gerenciamento de tabelas

Crie e atualize tabelas internas e externas; consulte e exclua tabelas internas, tabelas externas, views, materialized views e snapshot tables.
Gerenciamento de conexões

Gerencie configurações de Connection para acessar fontes de dados externas, como OSS e OTS.
Gerenciamento de permissões

Implemente controle de acesso refinado por meio de Role e Policy.
Segurança de dados

Implemente controle de acesso no nível de coluna com Taxonomy e Policy Tag, além de mascaramento dinâmico de dados via DataPolicy.
Rastreamento de metadados

Descubra e rastreie metadados automaticamente de fontes de dados externas usando DataScan.
Gerenciamento de modelos

Gerencie metadados de modelos de machine learning com suporte a múltiplas versões.
Busca de recursos

Pesquise diversas entidades de metadados dentro de um namespace.

Modelo de recursos

O CatalogAPI segue um estilo de design RESTful. A hierarquia principal de recursos é a seguinte:

Namespace (primary account UID)
├── Connection          # External data source connection
├── Role                # Custom role
├── Taxonomy            # Policy tag classification
│   └── PolicyTag       # Policy tag
├── DataPolicy          # Data policy (masking rules)
├── DataScan            # Metadata crawling task
│   └── ScanJob         # Crawling job
Project             # MaxCompute project
    └── Schema          # Namespace (directory)
        ├── Table       # Data table
        │   └── Partition # Partition
        └── Model       # Machine learning model

Nota

O ID do namespace corresponde ao UID da conta primária da Alibaba Cloud.

Início rápido

Instale o SDK

O SDK CatalogAPI está disponível em Java e Python, hospedado no repositório GitHub da Alibaba Cloud.

// Add dependency in Maven project
<dependency>
    <groupId>com.aliyun.odps</groupId>
    <artifactId>catalog-api</artifactId>
    <version>0.2.2</version>
</dependency>

pip install pyodps-catalog

Inicialize o cliente

Inicialize o cliente CatalogAPI usando um par de AccessKey.

Importante

Não codifique pares de AccessKey diretamente no seu código. Utilize variáveis de ambiente ou arquivos de configuração para gerenciar credenciais.

import com.aliyun.odps.catalog.Client;
import com.aliyun.odps.models.Config;

public class CatalogDemo {
    public static void main(String[] args) throws Exception {
        // Initialize configuration
        Config config = new Config();
        config.setAccessKeyId(System.getenv("ALIBABACLOUD_ACCESS_KEY_ID"));
        config.setAccessKeySecret(System.getenv("ALIBABACLOUD_ACCESS_KEY_SECRET"));
        // Set the MaxCompute endpoint. The SDK automatically discovers the CatalogAPI endpoint through the routing API.
        // Replace cn-shanghai with your actual region.
        config.setOdpsEndpoint("service.cn-shanghai.maxcompute.aliyun.com");
        
        // Create client
        Client client = new Client(config);
        
        // Use client to call APIs
    }
}

import os
from pyodps_catalog.client import Client
from maxcompute_tea_openapi.models import Config

# Initialize configuration
config = Config(
    access_key_id=os.environ.get('ALIBABACLOUD_ACCESS_KEY_ID'),
    access_key_secret=os.environ.get('ALIBABACLOUD_ACCESS_KEY_SECRET'),
    # Method 1 (recommended): Set odps_endpoint. The SDK automatically discovers the CatalogAPI endpoint through the routing API.
    odps_endpoint='service.cn-shanghai.maxcompute.aliyun.com'
    # Method 2: Directly specify the CatalogAPI endpoint.
    # endpoint='catalogapi.cn-shanghai.maxcompute.aliyun.com'
)

# Create client
client = Client(config)

# Use client to call APIs

Exemplo: Liste tabelas

Este exemplo lista todas as tabelas em um schema especificado:

import com.aliyun.odps.catalog.models.ListTablesResponse;
import com.aliyun.odps.catalog.models.Table;

ListTablesResponse response = client.listTables(
    "my_project",    // projectId
    "default",       // schemaName
    100,             // pageSize
    ""               // pageToken. Pass empty string for the first call
);

if (response.getTables() != null) {
    for (Table table : response.getTables()) {
        System.out.println("Table: " + table.getTableName());
    }
}

// If more pages exist, use nextPageToken to continue
String nextToken = response.getNextPageToken();

response = client.list_tables(
    project_id="my_project",
    schema_name="default",
    page_size=100,
    page_token=""
)

if response.tables:
    for table in response.tables:
        print(f"Table: {table.table_name}")

# If more pages exist, use next_page_token to continue
next_token = response.next_page_token

Autenticação

Credenciais de acesso

O CatalogAPI exige um par de AccessKey da Alibaba Cloud para autenticação. Recomendamos o uso de um par de AccessKey de usuário RAM, seguindo o princípio do menor privilégio.

Lista de permissões

A tabela a seguir lista as permissões necessárias para cada operação de API:

Clique para expandir a lista completa de permissões

Recurso	Operação	Permissão necessária
Connection	Create	CreateConnection
Connection	List	ListConnection
Connection	Get	GetConnection
Connection	Update	UpdateConnection
Connection	Delete	DeleteConnection
Connection	SetPolicy	SetConnectionPolicy
Connection	GetPolicy	GetConnectionPolicy
Role	Create	CreateRole
Role	List	ListRole
Role	Get	GetRole
Role	Update	UpdateRole
Role	Delete	DeleteRole
Role	SetPolicy	SetRolePolicy
Role	GetPolicy	GetRolePolicy
Taxonomy	Create	CreateTaxonomy
Taxonomy	List	ListTaxonomy
Taxonomy	Get	GetTaxonomy
Taxonomy	Update	UpdateTaxonomy
Taxonomy	Delete	DeleteTaxonomy
Taxonomy	SetPolicy	SetTaxonomyPolicy
Taxonomy	GetPolicy	GetTaxonomyPolicy
PolicyTag	Create	UpdateTaxonomy
PolicyTag	List	GetTaxonomy
PolicyTag	Get	GetTaxonomy
PolicyTag	Update	UpdateTaxonomy
PolicyTag	Delete	UpdateTaxonomy
DataPolicy	Create	CreateDataPolicy
DataPolicy	List	ListDataPolicy
DataPolicy	Get	GetDataPolicy
DataPolicy	Delete	DeleteDataPolicy
DataPolicy	SetPolicy	SetDataPolicyPolicy
DataPolicy	GetPolicy	GetDataPolicyPolicy
Project	Get	ConnectProject
Schema	Create	CreateSchema
Schema	List	ListSchema
Schema	Get	GetSchema
Schema	Update	UpdateSchema
Schema	Delete	DeleteSchema
Schema	SetPolicy	SetSchemaPolicy
Schema	GetPolicy	GetSchemaPolicy
Table	Create	CreateTable
Table	List	List Table
Table	Get	Describe Table
Table	Update	Alter Table
Table	Delete	Drop Table
Table	SetPolicy	SetTablePolicy
Table	GetPolicy	GetTablePolicy
Table	GetDataToken	Select Table+UseConnection
Partition	List	Describe Table
Model	Create	CreateModel
Model	List	List Model
Model	Get	Describe Model
Model	Update	Alter Model
Model	Delete	Drop Model
Model	SetPolicy	SetModelPolicy
Model	GetPolicy	GetModelPolicy
ModelVersion	Create	Alter Model
ModelVersion	Delete	Alter Model
ModelVersion	List	Describe Model
DataScan	Create	CreateDataScan
DataScan	List	ListDataScan
DataScan	Get	GetDataScan
DataScan	Update	UpdateDataScan
DataScan	Delete	DeleteDataScan
DataScan	Trigger	TriggerDataScan
ScanJob	List	ListDataScanJob
Search	Search	SearchNamespace. Se a busca incluir uma condição de projeto, a permissão SearchProject será necessária para esses projetos

Policy e Role

O CatalogAPI suporta controle de acesso baseado em Policy. Uma Policy consiste em um conjunto de Bindings, onde cada Binding atribui uma Role a um conjunto de Members.

Modelo de Policy
```
{
  "etag": "string",
  "bindings": [
    {
      "role": "string",
      "members": ["string"]
    }
  ]
}
```
- etag: usado para validação de consistência em operações de leitura-modificação-escrita
- bindings: lista de bindings de funções
  - role: nome da função
  - members: lista de membros no formato user:{userId}

Exemplo de definição de Policy

import com.aliyun.odps.catalog.models.*;

// Construct SetPolicyRequest
Policy policy = new Policy();
Binding binding = new Binding();
// The role field requires the full resource path format: namespaces/{namespaceId}/roles/{roleName}
binding.setRole("namespaces/{namespaceId}/roles/odps.admin");
binding.setMembers(Arrays.asList("user:123456789"));
policy.setBindings(Arrays.asList(binding));
policy.setEtag("fetch_with_get_policy");
SetPolicyRequest request = new SetPolicyRequest();
request.setPolicy(policy);

// Set table Policy
client.setTablePolicy(table, request);

Modelos de dados

Campos comuns

Campo	Tipo	Descrição
name	string	Nome completo do recurso REST, globalmente único dentro do domínio. O SDK utiliza o nome do recurso para construir URLs de requisição REST. Geralmente é um campo apenas de saída.

Tipos de dados

Além dos tipos JSON padrão, os seguintes marcadores especiais de tipo de dados são utilizados:

Tipos de dados	Descrição
enum	Tipo de enumeração semântica, representado como string no formato JSON
int64	Inteiro de 64 bits, transmitido como string

Modelo Table

Table é um dos recursos principais no CatalogAPI.

{
  "etag": "string",
  "name": "string",
  "projectId": "string",
  "schemaName": "string",
  "tableName": "string",
  "type": "enum(TableType)",
  "description": "string",
  "tableSchema": { "object(TableFieldSchema)" },
  "clustering": { "object(Clustering)" },
  "tableConstraints": { "object(TableConstraints)" },
  "partitionDefinition": { "object(PartitionDefinition)" },
  "tableFormatDefinition": { "object(TableFormatDefinition)" },
  "externalDataConfiguration": { "object(ExternalDataConfiguration)" },
  "maxLakeConfiguration": { "object(MaxLakeConfiguration)" },
  "externalCatalogTableOptions": { "object(ExternalCatalogTableOptions)" },
  "expirationOptions": { "object(ExpirationOptions)" },
  "createTime": "string (int64 format)",
  "lastModifiedTime": "string (int64 format)",
  "labels": { "map<string, string>" }
}

Clique para expandir detalhes dos campos

Campo	Tipo	Obrigatório	Descrição
etag	string	Não	Usado para validação de consistência em operações de leitura-modificação-escrita
name	string	Não	Caminho completo da tabela, como projects/{projectId}/schemas/{schemaName}/tables/{tableName}. Apenas saída
projectId	string	Sim	ID do projeto ao qual a tabela pertence
schemaName	string	Condicional	Nome do schema ao qual a tabela pertence. Obrigatório no modelo de três camadas; não deve ser especificado no modelo de duas camadas
tableName	string	Sim	Nome da tabela
type	enum(TableType)	Não	Tipo da tabela. Valores válidos: TABLE (tabela interna), EXTERNAL (tabela externa), VIEW (view), MATERIALIZED_VIEW (materialized view), SNAPSHOT (snapshot table)
description	string	Não	Descrição da tabela, equivalente ao comentário em SQL DDL
tableSchema	TableFieldSchema	Não	Definição do schema de colunas da tabela
clustering	Clustering	Não	Definição de atributos de cluster. Disponível apenas para tabelas clusterizadas
tableConstraints	TableConstraints	Não	Definição de restrição de chave primária. Disponível apenas para delta tables
partitionDefinition	PartitionDefinition	Não	Definições de colunas de partição. Disponível apenas para tabelas particionadas
tableFormatDefinition	TableFormatDefinition	Não	Disponível apenas para tabelas internas. O padrão é o formato de tabela padrão
externalDataConfiguration	ExternalDataConfiguration	Não	Configuração de tabela externa. Aplicável apenas a tabelas externas
maxLakeConfiguration	MaxLakeConfiguration	Não	Configuração de tabela de lake gerenciado
externalCatalogTableOptions	ExternalCatalogTableOptions	Não	Informações de catálogo externo
expirationOptions	ExpirationOptions	Não	Configuração de expiração para dados de tabela e partição
createTime	string (int64)	Não	Hora de criação da tabela em milissegundos. Apenas saída
lastModifiedTime	string (int64)	Não	Hora da última modificação da tabela em milissegundos. Apenas saída
labels	map<string, string>	Não	Rótulos na tabela

Modelo TableFieldSchema

Tipos de dados suportados (FieldDataType):TINYINT,SMALLINT,INT,BIGINT,BINARY,FLOAT,DOUBLE,DECIMAL,VARCHAR,CHAR,STRING,DATE,DATETIME,TIMESTAMP,TIMESTAMP_NTZ,BOOLEAN,STRUCT,ARRAY,MAP

{
  "fieldName": "string",
  "sqlTypeDefinition": "string",
  "typeCategory": "enum(FieldDataType)",
  "mode": "enum(FieldMode)",
  "fields": [{ "object(TableFieldSchema)" }],
  "description": "string",
  "policyTags": { "object(PolicyTags)" },
  "maxLength": "string (int64 format)",
  "precision": "string (int64 format)",
  "scale": "string (int64 format)",
  "defaultValueExpression": "string"
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
fieldName	string	Nome da coluna (coluna de nível superior) ou nome do campo struct. Não presente no tableSchema de nível de tabela
sqlTypeDefinition	string	Apenas saída. Definição em string que representa o tipo da coluna em instruções SQL DDL. Saída apenas para colunas de tabela
typeCategory	enum(FieldDataType)	Tipo do campo
mode	enum(FieldMode)	REQUIRED (não pode ser NULL) ou NULLABLE (pode ser NULL)
fields	TableFieldSchema[]	Subcampos de um tipo STRUCT
description	string	Comentário da coluna
policyTags	PolicyTags	Opcional. Policy tag vinculada à coluna, usada para controle de acesso no nível de coluna e mascaramento de dados. A ausência deste campo indica nenhuma policy tag. Para tipos aninhados, policy tags só podem ser aplicadas a nós folha. Policy tags não podem ser aplicadas a colunas de partição
policyTags.names	string[]	Opcional. Lista de nomes de recursos de policy tag. Atualmente, cada coluna suporta apenas uma policy tag
maxLength	string (int64)	Comprimento máximo para tipos CHAR/VARCHAR
precision	string (int64)	Precisão para o tipo DECIMAL
scale	string (int64)	Escala para o tipo DECIMAL
defaultValueExpression	string	Opcional. String de expressão para o valor padrão

Modelo Connection

Connection é usado para configurar informações de conexão para acessar fontes de dados externas, como OSS e OTS.

{
  "name": "string",
  "connectionName": "string",
  "description": "string",
  "creationTime": "string (int64 format)",
  "lastModifiedTime": "string (int64 format)",
  "connectionType": "enum(ConnectionType)",
  "cloudResource": { "object(CloudResourceOptions)" },
  "region": "string"
}

Clique para expandir detalhes dos campos

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Nome de recurso globalmente único: namespaces/{namespace_ID}/connections/{connectionName}. Apenas saída
connectionName	string	Sim	Único dentro do namespace. Sensível a maiúsculas e minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Faixa de comprimento: [3, 32] bytes
description	string	Não	Opcional. Máximo de 1 KB
creationTime	string (int64)	Não	Hora de criação da conexão em milissegundos. Apenas saída
lastModifiedTime	string (int64)	Não	Hora da última modificação em milissegundos
connectionType	enum(ConnectionType)	Sim	Tipo de conexão. Valores válidos: CLOUD_RESOURCE (tipo de recurso de nuvem, como OSS e OTS)
cloudResource	CloudResourceOptions	Condicional	Defina apenas quando connectionType for CLOUD_RESOURCE delegatedAccount Tipo STRING. Nome da conta delegada, salvo automaticamente como a conta primária do criador durante a criação. Apenas saída. ramRoleArn Tipo STRING, obrigatório. ARN da função RAM autorizada para o serviço MaxCompute.
region	string	Não	Região à qual esta conexão pertence. Apenas saída

Modelo Role

Role é usado para definir funções personalizadas.

{
  "name": "string",
  "roleName": "string",
  "description": "string",
  "includedPermissions": ["string"],
  "etag": "string",
  "deleted": false
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Nome de recurso globalmente único: namespaces/{namespace_ID}/roles/{roleName}. Apenas saída
roleName	string	Único dentro do namespace. Sensível a maiúsculas e minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Faixa de comprimento: [3, 255] bytes
description	string	Opcional. Máximo de 1 KB
includedPermissions	string[]	Lista de permissões incluídas na Role
etag	string	Apenas saída por enquanto. Será usado para consistência de leitura-modificação-escrita no futuro
deleted	boolean	Apenas saída. Indica se o item foi excluído

Enum RoleView

Valores do enum	Descrição
BASIC	Não retorna includedPermissions. Este é o padrão
FULL	Retorna todos os campos

Modelo Taxonomy

Taxonomy é usado para gerenciar o sistema de classificação de policy tags (Policy Tag).

{
  "name": "string",
  "taxonomyName": "string",
  "description": "string",
  "activatedPolicyTypes": ["enum(PolicyType)"],
  "policyTagCount": 0,
  "createTime": "string (int64 format)",
  "lastModifiedTime": "string (int64 format)"
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Apenas saída. Formato: namespaces/{namespace_ID}/taxonomies/{ID}, onde ID é um ID único atribuído pelo sistema
taxonomyName	string	Único dentro do namespace. Sensível a maiúsculas e minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Faixa de comprimento: [3, 255] bytes
description	string	Opcional. Máximo de 2000 bytes
activatedPolicyTypes	PolicyType[]	Opcional. Lista de tipos de política habilitados nesta Taxonomy. O padrão é POLICY_TYPE_UNSPECIFIED
policyTagCount	integer	Apenas saída. Número de policy tags nesta Taxonomy
createTime	string (int64)	Apenas saída. Timestamp de criação da Taxonomy em milissegundos UTC
lastModifiedTime	string (int64)	Apenas saída. Timestamp da última modificação da Taxonomy em milissegundos UTC

Enum PolicyType

Valores do enum	Descrição
POLICY_TYPE_UNSPECIFIED	Tipo não especificado
FINE_GRAINED_ACCESS_CONTROL	Habilita controle de acesso no nível de coluna

Nota

Quando uma taxonomia especifica explicitamente FINE_GRAINED_ACCESS_CONTROL, ou qualquer policy tag sob a taxonomia tem uma política de dados configurada, todas as policy tags sob essa taxonomia são consideradas com controle de acesso no nível de coluna habilitado.

Modelo PolicyTag

PolicyTag é uma etiqueta de política anexada a uma Taxonomy, usada para implementar controle de acesso no nível de coluna.

{
  "name": "string",
  "policyTagName": "string",
  "description": "string",
  "parentPolicyTag": "string",
  "childPolicyTags": ["string"]
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Caminho completo da PolicyTag: namespaces/{namespace_ID}/taxonomies/{TID}/policyTags/{ID}, onde ID é um ID único atribuído pelo sistema
policyTagName	string	Único dentro da Taxonomy pai. Sensível a maiúsculas e minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Faixa de comprimento: [3, 255] bytes
description	string	Opcional. Máximo de 2000 bytes
parentPolicyTag	string	Nome do nó pai. Vazio indica o nó raiz. O padrão é vazio
childPolicyTags	string[]	Apenas saída. Lista de nomes de nós filhos

Modelo DataPolicy

DataPolicy é usado para definir regras de mascaramento de dados.

{
  "name": "string",
  "dataPolicyName": "string",
  "policyTag": "string",
  "dataPolicyType": "enum(DataPolicyType)",
  "dataMaskingPolicy": { "object(DataMaskingPolicy)" }
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	namespaces/{namespace_ID}/dataPolicies/{dataPolicyName}. Apenas saída
dataPolicyName	string	Nome da política de dados especificado pelo usuário, único no nível da conta
policyTag	string	Nome completo do recurso da policy tag vinculada a esta política de dados
dataPolicyType	enum(DataPolicyType)	Atualmente, apenas DATA_MASKING_POLICY (mascaramento de dados no nível de coluna) é suportado
dataMaskingPolicy	DataMaskingPolicy	Regras de mascaramento definidas nesta política de dados

DataMaskingPolicy

Campo	Tipo	Descrição
predefinedExpression	enum(PredefinedExpression)	Tipo de estratégia de mascaramento predefinida
parameters	string[]	Parâmetros da estratégia de mascaramento predefinida

Estratégias de mascaramento predefinidas (PredefinedExpression)

Valores do enum	Descrição
SHA256	Hash SHA256
SHA512	Hash SHA512
ALWAYS_NULL	Sempre retorna NULL
DEFAULT_MASKING_VALUE	Valor de mascaramento padrão
DATE_YEAR	Preserva apenas o ano
POINT_RESERVE	Preserva o ponto decimal
STRING_MASKED_BA	Mascaramento de string (direto)
STRING_UNMASKED_BA	String sem mascaramento (direto)
MD5	Hash MD5
SM3	Hash SM3
REPLACE_RANDOM	Substituição aleatória
REPLACE_RANDOM_BA	Substituição aleatória (direta)
REPLACE_FIXED	Substituição por valor fixo

Modelo DataScan

DataScan é usado para configurar tarefas de rastreamento de metadados.

{
  "name": "string",
  "scanName": "string",
  "type": "string",
  "creator": "string",
  "customerId": "string",
  "namespaceId": "string",
  "description": "string",
  "scanId": "string",
  "creationTime": 0,
  "lastModifiedTime": 0,
  "lastTriggeredTime": 0,
  "lastSuccessfulScheduleTime": 0,
  "lastTriggeredBy": "string",
  "schedulingStatus": "string",
  "source": { "object(DataScanSource)" },
  "target": { "object(DataScanTarget)" },
  "properties": { "object(DataScanProperties)" },
  "schedulerMode": "string",
  "schedulerInterval": "string",
  "scheduledCount": 0
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Nome de recurso globalmente único: namespaces/{namespaceID}/dataScans/{dataScanName}
scanName	string	Nome da tarefa de rastreamento especificado pelo usuário
type	string	Valores válidos: TABLE_DISCOVERY (descoberta de tabelas), SCHEMA_DISCOVERY (descoberta de schemas)
creator	string	Criador do dataScan
customerId	string	ID do cliente
namespaceId	string	Namespace ao qual o dataScan pertence
description	string	Descrição definida pelo usuário
scanId	string	ID de varredura gerado pelo sistema. Campo de exibição somente leitura
creationTime	int64	Hora de criação, timestamp UTC
lastModifiedTime	int64	Hora da última modificação, timestamp UTC
lastTriggeredTime	int64	Última hora de acionamento da tarefa de rastreamento (hora de início do agendamento), timestamp UTC. O padrão é 0 se nunca tiver sido acionado
lastSuccessfulScheduleTime	int64	Hora de execução do último DatascanJob bem-sucedido. O padrão é 0
lastTriggeredBy	string	Fonte que acionou o agendamento atual: um usuário específico ou o agendador
schedulingStatus	string	Status do agendamento. Valores válidos: IDLE / IMMEDIATE / PENDING / SCHEDULING. O status inicial é IDLE. Defina como IMMEDIATE para executar imediatamente após a criação
source	DataScanSource	Fonte de rastreamento e descoberta de metadados
target	DataScanTarget	Parâmetros que controlam como os resultados da descoberta são gravados
properties	DataScanProperties	Parâmetros opcionais para a tarefa de rastreamento
schedulerMode	string	manual (acionado manualmente) / periodic (acionamento automático periódico)
schedulerInterval	string	Quando schedulerMode é periodic, o intervalo máximo entre duas tarefas de rastreamento. Faixa válida: [1h-7d]
scheduledCount	int64	Número total de vezes que este dataScan foi agendado

DataScanSource

Campo	Tipo	Descrição
location	string	Endereço de localização. Suporta OSS, DLF e Holo
connection	string	Nome da conexão. Fornece as informações de identidade e rede necessárias para acessar a fonte. Autenticação necessária
ignores	string[]	Caminhos a ignorar. Suporta expressões regulares

DataScanTarget

Campo	Tipo	Descrição
project	string	Nome do projeto onde os resultados são gravados
schema	string	Quando dataScan.type é table, o schema onde as tabelas são gravadas
namePrefix	string	Prefixo para nomes de tabela/schema gerados automaticamente pela tarefa de rastreamento, evitando conflitos de nomenclatura
properties	string	Atributos de tabela/schema que os usuários podem especificar para a saída final

DataScanProperties

Campo	Tipo	Descrição
formatFilter	string	AUTO/PARQUET/ORC/JSON/CSV. Rastreia apenas dados com o formato especificado. Se especificado, arquivos de outros formatos são ignorados. AUTO habilita a detecção automática de formato
scanMode	enum	SAMPLE / TOTAL. O padrão é SAMPLE
enableStats	boolean	Se estatísticas são usadas para otimização de consultas
options	string	Configurações opcionais adicionais, como opções extras para formato CSV
pattern	string	Padrão de reconhecimento de caminho de partição, como {table}/{part1}={value1}/{part2}={value2}
updatePolicy	string	Política para lidar com alterações de metadados da tabela: APPEND_ONLY / OVERWRITE / IGNORE
syncRemove	boolean	Se deve excluir tabelas automaticamente quando removidas da fonte
autoCommit	boolean	false indica que a tarefa de rastreamento apenas gera resultados sem confirmar DDL
inventoryLocation	string	Especifica o local de armazenamento para logs do OSS Inventory, usado para varredura incremental

Modelo Model

Model é usado para gerenciar metadados de modelos de machine learning.

{
  "name": "string",
  "modelName": "string",
  "versionName": "string",
  "defaultVersion": "string",
  "createTime": "string",
  "updateTime": "string",
  "versionCreateTime": "string",
  "versionUpdateTime": "string",
  "description": "string",
  "versionDescription": "string",
  "expirationDays": 0,
  "versionExpirationDays": 0,
  "sourceType": "string",
  "modelType": "string",
  "labels": { "map<string, string>" },
  "transform": { "map<string, string>" },
  "path": "string",
  "options": { "map<string, string>" },
  "extraInfo": { "map<string, string>" },
  "versionExtraInfo": { "map<string, string>" },
  "trainingInfo": { "map<string, string>" },
  "inferenceParameters": { "map<string, string>" },
  "featureColumns": { "object(ModelFieldSchema)" },
  "tasks": ["string"]
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Caminho completo do modelo: projects/{projectId}/schemas/{schemaName}/models/{modelName}
modelName	string	Nome do modelo, único dentro do schema pai. Insensível a maiúsculas e minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Faixa de comprimento: [3, 255] bytes
versionName	string	Nome da versão, único dentro do mesmo modelo. Insensível a maiúsculas e minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Faixa de comprimento: [3, 255] bytes
defaultVersion	string	Nome da versão padrão do modelo
createTime	string	Hora de criação do modelo em milissegundos
updateTime	string	Hora da última modificação do modelo em milissegundos
versionCreateTime	string	Hora de criação da versão em milissegundos
versionUpdateTime	string	Hora da última modificação da versão em milissegundos
description	string	Descrição do modelo, máximo de 1 KB
versionDescription	string	Descrição da versão, máximo de 1 KB
expirationDays	integer	Ciclo de vida em dias com base na hora da última atualização do modelo
versionExpirationDays	integer	Ciclo de vida em dias com base na hora da última atualização da versão
sourceType	string	Tipo de origem do modelo. Não pode ser modificado após a criação
modelType	string	Tipo do modelo. Não pode ser modificado após a criação
labels	map<string, string>	Rótulos do modelo
transform	map<string, string>	Informações de pré-processamento da versão
path	string	Caminho para os arquivos do modelo da versão
options	map<string, string>	Parâmetros da versão
extraInfo	map<string, string>	Informações adicionais sobre o modelo
versionExtraInfo	map<string, string>	Informações adicionais sobre a versão
trainingInfo	map<string, string>	Informações de treinamento da versão
inferenceParameters	map<string, string>	Parâmetros de inferência da versão
featureColumns	ModelFieldSchema	Definição do schema de colunas da versão
tasks	string[]	Todos os tipos de tarefa suportados por esta versão

Restrições do campo tasks

Para modelos LLM/MLLM, os valores válidos incluem um ou mais de: text-generation, chat, sentence-embedding
Para modelos BOOSTED_TREE_CLASSIFIER, os valores válidos são [predict, predict-proba, feature-importance] (em qualquer ordem)
Para modelos BOOSTED_TREE_REGRESSOR, os valores válidos são [predict, feature-importance] (em qualquer ordem)

Modelo Schema

{
  "name": "string",
  "schemaName": "string",
  "description": "string",
  "type": "enum(SchemaType)",
  "owner": "string",
  "externalSchemaConfiguration": { "object(ExternalSchemaConfiguration)" }
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Nome completo do recurso do schema: projects/{projectId}/schemas/{schemaName}. Apenas saída
schemaName	string	Nome do schema, único dentro de um projeto
description	string	Opcional. Descrição do schema
type	enum(SchemaType)	Tipo de schema: DEFAULT (tipo padrão), EXTERNAL (externo, atualmente não suportado)
owner	string	Proprietário do schema
externalSchemaConfiguration	ExternalSchemaConfiguration	Opcional. Disponível apenas para schemas externos. Atualmente não habilitado nesta versão

Modelo Project

{
  "name": "string",
  "projectId": "string",
  "owner": "string",
  "description": "string",
  "createTime": "string (int64 format)",
  "lastModifiedTime": "string (int64 format)",
  "schemaEnabled": "boolean",
  "region": "string"
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Nome completo do recurso do projeto: projects/{projectId}. Apenas saída
projectId	string	ID único do projeto
owner	string	Proprietário do projeto
description	string	Descrição do projeto
createTime	string (int64)	Timestamp de criação do projeto em milissegundos UTC
lastModifiedTime	string (int64)	Timestamp da última modificação do projeto em milissegundos UTC
schemaEnabled	boolean	Se o modelo de três camadas está habilitado para o projeto
region	string	Região à qual o projeto pertence

Modelo Partition

{
  "spec": "string"
}

Campo	Tipo	Descrição
spec	string	Especificação da partição. Formato de exemplo: bu=tt/ds=20250515

Modelo Search

{
  "name": "string",
  "displayName": "string",
  "type": "string",
  "aspects": { "map<string, string>" },
  "createTime": "string",
  "lastModifiedTime": "string",
  "description": "string"
}

Clique para expandir detalhes dos campos

Campo	Tipo	Descrição
name	string	Caminho completo da entidade, como `projects/{projectId}/schemas/{schemaName}/tables/{tableName}`
displayName	string	Nome da entidade
type	string	Tipo da entidade, por exemplo, TABLE, RESOURCE, SCHEMA
aspects	map<string, string>	Informações adicionais sobre a entidade
createTime	string	Hora de criação da entidade em milissegundos
lastModifiedTime	string	Hora da última modificação da entidade em milissegundos
description	string	Descrição da entidade

Referência de API

Observações gerais

Prefixo de URL: Todas as URLs de API neste documento utilizam o seguinte prefixo:/api/catalog/v1alpha/.

Importante

Este prefixo não se repete nas descrições individuais das APIs.

Tratamento de erros

Código de status HTTP	Motivo	Descrição
400	InvalidArgument	Entrada da requisição inválida
403	AccessDenied	Sem permissão para executar esta operação
404	NotFound	O objeto alvo da operação não existe
409	AlreadyExists	O objeto a ser criado já existe
429	RateLimitExceeded	Taxa de requisições muito alta. Limitação de taxa acionada
500	InternalError	Erro interno do servidor

API de Tabelas

Criar tabela

Crie uma nova tabela.

Assinatura do método
```
Table createTable(Table table)
```

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table, contendo a definição completa da tabela

Resposta

Retorna o objeto Table criado.

Exemplo de uso

// Construct table
Table table = new Table();
table.setProjectId("my_project");
table.setSchemaName("default");
table.setTableName("my_table");
table.setDescription("This is an example table");
table.setType("TABLE");

// Set table schema
TableFieldSchema field = new TableFieldSchema();
field.setFieldName("id");
field.setTypeCategory("BIGINT");
field.setMode("REQUIRED");

TableFieldSchema nameField = new TableFieldSchema();
nameField.setFieldName("name");
nameField.setTypeCategory("STRING");
nameField.setMode("NULLABLE");

TableFieldSchema schema = new TableFieldSchema();
schema.setFields(Arrays.asList(field, nameField));
table.setTableSchema(schema);

// Create table
Table createdTable = client.createTable(table);
System.out.println("Created table: " + createdTable.getName());

Obter tabela

Obtenha informações detalhadas sobre uma tabela especificada.

Assinatura do método
```
Table getTable(Table table)
```

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table contendo projectId, schemaName e tableName

Resposta

Retorna um objeto Table.

Exemplo de uso

Table query = new Table();
query.setProjectId("my_project");
query.setSchemaName("default");
query.setTableName("my_table");

Table result = client.getTable(query);
System.out.println("Table type: " + result.getType());
System.out.println("Description: " + result.getDescription());

Atualizar tabela

Atualize os atributos de uma tabela especificada.

Assinatura do método
```
Table updateTable(Table table)
```

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table contendo as atualizações

Resposta

Retorna o objeto Table atualizado.

Exemplo de uso

Table table = client.getTable(query);
table.setDescription("Updated description");

Table updated = client.updateTable(table);

Excluir tabela

Exclua uma tabela especificada.

Assinatura do método
```
HttpResponse deleteTable(Table table)
```

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table contendo projectId, schemaName e tableName

Resposta

Retorna um HttpResponse vazio em caso de sucesso.

Exemplo de uso

HttpResponse response = client.deleteTable(table);
System.out.println("Status code: " + response.getStatusCode());

Listar tabelas

Liste todas as tabelas em um schema especificado.

Assinatura do método

ListTablesResponse listTables(String projectId, String schemaName, Integer pageSize, String pageToken)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
projectId	string	Sim	ID do projeto
schemaName	string	Sim	Nome do schema
pageSize	integer	Não	Tamanho da página. O padrão é 100, máximo de 1000
pageToken	string	Não	Token de paginação. O padrão é vazio

Resposta

{
  "tables": [Table],
  "nextPageToken": "string"
}

Exemplo de uso

ListTablesResponse response = client.listTables("my_project", "default", 100, "");

// Iterate through all pages
while (response.getTables() != null && !response.getTables().isEmpty()) {
    for (Table t : response.getTables()) {
        System.out.println(t.getTableName());
    }
    
    if (response.getNextPageToken() == null || response.getNextPageToken().isEmpty()) {
        break;
    }
    response = client.listTables("my_project", "default", 100, response.getNextPageToken());
}

Definir Policy da tabela

Defina a política de acesso de uma tabela.

Assinatura do método

Policy setTablePolicy(Table table, SetPolicyRequest request)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table
request	SetPolicyRequest	Sim	Requisição de política

Resposta

Retorna o objeto Policy atualizado.

Obter Policy da tabela

Obtenha a política de acesso de uma tabela.

Assinatura do método
```
Policy getTablePolicy(Table table)
```

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table

Resposta

Retorna o objeto Policy da tabela.

Obter DataToken da tabela

Obtenha um token de acesso temporário para uma tabela especificada.

Assinatura do método

DataToken getDataToken(Table table, Integer duration)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
table	Table	Sim	Objeto Table
duration	integer	Não	Período de validade do token (segundos)

Resposta

{
  "version": "string",
  "type": "string",
  "value": "string",
  "expiration": "string"
}

Descrição dos campos do DataToken

Campo	Tipo	Descrição
version	string	Versão do formato. Atualmente V1
type	string	Tipo. Atualmente, apenas STS é suportado
value	string	Conteúdo do token, codificado em base64
expiration	string	Horário de expiração

API de Partições

Listar partições

Liste todas as partições de uma tabela especificada.

Assinatura do método

ListPartitionsResponse listPartitions(
    String projectId, 
    String schemaName, 
    String tableName, 
    Integer pageSize, 
    String pageToken,
    String query,
    String view
)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
projectId	string	Sim	ID do projeto
schemaName	string	Sim	Nome do schema
tableName	string	Sim	Nome da tabela
pageSize	integer	Não	Tamanho da página. O padrão é 100, máximo de 1000
pageToken	string	Não	Token de paginação. O padrão é vazio
query	string	Não	Condição de busca de partição, por exemplo, partition_name:part
view	string	Não	Atualmente, apenas BASIC é suportado

Resposta

{
  "partitions": [Partition],
  "nextPageToken": "string"
}

API de Conexões

Criar conexão

Crie uma nova conexão com fonte de dados externa.

Assinatura do método

Connection createConnection(String namespace, Connection connection)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace (UID da conta principal)
connection	Connection	Sim	Objeto Connection

Resposta

Retorna o objeto Connection criado.

Exemplo de uso

// Construct Connection
Connection conn = new Connection();
conn.setConnectionName("my_oss_connection");
conn.setDescription("Connection for accessing OSS");
conn.setConnectionType("CLOUD_RESOURCE");

CloudResourceOptions options = new CloudResourceOptions();
options.setRamRoleArn("acs:ram::123456789:role/MaxComputeOSSRole");
conn.setCloudResource(options);

// Create connection
Connection created = client.createConnection("123456789", conn);

Listar conexões

Liste todas as conexões em um namespace especificado.

Assinatura do método

ListConnectionsResponse listConnections(String namespace, Integer pageSize, String pageToken)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
pageSize	integer	Não	Tamanho da página. O padrão é 100, máximo de 1000
pageToken	string	Não	Token de paginação. O padrão é vazio

Resposta

{
  "connections": [Connection],
  "nextPageToken": "string"
}

Obter conexão

Obtenha informações detalhadas sobre uma conexão especificada.

Assinatura do método

Connection getConnection(String namespace, String connectionName)

Atualizar conexão

Atualize os atributos de uma conexão especificada.

Assinatura do método

Connection updateConnection(String namespace, String connectionName, Connection connection, String updateMask)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
connectionName	string	Sim	Nome da conexão
connection	Connection	Sim	Objeto Connection contendo as atualizações
updateMask	string	Sim	Especifique os campos a serem atualizados. Atualmente, apenas o campo description é suportado

Resposta

Retorna o objeto Connection atualizado.

Exemplo de uso

Connection conn = new Connection();
conn.setConnectionName("my_oss_connection");
conn.setDescription("Updated description");

Connection updated = client.updateConnection("123456789", "my_oss_connection", conn, "description");

Excluir conexão

Exclua uma conexão especificada.

Assinatura do método

HttpResponse deleteConnection(String namespace, String connectionName)

Definir Policy da conexão

Defina a política de acesso de uma conexão.

Assinatura do método

Policy setConnectionPolicy(String namespace, String connectionName, SetPolicyRequest request)

Obter Policy da conexão

Obtenha a política de acesso de uma conexão.

Assinatura do método

Policy getConnectionPolicy(String namespace, String connectionName)

API de Funções

Criar função

Crie uma Role personalizada.

Assinatura do método

Role createRole(String namespace, Role role)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
role	Role	Sim	Objeto Role

Resposta

Retorna o objeto Role criado.

Exemplo de uso

Role role = new Role();
role.setRoleName("my_custom_role");
role.setDescription("Custom role");
role.setIncludedPermissions(Arrays.asList("odps:CreateTable", "odps:ListTable"));

Role created = client.createRole("123456789", role);

Listar funções

Liste todas as funções em um namespace especificado.

Assinatura do método

ListRolesResponse listRoles(
    String namespace, 
    Integer pageSize, 
    String pageToken, 
    String view, 
    Boolean showDeleted
)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
pageSize	integer	Não	Tamanho da página. O padrão é 100, máximo de 1000
pageToken	string	Não	Token de paginação. O padrão é vazio
view	enum(RoleView)	Não	O padrão é BASIC. Quando definido como FULL, todos os campos são retornados
showDeleted	boolean	Não	Indica se deve incluir funções excluídas. O padrão é false

Resposta

{
  "roles": [Role],
  "nextPageToken": "string"
}

Obter função

Obtenha informações detalhadas sobre uma função especificada.

Assinatura do método

Role getRole(String namespace, String roleName)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
roleName	string	Sim	Nome da função

Atualizar função

Atualize os atributos de uma função especificada.

Assinatura do método

Role updateRole(String namespace, String roleName, Role role, String updateMask)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
roleName	string	Sim	Nome da função
role	Role	Sim	Objeto Role contendo as atualizações
updateMask	string	Sim	Especifique os campos a serem atualizados, como `"description, includedPermissions"`

Excluir função

Exclua uma função personalizada especificada.

Assinatura do método

HttpResponse deleteRole(String namespace, String roleName)

Importante

Após a exclusão de uma função, as seguintes alterações entram em vigor imediatamente:

A função não pode mais ser vinculada a uma Policy.
Políticas já vinculadas a esta função permanecem no estado vinculado, mas não surtem efeito.
A operação de listar funções não exibe funções excluídas por padrão. Após a exclusão, a função ainda conta para o limite total e permanece em estado excluído por sete dias. Depois desse período, a função é removida permanentemente, todos os vínculos de recursos com ela são eliminados e ela deixa de contar para o limite total.

Definir Policy da função

Defina a política de acesso de uma função.

Assinatura do método

Policy setRolePolicy(String namespace, String roleName, SetPolicyRequest request)

Obter Policy da função

Obtenha a política de acesso de uma função.

Assinatura do método

Policy getRolePolicy(String namespace, String roleName)

API de Taxonomia

Criar Taxonomy

Crie uma nova classificação de tags de política.

Assinatura do método

Taxonomy createTaxonomy(String namespace, Taxonomy taxonomy)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
taxonomy	Taxonomy	Sim	Objeto Taxonomy

Resposta

Retorna o objeto Taxonomy criado.

Exemplo de uso

Taxonomy taxonomy = new Taxonomy();
taxonomy.setTaxonomyName("sensitive_data");
taxonomy.setDescription("Sensitive data classification");
taxonomy.setActivatedPolicyTypes(Arrays.asList("FINE_GRAINED_ACCESS_CONTROL"));

Taxonomy created = client.createTaxonomy("123456789", taxonomy);

Listar Taxonomy

Liste todas as Taxonomies em um namespace especificado.

Assinatura do método

ListTaxonomiesResponse listTaxonomies(String namespace, Integer pageSize, String pageToken)

Obter Taxonomy

Obtenha informações detalhadas sobre uma Taxonomy especificada.

Assinatura do método

Taxonomy getTaxonomy(String namespace, String taxonomyId)

Atualizar Taxonomy

Atualize os atributos de uma Taxonomy especificada.

Assinatura do método

Taxonomy updateTaxonomy(String namespace, String taxonomyId, Taxonomy taxonomy, String updateMask)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
taxonomyId	string	Sim	ID da Taxonomy
taxonomy	Taxonomy	Sim	Objeto Taxonomy contendo as atualizações
updateMask	string	Sim	Especifique os campos a serem atualizados, como `"description, activatedPolicyTypes"`

Excluir Taxonomy

Exclui em cascata todas as tags de política, políticas de dados configuradas e relações de vínculo de colunas sob a taxonomia.

Assinatura do método

HttpResponse deleteTaxonomy(String namespace, String taxonomyId)

Definir Policy da Taxonomy

Defina a política de acesso de uma Taxonomy.

Assinatura do método

Policy setTaxonomyPolicy(String namespace, String taxonomyId, SetPolicyRequest request)

Obter Policy da Taxonomy

Obtenha a política de acesso de uma Taxonomy.

Assinatura do método

Policy getTaxonomyPolicy(String namespace, String taxonomyId)

API de PolicyTag

Criar PolicyTag

Crie uma nova tag de política sob uma Taxonomy especificada.

Assinatura do método

PolicyTag createPolicyTag(String namespace, String taxonomyId, PolicyTag policyTag)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
taxonomyId	string	Sim	ID da Taxonomy
policyTag	PolicyTag	Sim	Objeto PolicyTag

Resposta

Retorna o objeto PolicyTag criado.

Exemplo de uso

PolicyTag tag = new PolicyTag();
tag.setPolicyTagName("phone_number");
tag.setDescription("Phone number masking tag");

PolicyTag created = client.createPolicyTag("123456789", "taxonomy_id_123", tag);

Listar PolicyTag

Liste todas as PolicyTags sob uma Taxonomy especificada.

Assinatura do método

ListPolicyTagsResponse listPolicyTags(
    String namespace, 
    String taxonomyId, 
    Integer pageSize, 
    String pageToken
)

Obter PolicyTag

Obtenha informações detalhadas sobre uma PolicyTag especificada.

Assinatura do método

PolicyTag getPolicyTag(String namespace, String taxonomyId, String policyTagId)

Atualizar PolicyTag

Atualize os atributos de uma PolicyTag especificada.

Assinatura do método

PolicyTag updatePolicyTag(
    String namespace, 
    String taxonomyId, 
    String policyTagId, 
    PolicyTag policyTag, 
    String updateMask
)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
taxonomyId	string	Sim	ID da Taxonomy
policyTagId	string	Sim	ID da PolicyTag
policyTag	PolicyTag	Sim	Objeto PolicyTag contendo as atualizações
updateMask	string	Sim	Especifique os campos a serem atualizados. Atualmente, apenas o campo description é suportado

Excluir PolicyTag

Exclua uma tag de política e remova recursivamente: todos os nós filhos da tag, todas as políticas de dados configuradas nela (incluindo nós filhos) e as relações de vínculo de colunas da tag nas tabelas (incluindo nós filhos).

Assinatura do método

HttpResponse deletePolicyTag(String namespace, String taxonomyId, String policyTagId)

Definir Policy da PolicyTag

Defina a política de acesso de uma PolicyTag.

Assinatura do método

Policy setPolicyTagPolicy(String namespace, String taxonomyId, String policyTagId, SetPolicyRequest request)

Obter Policy da PolicyTag

Obtenha a política de acesso de uma PolicyTag.

Assinatura do método

Policy getPolicyTagPolicy(String namespace, String taxonomyId, String policyTagId)

API de DataPolicy

Criar DataPolicy

Crie uma nova política de dados (regra de mascaramento).

Assinatura do método

DataPolicy createDataPolicy(String namespace, DataPolicy dataPolicy)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
dataPolicy	DataPolicy	Sim	Objeto DataPolicy

Resposta

Retorna o objeto DataPolicy criado.

Exemplo de uso

// Construct masking rule
DataMaskingPolicy maskingPolicy = new DataMaskingPolicy();
maskingPolicy.setPredefinedExpression("STRING_MASKED_BA");

DataPolicy policy = new DataPolicy();
policy.setDataPolicyName("phone_masking");
policy.setPolicyTag("namespaces/123456789/taxonomies/tid_123/policyTags/ptid_456");
policy.setDataPolicyType("DATA_MASKING_POLICY");
policy.setDataMaskingPolicy(maskingPolicy);

DataPolicy created = client.createDataPolicy("123456789", policy);

Listar DataPolicy

Liste todas as DataPolicies em um namespace especificado.

Assinatura do método

ListDataPoliciesResponse listDataPolicies(String namespace, Integer pageSize, String pageToken)

Obter DataPolicy

Obtenha informações detalhadas sobre uma DataPolicy especificada.

Assinatura do método

DataPolicy getDataPolicy(String namespace, String dataPolicyName)

Excluir DataPolicy

Exclua uma DataPolicy especificada.

Assinatura do método

HttpResponse deleteDataPolicy(String namespace, String dataPolicyName)

Definir Policy da DataPolicy

Defina a política de acesso de uma DataPolicy.

Assinatura do método

Policy setDataPolicyPolicy(String namespace, String dataPolicyName, SetPolicyRequest request)

Obter Policy da DataPolicy

Obtenha a política de acesso de uma DataPolicy.

Assinatura do método

Policy getDataPolicyPolicy(String namespace, String dataPolicyName)

API de DataScan

Criar DataScan

Crie uma nova tarefa de rastreamento de metadados.

Assinatura do método

DataScan createDataScan(String namespace, DataScan dataScan)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespace	string	Sim	ID do namespace
dataScan	DataScan	Sim	Objeto DataScan

Resposta

Retorna o objeto DataScan criado.

Exemplo de uso

// Construct crawling task
DataScanSource source = new DataScanSource();
source.setLocation("oss://my-bucket/my-path/");
source.setConnection("my_oss_connection");

DataScanTarget target = new DataScanTarget();
target.setProject("my_project");
target.setSchema("default");
target.setNamePrefix("auto_");

DataScanProperties properties = new DataScanProperties();
properties.setFormatFilter("AUTO");
properties.setScanMode("SAMPLE");
properties.setAutoCommit(true);

DataScan dataScan = new DataScan();
dataScan.setScanName("my_oss_scan");
dataScan.setType("TABLE_DISCOVERY");
dataScan.setDescription("Crawl OSS metadata");
dataScan.setSource(source);
dataScan.setTarget(target);
dataScan.setProperties(properties);
dataScan.setSchedulerMode("MANUAL");

DataScan created = client.createDataScan("123456789", dataScan);

Listar DataScan

Liste todos os DataScans em um namespace especificado.

Assinatura do método

ListDataScansResponse listDataScans(String namespace, Integer pageSize, String pageToken)

Obter DataScan

Obtenha informações detalhadas sobre um DataScan especificado.

Assinatura do método

DataScan getDataScan(String namespace, String dataScanName)

Atualizar DataScan

Atualize os atributos de um DataScan especificado.

Assinatura do método

DataScan updateDataScan(String namespace, DataScan dataScan, String updateMask)

Excluir DataScan

Exclua um DataScan especificado.

Assinatura do método

HttpResponse deleteDataScan(String namespace, String dataScanName)

Acionar DataScan

Acione manualmente uma tarefa de rastreamento do DataScan.

Assinatura do método

HttpResponse triggerDataScan(String namespace, String dataScanName)

Exemplo de uso

HttpResponse response = client.triggerDataScan("123456789", "my_oss_scan");
System.out.println("Triggered: " + response.getStatusCode());

Listar jobs do DataScan

Liste o histórico de jobs de rastreamento de um DataScan especificado.

Assinatura do método

ListDataScanJobsResponse listDataScanJobs(
    String namespace, 
    String dataScanName, 
    Integer pageSize, 
    String pageToken
)

Resposta

{
  "scanJobs": [ScanJob],
  "nextPageToken": "string"
}

Modelo ScanJob

Campo	Tipo	Descrição
jobId	string	ID do job
namespaceId	string	Namespace ao qual o job pertence
dataScanId	string	ID do dataScan gerado pelo sistema
dataScanName	string	Nome da tarefa de rastreamento pai
triggeredBy	string	Pessoa que acionou este job de rastreamento. scheduler para acionamentos agendados
startTime	int64	Horário de início do job de rastreamento, timestamp UTC
endTime	int64	Horário de término do job de rastreamento, timestamp UTC
status	string	Status do job de rastreamento: Created/Running/Terminated/Failed
statusDetail	string	Detalhes do status do job de rastreamento, como mensagens de erro
ddl	string	Informações DDL retornadas pelo job de rastreamento que precisam ser submetidas
stats	string	Informações de estatísticas retornadas pelo job de rastreamento no formato JSON

API de Modelos

Criar modelo

Crie um novo modelo de machine learning.

Assinatura do método

Model createModel(String projectId, String schemaName, Model model)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
projectId	string	Sim	ID do projeto
schemaName	string	Sim	Nome do schema
model	Model	Sim	Objeto Model

Resposta

Retorna o objeto Model criado.

Exemplo de uso

Model model = new Model();
model.setModelName("my_llm_model");
model.setVersionName("v1");
model.setDefaultVersion("v1");
model.setDescription("My large language model");
model.setSourceType("IMPORT");
model.setModelType("LLM");
model.setPath("oss://my-bucket/models/my_llm/");
model.setTasks(Arrays.asList("text-generation", "chat"));

Model created = client.createModel("my_project", "default", model);

Listar modelos

Liste todos os modelos em um schema especificado.

Assinatura do método

ListModelsResponse listModels(
    String projectId, 
    String schemaName, 
    Integer pageSize, 
    String pageToken
)

Obter modelo

Obtenha informações detalhadas sobre um modelo específico.

Assinatura do método

Model getModel(String projectId, String schemaName, String modelName, String versionName)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
projectId	string	Sim	ID do projeto
schemaName	string	Sim	Nome do schema
modelName	string	Sim	Nome do modelo
versionName	string	Não	Nome da versão. Se não for especificado, os metadados do modelo (sem versão) serão consultados

Atualizar modelo

Atualize os atributos de um modelo específico.

Assinatura do método

Model updateModel(
    String projectId, 
    String schemaName, 
    String modelName, 
    Model model, 
    String updateMask, 
    String versionName
)

Excluir modelo

Exclua um modelo específico (incluindo todas as versões).

Assinatura do método

HttpResponse deleteModel(String projectId, String schemaName, String modelName)

Criar versão do modelo

Crie uma nova versão para um modelo específico.

Assinatura do método

Model createModelVersion(String projectId, String schemaName, String modelName, Model model)

Exemplo de uso

Model version = new Model();
version.setModelName("my_llm_model");
version.setVersionName("v2");
version.setVersionDescription("Updated model version");
version.setPath("oss://my-bucket/models/my_llm_v2/");
version.setTasks(Arrays.asList("text-generation", "chat"));

Model createdVersion = client.createModelVersion("my_project", "default", "my_llm_model", version);

Excluir versão do modelo

Exclua uma versão específica do modelo.

Assinatura do método

HttpResponse deleteModelVersion(
    String projectId, 
    String schemaName, 
    String modelName, 
    String versionName
)

Listar versões do modelo

Liste todas as versões de um modelo específico.

Assinatura do método

ListModelVersionsResponse listModelVersions(
    String projectId, 
    String schemaName, 
    String modelName, 
    Integer pageSize, 
    String pageToken
)

Definir Policy do modelo

Defina a política de acesso de um modelo.

Assinatura do método

Policy setModelPolicy(String projectId, String schemaName, String modelName, SetPolicyRequest request)

Obter Policy do modelo

Obtenha a política de acesso de um modelo.

Assinatura do método

Policy getModelPolicy(String projectId, String schemaName, String modelName)

API de Projeto

Obter Projeto

Obtenha informações detalhadas sobre um projeto específico.

Assinatura do método
```
Project getProject(String projectId)
```

Exemplo de uso

Project project = client.getProject("my_project");
System.out.println("Project owner: " + project.getOwner());
System.out.println("Schema enabled: " + project.getSchemaEnabled());
System.out.println("Region: " + project.getRegion());

API de Schema

Criar Schema

Crie um novo schema em um projeto específico.

Assinatura do método

Schema createSchema(String projectId, Schema schema)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
projectId	string	Sim	ID do projeto
schema	Schema	Sim	Objeto schema

Resposta

Retorna o objeto schema criado.

Exemplo de uso

Schema schema = new Schema();
schema.setSchemaName("my_schema");
schema.setDescription("My custom schema");

Schema created = client.createSchema("my_project", schema);

Listar Schemas

Liste todos os schemas em um projeto específico.

Assinatura do método

ListSchemasResponse listSchemas(String projectId, Integer pageSize, String pageToken)

Obter Schema

Obtenha informações detalhadas sobre um schema específico.

Assinatura do método

Schema getSchema(String projectId, String schemaName)

Atualizar Schema

Atualize os atributos de um schema específico.

Assinatura do método

Schema updateSchema(String projectId, String schemaName, String updateMask, Schema schema)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
projectId	string	Sim	ID do projeto
schemaName	string	Sim	Nome do schema
updateMask	string	Sim	Especifique os campos a serem atualizados. Atualmente, apenas os campos description e owner são suportados, e somente um campo pode ser atualizado por vez
schema	Schema	Sim	Objeto schema contendo as atualizações

Excluir Schema

Exclua um schema específico.

Assinatura do método

HttpResponse deleteSchema(String projectId, String schemaName)

Definir Policy do Schema

Defina a política de acesso de um schema.

Assinatura do método

Policy setSchemaPolicy(String projectId, String schemaName, SetPolicyRequest request)

Obter Policy do Schema

Obtenha a política de acesso de um schema.

Assinatura do método

Policy getSchemaPolicy(String projectId, String schemaName)

API de Pesquisa

Pesquisar entidades

Pesquise várias entidades dentro de um namespace específico.

Assinatura do método

SearchResponse search(
    String namespaceId, 
    String query, 
    Integer pageSize, 
    String pageToken, 
    String orderBy
)

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Descrição
namespaceId	string	Sim	ID da conta primária. A pesquisa é realizada no escopo desta conta primária
query	string	Sim	String de consulta de pesquisa composta por uma ou mais condições separadas por vírgulas
pageSize	integer	Não	Número de resultados por página. Deve ser > 0, máximo de 100
pageToken	string	Não	Token de página
orderBy	string	Não	Ordem de classificação dos resultados

Sintaxe de consulta

Lista de condições de consulta:

Condição de consulta	Descrição
name:foo	Corresponde a foo como substring ao nome da entidade
description:bar	Corresponde a bar como substring à descrição da entidade
type=TABLE	Obrigatório. Corresponde a entidades de um tipo específico. Atualmente suporta TABLE, RESOURCE, SCHEMA
project=proj	Pesquisa entidades apenas em um único projeto especificado. O chamador deve ter permissão SearchProject para o projeto
project=(proj1	proj2	proj3)	Pesquisa entidades em vários projetos (até 512). O chamador deve ter permissão SearchProject para todos os projetos especificados
region=region_id	Pesquisa entidades em projetos de uma região específica

project=proj e project=(proj1|proj2|proj3) não podem ser usados juntos
region=region_id não pode ser usado junto com a condição de consulta project

Ordem de classificação (orderBy)

Valores válidos	Descrição
default	Ordem de armazenamento interno (padrão)
create_time asc	Tempo de criação crescente
create_time desc	Tempo de criação decrescente
last_modified_time asc	Última modificação crescente
last_modified_time desc	Última modificação decrescente

Resposta

{
  "entries": [SearchResultEntry],
  "nextPageToken": "string"
}

Exemplo de uso

// Search all tables in a specified project
SearchResponse response = client.search(
    "123456789",                            // namespaceId
    "type=TABLE,project=my_project",        // query
    50,                                     // pageSize
    "",                                     // pageToken
    "last_modified_time desc"               // orderBy
);

if (response.getEntries() != null) {
    for (SearchResultEntry entry : response.getEntries()) {
        System.out.println("Name: " + entry.getDisplayName());
        System.out.println("Type: " + entry.getType());
        System.out.println("Path: " + entry.getName());
    }
}

Limites de uso

Limites de taxa

Os limites de taxa são aplicados no nível da conta primária. Cada método possui seu próprio limite, que varia conforme a categoria da solicitação.

Limite	Valor
Métodos Get e GetPolicy	1500 solicitações / 15 segundos
Métodos List, Create, Update, Delete e SetPolicy	150 solicitações / 15 segundos
GetProject, ListTables, ListPartitions view=StorageDetail/FULL	15 solicitações / 15 segundos

Limites de capacidade

Limite	Valor
Número de funções personalizadas por conta primária	300
Número de permissões por função	3000
Número de principais por política de permissão	1500
Tamanho total de uma única função personalizada (incluindo descrição, roleName, etc.)	64KB

Limites de Policy Tag

Limite	Valor
Número de Policy Tags vinculadas a uma única coluna em uma única tabela	1
Número de taxonomias por conta	40
Número de Policy Tags por taxonomia	100
Profundidade de uma árvore de Policy Tag	5
Número de políticas de dados por tag	8

Limites de paginação

Parâmetro	Valor padrão	Valor máximo
pageSize	100	1000 (100 para algumas APIs)

Convenções de nomenclatura

Convenções de nomenclatura de conexão

Campo	Convenção
connectionName	Único dentro do namespace. Diferencia maiúsculas de minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Intervalo de comprimento: [3, 32] bytes

Convenções de nomenclatura de função

Campo	Convenção
roleName	Único dentro do namespace. Diferencia maiúsculas de minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Intervalo de comprimento: [3, 255] bytes

Convenções de nomenclatura de taxonomia

Campo	Convenção
taxonomyName	Único dentro do namespace. Diferencia maiúsculas de minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Intervalo de comprimento: [3, 255] bytes

Convenções de nomenclatura de PolicyTag

Campo	Convenção
policyTagName	Único dentro da taxonomia pai. Diferencia maiúsculas de minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Intervalo de comprimento: [3, 255] bytes

Convenções de nomenclatura de DataPolicy

Campo	Convenção
dataPolicyName	Único no nível da conta

Convenções de nomenclatura de modelo

Campo	Convenção
modelName	Único dentro do schema pai. Não diferencia maiúsculas de minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Intervalo de comprimento: [3, 255] bytes
versionName	Único dentro do mesmo modelo. Não diferencia maiúsculas de minúsculas. Caracteres válidos: [a-z][A-Z][0-9]_. Intervalo de comprimento: [3, 255] bytes

FAQ

O que é um Namespace ID?

O Namespace ID é o UID da conta primária do Alibaba Cloud. Ao chamar APIs de nível de namespace, como Connection, Role, Taxonomy, DataPolicy e DataScan, o UID da conta primária deve ser passado como parâmetro de namespace.

O que é o modelo de três camadas?

O MaxCompute suporta dois métodos de organização de metadados:

Modelo de duas camadas: Projeto → Tabela (método tradicional)
Modelo de três camadas: Projeto → Schema → Tabela (novo método)

Utilize o campo Project.schemaEnabled para determinar se o modelo de três camadas está ativado para um projeto. Caso esteja ativado, o parâmetro schemaName deve ser especificado ao chamar APIs de tabela.

Como implementar controle de acesso no nível de coluna usando Policy Tag?

Fluxo completo para controle de acesso no nível de coluna:

Crie uma taxonomia com activatedPolicyTypes definido como FINE_GRAINED_ACCESS_CONTROL.
Crie PolicyTags sob a taxonomia (suporta estrutura hierárquica em árvore).
Vincule uma PolicyTag a uma coluna específica no schema da tabela.
Crie uma DataPolicy para a PolicyTag (defina regras de mascaramento, opcional).
Use Policy para controlar quais usuários podem acessar colunas vinculadas à PolicyTag.

Como verificar os resultados de rastreamento do DataScan?

Após a execução de uma tarefa de rastreamento do DataScan, um ScanJob é gerado. O histórico de tarefas pode ser visualizado através da API listDataScanJobs. Cada ScanJob contém:

status: status da tarefa (Created/Running/Terminated/Failed)
ddl: informações DDL retornadas pelo rastreamento que precisam ser confirmadas
stats: informações estatísticas retornadas pelo rastreamento (formato JSON)

As policy tags são restauradas ao recuperar tabelas excluídas com o comando RESTORE?

Não. As policy tags aplicadas à tabela antes da exclusão não são restauradas junto com ela. Após a restauração, as policy tags devem ser reaplicadas às colunas da tabela.

Como lidar com a paginação?

A maioria das APIs List retorna um campo nextPageToken. Se este campo não estiver vazio, há mais páginas disponíveis. Passe o nextPageToken como parâmetro pageToken na próxima solicitação para recuperar a página seguinte de dados.

Apêndice

Histórico de versões do SDK

Versão	Data de lançamento	Descrição
v0.2.2	—	Versão atual

Glossário

Termo	Descrição
Namespace	Namespace, correspondente ao UID da conta primária do Alibaba Cloud
Project	Projeto do MaxCompute
Schema	Namespace (diretório) para o modelo de três camadas
Table	Tabela de dados
Connection	Conexão com fonte de dados externa
Role	Função personalizada
Taxonomy	Sistema de classificação de policy tags
PolicyTag	Tag de política para implementação de controle de acesso no nível de coluna
DataPolicy	Política de dados para definição de regras de mascaramento
DataScan	Tarefa de rastreamento de metadados
Model	Metadados de modelo de machine learning
Policy	Política de acesso, consistindo em um conjunto de Bindings
Binding	Vincula uma função a um conjunto de membros