Ir para o conteúdo

Datapool

A funcionalidade do Datapool pode ser utilizada para gerenciar uma fila de itens em grande volume que precisam ser processados e acompanhados granularmente.

Nessa seção você encontra mais detalhes sobre como interagir com esse recurso do Orquestrador BotCity através do SDK.

Orquestrador BotCity

Você pode utilizar a funcionalidade do Datapool diretamente na plataforma do Orquestrador BotCity.

Veja mais em:

Criar um Datapool

Você pode criar a estrutura de um novo Datapool e fazer as configurações via SDK.

Você precisa das seguintes informações:

  • Label: Identificador único do Datapool.
  • Nome: Nome amigável para reconhecimento do Datapool.
  • Reprocessamento: O número máximo de tentativas de reprocessamento em caso de erro no item.
  • Abortar em caso de erro: O número máximo de erros consecutivos até inativar a fila.
  • Tempo de processamento: O tempo em minutos esperado para processamento do item.
  • Schema: Lista de campos que compões o Datapool, definidos com a classe SchemaField:
    • label: Identificador do campo.
    • type: Tipo de dado, definido por FieldType: TEXT, INTEGER ou DOUBLE.
    • unique_id: Define como um ID unico: True ou False.
    • display_value: Define como visivel aos usuários: True ou False.

Criar via interface do Orquestrador

Apesar do Maestro SDK possibilitar a criação de um Datapool via código, recomendamos que você utilize a interface web do Orquestrador para conseguir realizar as configurações de forma mais intuitiva e detalhada sobre cada parâmetro necessário.

Veja mais em:

# Exemplo de Schema com campos: 'id', 'name' e 'price'

product_id = SchemaField(
    label="id",
    type=FieldType.TEXT,
    unique_id=True,
    display_value=True
)

product_name = SchemaField(
    label="name",
    type=FieldType.TEXT,
    unique_id=False,
    display_value=True
)

product_price = SchemaField(
    label="price",
    type=FieldType.DOUBLE,
    unique_id=False,
    display_value=False
)

# Lista com os campos
schema = [product_id, product_name, product_price]

# Criando o objeto do Datapool
datapool = DataPool(
    label="ProductsData",
    name="ProductsData",
    max_auto_retry=2,
    max_errors_before_inactive=5,
    item_max_processing_time=3,
    schema=schema
)

# Criando a estrutura do Datapool no Orquestrador
maestro.create_datapool(datapool)

// Ainda não implementado

Operações com o Datapool

Você pode realizar algumas operações com o Datapool criado, entre elas:

  • Obter: Retorna a referência do Datapool.
    • Label: Parâmetro de identificação do Datapool.
  • Está ativo: Verifica se o Datapool obtido está ativo: True ou False.
  • Está vazio: Verifica se não há itens pendentes no Datapool obtido: True ou False.
  • Tem próximo: Verifica se há um próximo item pendente na fila no Datapool obtido: True ou False.
  • Ativar: Faz a ativação do Datapool obtido.
  • Desativar: Faz a inativação do Datapool obtido.

Exemplos de uso:

# Obtendo a referência do Datapool
datapool = maestro.get_datapool("ProductsData")

# Verificando se o Datapool está ativo
print(datapool.is_active())

# Verificando se o Datapool está vazio de itens pendentes
print(datapool.is_empty())

# Verificando se há um próximo item pendente
print(datapool.has_next())

# Marcando o Datapool como ativo
datapool.activate()

# Marcando o Datapool como inativo
datapool.deactivate()

// Obtendo a referência do Datapool
Datapool datapool = await maestro.GetDatapoolAsync("ProductsData");

// Verificando se o Datapool está vazio
Console.WriteLine(await datapool.IsActiveAsync());

// Checking if the Datapool is empty
Console.WriteLine(await datapool.IsEmptyAsync());

// Marcando o Datapool como ativo
await datapool.ActivateAsync();

// Marcando o Datapool como inativo
await datapool.DeactivateAsync();

Operações com o itens

Com o Datapool criado, você pode fazer operações com os itens, veja a seguir as ações possiveis.

Adicionar novos itens

Você pode adicionar itens diretamente por uma automação ou script utilizando o SDK.

Você precisa das seguintes informações:

  • Label: Referência do Datapool criado.
  • Item: Valores de entrada de um novo item, definidos com a classe DataPoolEntry:
    • values: Estrutura de chave e valor conforme os campos criados para o Datapool de referência.

Dica

Você pode criar um script que faz entrada de valores no Datapool e outro que faz o consumo e processamento desses dados.

Exemplo de entrada de um item:

# Instanciando um novo item do Datapool com base no Schema que foi definido
new_item = DataPoolEntry(
    values={
        "id": "Electronic#001"
        "name": "Smartphone",
        "price": "2000"
    }
)

# Obtendo a referência do Datapool
datapool = maestro.get_datapool("ProductsData")

# Adicionando um novo item
datapool.create_entry(new_item)

// Instanciando um novo item do Datapool com base no Schema que foi definido
var values = new Dictionary<string, object>
{
    { "id", "Electronic#001" },
    { "name", "Smartphone" },
    { "price", 2000 }
};
DatapoolEntry new_item = new DatapoolEntry(0,values);

// Obtendo a referência do Datapool
Datapool datapool = await maestro.GetDatapoolAsync("ProductsData");

// Adicionando um novo item
await datapool.CreateEntryAsync(new_item);

Cancelar itens

Você pode cancelar itens que estão pendentes de processamento na fila. Isso significa que o item não será processado, porém, se mantém no histórico do Datapool.

Você precisa das seguintes informações:

  • Label: Referência do Datapool.
  • ID do Item: Identificador único do item.
  • Mensagem de finalização: (opcional) Mensagem de cancelamento.

Estado do item

Somente itens que possuem o estado de PENDENTE podem ser cancelados.

Exemplo de cancelamento de um item:

# Obtendo a referência do Datapool
datapool = maestro.get_datapool("ProductsData")

# Cancelando item que está pendente na fila
datapool.cancel_entry(
    entry_id="<ENTRY_ID>",
    finish_message="Item com dados faltantes"
)

// Ainda não implementado

Deletar itens

Você pode excluir itens que estão na fila do Datapool.

Você precisa das seguintes informações:

  • Label: Referência do Datapool.
  • ID do Item: Identificador unico do item.

Estado do item

Itens que estão no estado de PROCESSANDO ou TIMEOUT não podem ser excluídos.

# Obtendo a referência do Datapool
datapool = maestro.get_datapool("ProductsData")

# Removendo item da fila
datapool.delete_entry(entry_id="<ENTRY_ID>")

// Ainda não implementado

Obter itens

Você pode obter a referência dos itens para processamento ou para verificação de seus valores.

Você precisa das seguintes informações:

  • Label: Referência do Datapool.
  • ID do Item: Identificador unico do item.

Atenção!

O método next() altera o estado de um item de PENDENTE para PROCESSANDO.

# Obtendo a referência do Datapool
datapool = maestro.get_datapool("ProductsData")

# Busca o próximo item do Datapool
item_1 = datapool.next(task_id=<TASK_ID>)

# Através do método get_entry() também podemos obter um item através do seu ID
item_2 = datapool.get_entry(entry_id="<ENTRY_ID>")

// Busca o próximo item do Datapool
DatapoolEntry item = await datapool.NextAsync(<TASK_ID>);

// Obtendo o valor de algum campo específico do item
string item_data = await item.GetValueAsync("data-label");

Acessar valores dos itens

Após obter a referência do item, você pode acessar seus valores com base no Schema que foi criado.

Você precisa das seguintes informações:

  • Item: Referência do item obtido.
  • Label: Identificador do campo definido no Schema.
# Obtendo o valor de algum campo específico do item
item_data = item["data-label"]

# Utilizar o método get_value() terá o mesmo efeito
item_data = item.get_value("data-label")

// Busca o próximo item do Datapool
DatapoolEntry item = await datapool.NextAsync(<TASK_ID>);

// Obtendo o valor de algum campo específico do item
string item_data = await item.GetValueAsync("data-label");

Reportar o estado de finalização

Reportar o estado de finalização de um item é essencial para que eles sejam contabilizados da forma correta.

Cada item processado pode ser finalizado com um estado de CONCLUÍDO ou ERRO.

Você precisa das seguintes informações:

  • Item: Referência do item obtido.
  • Sucesso: Reporta o estado de concluido.
  • Erro: Reporta o estado de erro, definido o tipo:
    • ErrorType.SYSTEM: indica um erro de sistema.
    • ErrorType.BUSINESS: indica um erro de negócio.
  • Mensagem: (opcional) valor customizado para finalização.

Tipo de erro

Por padrão, todo erro será considerado do tipo SYSTEM quando não for especificado no reporte.

Itens reportados com erros do tipo BUSINESS não serão considerados para os cenários de auto-retry e abortar em caso de erros. Para esses cenários, somente itens com erro do tipo SYSTEM serão considerados.

# Busca o próximo item disponível do Datapool
item = datapool.next(task_id=<TASK_ID>)

# Finalizando como 'CONCLUÍDO' após o processamento
item.report_done(finish_message="Processado com sucesso!")

# Finalizando o processamento do item indicando um erro de sistema
item.report_error(error_type=ErrorType.SYSTEM, finish_message="Sistema indisponível.")

# Finalizando o processamento do item indicando um erro de negócio
item.report_error(error_type=ErrorType.BUSINESS, finish_message="Dados inválidos.")

// Busca o próximo item do Datapool
DatapoolEntry item = await datapool.NextAsync(<TASK_ID>);

// Finalizando como 'CONCLUÍDO' após o processamento
await item.ReportDoneAsync();

// Finalizando o processamento do item como 'ERRO'
await item.ReportErrorAsync();

Sugestão de estrutura de consumo do Datapool

O Datapool pode ser consumido de diversas formas, utilizando os métodos de operações de itens.

Veja um exemplo de implementação para consumo de uma sequência de itens em uma única tarefa:

# Consumindo o próximo item disponível e reportando o estado de finalização ao final
datapool = maestro.get_datapool(label="Items-To-Process")

while datapool.has_next():
    # Busca o próximo item do Datapool
    item = datapool.next(task_id=<TASK_ID>)
    if item is None:
        # O item poderia ser 'None', caso outro processo o consumisse antes
        break

    try:
        # Processando o item...

        # Finalizando como 'CONCLUÍDO' após o processamento
        item.report_done(finish_message="Processado com sucesso!")

    except Exception:
        # Finalizando o processamento do item como 'ERRO'
        item.report_error(finish_message="Falha no processamento.")

// Consumindo o próximo item disponível e reportando o estado de finalização ao final
Datapool datapool = await maestro.GetDatapoolAsync("Items-To-Process");

while (await dataPool.HasNextAsync()) {
    // Busca o próximo item do Datapool
    DatapoolEntry item = await datapool.NextAsync(<TASK_ID>);
    if (item == null) {
        // O item poderia ser 'null', caso outro processo o consumisse antes
        break;
    }

    try {
        // Processando o item...

        // Finalizando como 'CONCLUÍDO' após o processamento
        await item.ReportDoneAsync();

    } catch (Exception ex) {
        // Finalizando o processamento do item como 'ERRO'
        await item.ReportErrorAsync();
    }
}

Aviso

Lembre-se de sempre incluir no código o reporte referente ao estado de finalização de cada item que foi processado.

Isso é extremamente importante para que os estados dos itens sejam atualizados dentro do Datapool no Orquestrador BotCity.