DataWorks:Criar e usar uma função definida pelo usuário

Contexto

Uma função definida pelo usuário (UDF) complementa a biblioteca de funções existente. Escreva lógica e cálculos personalizados para execução durante consultas e permita um processamento de dados mais robusto. Para mais informações, consulte UDF overview. Além da interface visual do DataWorks, também é possível criar uma UDF com o MaxCompute Studio ou executar comandos diretamente no MaxCompute. Para mais detalhes, consulte Create a user-defined function in MaxCompute Studio e Create a user-defined function in MaxCompute by running commands.

Pré-requisitos

As funções no MaxCompute dependem de recursos. Antes de criar uma função, crie um recurso do MaxCompute e faça upload dele ou adicione-o ao DataWorks. Para mais informações, consulte Create a MaxCompute resource.

Limitações

No DataWorks, apenas as funções definidas pelo usuário enviadas pela interface visual estão disponíveis para visualização e gerenciamento. Para UDFs adicionadas ao mecanismo MaxCompute por outra ferramenta, como o MaxCompute Studio, carregue-as manualmente no DataWorks pelo recurso MaxCompute Functions. Após o carregamento, essas funções ficam visíveis e gerenciáveis no DataWorks. Para mais informações, consulte Manage MaxCompute functions.

Registrar uma função

1. Faça login no DataWorks console. Na região desejada, clique em Data Development and O&M > Data Development no painel de navegação à esquerda. Selecione um workspace na lista suspensa e clique em Go to Data Development.

2. Crie um workflow. Para mais informações, consulte Create an auto triggered workflow.

3. Crie uma função.

   1. Abra o workflow, clique com o botão direito em MaxCompute e selecione Create Function.

   2. Na caixa de diálogo Create Function, insira um Name e selecione um Path.

   3. Clique em Create.

   4. Na caixa de diálogo Register Function, configure os parâmetros.

      Parâmetro	Descrição
      Function Type	Selecione o tipo da função. Os valores válidos são Mathematical Operation Functions, Aggregate Functions, String Processing Functions, Date Functions, Window Functions e Other Functions. Para mais informações, consulte Use built-in functions.
      MaxCompute Engine Instance	Este parâmetro é somente leitura.
      Function Name	Nome usado para referenciar a função em instruções SQL. Deve ser globalmente único e não pode ser alterado após o registro.
      Owner	Proprietário da função. Por padrão, corresponde ao usuário atual, mas é possível selecionar outra conta.
      Class Name	Nome da classe da UDF. O formato é ResourceName.ClassName. O nome do recurso pode ser um nome de pacote Java ou um nome de recurso Python. O DataWorks permite criar funções definidas pelo usuário com recursos do MaxCompute dos tipos JAR e Python. O formato do nome da classe varia conforme o tipo de recurso: Para recursos JAR, o formato do Class Name é PackageName.ActualClassName. Obtenha esse valor no IntelliJ IDEA usando a ação copy reference. Por exemplo, se o nome do pacote Java for com.aliyun.odps.examples.udf e o nome real da classe for UDAFExample, defina o parâmetro Class Name como com.aliyun.odps.examples.udf.UDAFExample. Para recursos Python, o formato do Class Name é PythonResourceName.ActualClassName. Por exemplo, se o nome do recurso Python for LcLognormDist_sh e o nome real da classe for LcLognormDist_sh, defina o parâmetro Class Name como LcLognormDist_sh.LcLognormDist_sh. Nota Não inclua o sufixo .jar ou .py no nome do recurso. Envie e publique o recurso antes de utilizá-lo. Para mais informações, consulte Create and use MaxCompute resources.
      Resources	Selecione os recursos necessários para registrar a função. Modo visual: selecione apenas recursos já enviados ou adicionados ao DataWorks. Editor de código: selecione qualquer recurso da instância correspondente do mecanismo MaxCompute. Nota Não é necessário informar o caminho de um recurso já adicionado. Se a UDF utilizar múltiplos recursos, separe os nomes por vírgula (,).
      Description	Breve descrição da UDF.
      Expression Syntax	Exemplo de uso da UDF, como test.
      Parameter Description	Descrição dos tipos de parâmetros de entrada e retorno suportados.
      Return Value	Exemplo de valor de retorno, como 1. Este parâmetro é opcional.
      Example	Exemplo de utilização. Este parâmetro é opcional.

4. Clique no ícone na barra de ferramentas para salvar a função.

5. Envie a função.

   1. Clique no ícone na barra de ferramentas.

   2. Na caixa de diálogo Submission, insira uma Change Description.

   3. Clique em OK.

Para visualizar as funções em uma instância do mecanismo MaxCompute e seu histórico de alterações, consulte Manage MaxCompute functions.

Histórico de versões e rollback

Clique com o botão direito no nome da função e selecione View Earlier Versions para consultar o histórico de versões ou fazer rollback.

Usar uma função definida pelo usuário em um nó

Apêndice 1: Visualizar lista de UDFs

• Execute o comando SHOW FUNCTIONS para listar todas as funções definidas pelo usuário registradas no projeto MaxCompute vinculado ao DataStudio no seu workspace do DataWorks.

• O MaxCompute oferece diversas funções integradas. Para mais informações, consulte Overview of built-in functions.

// View the functions in the current project.
SHOW FUNCTIONS;

Apêndice 2: Visualizar detalhes da UDF

• Execute o comando DESCRIBE ou DESC seguido do nome da função para visualizar os detalhes de uma função definida pelo usuário.

  // Use the short form to view the details of a user-defined function.
  DESC FUNCTION <function_name>;

• No DataWorks, caso as funções existentes não atendam aos requisitos de processamento de dados em um workflow, escreva uma função definida pelo usuário do MaxCompute. Em seguida, faça upload e associe os recursos correspondentes, como pacotes JAR ou arquivos Python, para gerenciar e expandir suas capacidades de processamento. Para mais informações, consulte Manage MaxCompute resources.

Melhores práticas

Após criar uma função definida pelo usuário, consulte Best practices for allowing a specified user to access a specific UDF para implementar o controle de acesso adequado.

Documentos relacionados

• O MaxCompute permite empacotar um arquivo JAR, enviar o recurso JAR e registrar uma função definida pelo usuário (UDF) do MaxCompute com um único clique. Para mais informações, consulte Package, upload, and register.

• Para problemas comuns ao escrever UDFs do MaxCompute em Java, consulte FAQ about writing MaxCompute UDFs in Java.

• Para problemas comuns ao escrever UDFs do MaxCompute em Python, consulte FAQ about writing MaxCompute UDFs in Python.

Perguntas frequentes

P: Após enviar um recurso para o DataWorks e defini-lo como UDF, posso usá-lo em consultas SQL no DataAnalysis, além dos nós ODPS SQL no DataStudio?

R: Sim. As UDFs registradas no DataWorks são armazenadas no projeto MaxCompute correspondente. Portanto, elas podem ser utilizadas tanto em nós ODPS SQL quanto em consultas SQL no DataAnalysis.