Opcional - com escopo, global

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 7 min. de leitura

    • A API opcional interage com um único registro retornado pelas APIs GlideQuery, Streamou GlideRecord, mesmo quando ele não existe. Grave scripts com menor probabilidade de resultar em erro ao manipular resultados de consulta nulos ou indefinidos.

    Você pode obter um objeto Opcional destas maneiras:

    Esses métodos são estáticos e não exigem uma instância da classe:

    Você pode usar esses métodos estáticos com qualquer API que retorne um único valor, como GlideRecord.

    Use a API opcional em scripts do lado do servidor com escopo ou globais. Esta API requer o plug-in GlideQuery [com.sn_glidequery].

    Implementação

    Esta API pode funcionar com as APIs GlideQuery e Stream em um Padrão de construtor em que as chamadas de método se encadeiam, cada método com base no resultado retornado do método anterior. Use métodos para definir os atributos da consulta. Os métodos não são executados até que você chame um método de terminal, um método que retorna um resultado de consulta, permitindo que você defina os requisitos da consulta antes de executá-la.

    Se a consulta retornar um único registro, o sistema encapsulará o resultado em um objeto Opcional. Se a consulta retornar um fluxo de registros, o sistema encapsulará o resultado em um objeto Fluxo. Esses objetos permitem gerenciar o resultado usando um conjunto de métodos em cada API.

    Por exemplo, este script executa uma consulta na tabela de tarefas, agrupa os registros por prioridade e retorna cada prioridade que tenha um total de reatribuições maior que quatro.

    var query = new global.GlideQuery('task')
    .where('active', true) //Returns new GlideQuery object with a "where" clause.
    .groupBy('priority') //Returns new GlideQuery object with a "group by" clause.
    .aggregate('sum', 'reassignment_count') //Returns new GlideQuery object with a "sum(reassignment_count)" clause.
    .having('sum', 'reassignment_count', '>', 4) //Returns new GlideQuery object with a "having reassignment_count > 4" clause.
    .select() //Returns a stream of records wrapped in a Stream object.  
    .forEach(function (priority){ //Terminal method in the Stream class that executes the query and returns the result. 
      gs.info("Priority " + priority.group.priority + ": " + priority.sum.reassignment_count + " reassignments");
    });
    Saída:
    Priority 1: 11 reassignments
Priority 3: 6 reassignments
Priority 5: 5 reassignments

    Métodos de terminal

    Por motivos de desempenho, uma consulta só busca dados quando você chama um método de terminal. Estes são os métodos de terminal da classe Opcional :

    Opcional - vazio (motivo da cadeia de caracteres)

    Retorna um objeto opcional vazio. Use este método em uma cláusula Else para lidar com uma consulta que pode não retornar um resultado.

    Nota:
    Este método é estático. Você não precisa de uma instância da classe para usar este método.
    Tabela 1. Parâmetros
    Nome Tipo Descrição
    motivo Cadeia de caracteres Opcional. Motivo exibido no log quando Opcional.get() é chamado no objeto Opcional vazio.
    Tabela 2. Retorna
    Tipo Descrição
    Opcional Objeto usado para interagir com um único registro.

    Este exemplo mostra como gerar um objeto Opcional vazio quando uma consulta não retorna um resultado.

    var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

    Saída:

    NiceError: [2020-08-26T23:23:37.402Z]: get() called on empty Optional: no results

    Opcional - filter(predicado da função)

    Aplica uma função de predicado, uma função que usa um único valor e retorna verdadeiro ou falso, ao registro dentro do objeto Opcional. Se a função retornar verdadeiro, o método retornará o registro Opcional inalterado. Se a função retornar falso, ela retornará um objeto opcional vazio.

    Tabela 3. Parâmetros
    Nome Tipo Descrição
    predicado Função Função de predicado a ser aplicada ao valor dentro do objeto Opcional. Deve retornar um valor booliano.
    Tabela 4. Retorna
    Tipo Descrição
    Opcional Objeto usado para interagir com um único registro.

    Este exemplo mostra como aplicar uma função de filtro a um resultado Opcional.

    var filteredQuery = new global.GlideQuery('sys_user')
    .getBy({ sys_id: 'f682abf03710200044e0bfc8bcbe5d38' }, ['phone'])
    .filter(function (user) {
        return phoneRegex.test(user.phone);
    });

    Opcional - planaMap(Função fn)

    Aplica uma função que retorna um objeto Opcional ao resultado de uma consulta. Use este método para executar uma segunda consulta usando o resultado da primeira.

    Tabela 5. Parâmetros
    Nome Tipo Descrição
    fn Função Função para aplicar aos resultados da consulta que retornou o objeto Opcional.
    Tabela 6. Retorna
    Tipo Descrição
    Opcional Objeto usado para interagir com um único registro.

    Este exemplo mostra como executar uma consulta da tabela Usuário com base no resultado de uma consulta anterior.

    new global.GlideQuery('alm_asset')
    .whereNotNull('owned_by')
    .selectOne('owned_by')
    .flatMap(function (asset) {
        return new global.GlideQuery('sys_user')
            .getBy({ sys_id: asset.owned_by }, ['first_name', 'last_name', 'company.name'])
    })
    .ifPresent(GQ.jsonDebug);

    Saída:

    {
  "sys_id": "46d59205a9fe198101d603f5de37bfa3",
  "first_name": "John",
  "last_name": "Bohnhamn",
  "company": {
    "name": "ACME North America"
  }
}

    Opcional - get()

    Retorna o registro dentro do objeto Opcional ou gera um erro se a consulta não retornar um registro.

    Tabela 7. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 8. Retorna
    Tipo Descrição
    Qualquer O registro dentro do objeto Opcional. Se o valor for nulo ou indefinido, o sistema emitirá um erro.

    Este exemplo mostra como obter o valor de um único registro.

    var value = new global.GlideQuery('sys_user')
    .selectOne('first_name') //Returns the result of the query inside an Optional object
    .get(); //Calls Optional.get() on the Optional object

gs.info(JSON.stringify(value));

    Saída:

    {
   "first_name":"fred",
   "sys_id":"005d500b536073005e0addeeff7b12f4"
}

    Opcional - ifPresent(Function fn)

    Aplica uma função ao registro em um objeto opcional. Se o objeto opcional não contiver um registro, a função não será executada.

    Tabela 9. Parâmetros
    Nome Tipo Descrição
    fn Função A função a ser aplicada ao registro no objeto Opcional.
    Tabela 10. Retorna
    Tipo Descrição
    Nenhum

    Este exemplo mostra como imprimir um valor se ele existir.

    var user = new global.GlideQuery('sys_user')
    .where('sys_id', 'f682abf03710200044e0bfc8bcbe5d38')
    .selectOne('zip')
    .ifPresent(function (user) {
      gs.info('Zip Code: ' + user.zip);
    });

    Opcional - isEmpty()

    Retorna verdadeiro se o objeto Opcional estiver vazio.

    Tabela 11. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 12. Retorna
    Tipo Descrição
    Booliano

    Sinalizador que indica se o resultado de uma consulta contém um valor.

    Valores válidos:
    • verdadeiro: a consulta retorna nulo ou indefinido.
    • falso: a consulta retorna um valor.

    Este exemplo mostra como verificar se o resultado de uma consulta está vazio.

    var checkEmpty = new global.GlideQuery('sys_user')
    .where('last_name', 'Barker')
    .selectOne()
    .isEmpty();

gs.info(checkEmpty);

    Saída:

    true

    Opcional - isPresent()

    Verifica se um objeto Opcional contém um valor.

    Tabela 13. Parâmetros
    Nome Tipo Descrição
    Nenhum
    Tabela 14. Retorna
    Tipo Descrição
    Booliano

    Sinalizador que indica se o resultado de uma consulta contém um valor.

    Valores válidos:
    • verdadeiro: a consulta retorna um valor.
    • falso: a consulta retorna nulo ou indefinido.

    Este exemplo mostra como verificar se uma consulta retorna um resultado.

    var checkPresent = new global.GlideQuery('sys_user')    
   .where('last_name', 'Luddy')
   .selectOne('first_name')
   .isPresent();

gs.info(checkPresent);

    Saída:

    true

    Opcional - preguiçoso (Função preguiçosoGetFn)

    Retorna um novo objeto Opcional. Em vez de conter o registro, o objeto contém uma função para obter o registro que só é chamado se e quando solicitado no código.

    Use este método para atrasar a obtenção do valor até que seja necessário. Você pode fazer isso se estiver solicitando o valor de uma origem lenta e não quiser tornar seu código desnecessariamente lento. Caso contrário, você pode retornar um objeto Opcional usando as APIs GlideQuery e Stream.

    Nota:
    Este método é estático. Você não precisa de uma instância da classe para usar este método.
    Tabela 15. Parâmetros
    Nome Tipo Descrição
    preguiçosoGetFn Função Função que retorna um único registro como resultado de uma consulta. Por exemplo: 
    var userGr = new GlideRecord('sys_user');
    Tabela 16. Retorna
    Tipo Descrição
    Opcional Objeto que contém o resultado da consulta no formato Opcional<result> .

    Este exemplo mostra como obter um objeto Opcional com base em uma consulta GlideRecord.

    var userOptional = global.Optional.lazy(function () {
    var userGr = new GlideRecord('sys_user');
    userGr.setLimit(1);
    userGr.query();
    return userGr.next() ? userGr.getUniqueValue() : null;
});

gs.info(userOptional);

    Saída:

    Optional<005d500b536073005e0addeeff7b12f4>

    Opcional - map(Função fn)

    Aplica uma função ao resultado de uma consulta.

    Tabela 17. Parâmetros
    Nome Tipo Descrição
    fn Função Função a ser aplicada ao resultado da consulta.
    Tabela 18. Retorna
    Tipo Descrição
    Opcional Objeto que contém os resultados da consulta atualizados pela função no formato Opcional<result> .

    Este exemplo mostra como aplicar uma função que transforma um valor em maiúsculas no resultado de uma consulta.

    var value = new global.GlideQuery('sys_user')
    .whereNotNull('first_name')
    .selectOne('first_name')
    .map(function (user) {
	       return user.first_name.toUpperCase();
    });

gs.info(value);

    Saída:

    Optional<ABEL>

    Opcional - de (qualquer valor)

    Encapsula um determinado valor em um objeto Opcional. Por exemplo, você pode encapsular o resultado de uma consulta GlideRecord em um objeto opcional para usar os métodos associados.

    Nota:
    Este método é estático. Você não precisa de uma instância da classe para usar este método.
    Tabela 19. Parâmetros
    Nome Tipo Descrição
    valor Qualquer Valor dentro do objeto Opcional.
    Tabela 20. Retorna
    Tipo Descrição
    Opcional Objeto que contém o valor passado no formato Opcional<value> .

    Este exemplo mostra como gerar um objeto Opcional com base em uma consulta GlideRecord.

    var now_GR = new GlideRecord('task');
now_GR.addQuery('approval', 'not requested'); 
now_GR.query();
var optional;
if (now_GR.next()) {
optional = Optional.of(now_GR.getUniqueValue());
} else {
    optional = Optional.empty("no results");
}

gs.info(optional.get());

    Saída:

    00c269162d761010f87708b56757cbb3

    Opcional - orElse(Any defaultValue)

    Adiciona um valor padrão ao objeto Opcional se a consulta não retornar resultados.

    Tabela 21. Parâmetros
    Nome Tipo Descrição
    defaultValue Qualquer Valor no objeto Opcional se a consulta não retornar resultados.
    Tabela 22. Retorna
    Tipo Descrição
    Qualquer Valor no objeto Opcional se a consulta não retornar resultados.

    Este exemplo mostra como retornar um valor, mesmo quando a consulta está incorreta.

    var user = new global.GlideQuery('sys_user')
    .get('1234', ['first_name', 'last_name'])
    .orElse({ first_name: 'Default', last_name: 'User' });

gs.info(JSON.stringify(user))

    Saída:

    {
   "first_name":"Default",
   "last_name":"User"
}